Zvec Promoted Memory Retrieval
Relevant source files
The following files were used as context for generating this wiki page:
Zvec Promoted Memory Retrieval manages the semantic recall and lifecycle of non-document artifacts within the Sequential Thinking MCP v2 architecture. It identifies and retrieves promoted memory objects, such as investigation summaries and architecture decisions, which represent durable machine-generated conclusions rather than ephemeral scratch reasoning. This system operates as part of a layered memory model that distinguishes between human-maintained "canonical truth" and reusable machine memory.
Sources: README.md:23-38, CLAUDE.md:24-34
Architecture and Memory Layers
The Zvec retrieval system manages semantic artifacts that have been "promoted" from raw session data. While the project uses Markdown as its canonical storage format, retrieval responsibility is split between qmd and Zvec.
- qmd Ownership: Handles retrieval for canonical documents and document collections.
- Zvec Ownership: Handles retrieval for promoted memory artifacts and non-document semantic artifacts.
Sources: CLAUDE.md:26-28, README.md:41-48
Semantic Retrieval Flow
The following diagram illustrates how artifacts move from ephemeral reasoning into the Zvec-managed semantic recall layer.
Zvec targets artifacts that possess stability beyond the current task and high likely reuse value.
Sources: README.md:52-64, CLAUDE.md:36-41
Promotion and Metadata Gating
Promotion to the Zvec layer is not automatic. The system requires specific metadata and evidence before an artifact becomes durable memory.
Promotion Gating Criteria
A structured metadata store tracks the state of artifacts to determine eligibility for retrieval.
| Metric | Description |
|---|---|
| Confidence | Numeric score (0.0 to 1.0) indicating certainty of the conclusion. |
| Evidence | Supporting data or references validating the memory. |
| Promotion Status | State indicating if the artifact is durable or ephemeral. |
| Stability | Persistence of the conclusion beyond the immediate session. |
| Sync State | Coordination between local storage and cloud memory overlays. |
Sources: CLAUDE.md:29-31, 39-41, README.md:46-48, 62-64, session_manager.py:165-171
Lifecycle Management Logic
The UnifiedSessionManager implements this by validating confidence bounds and parsing tags during memory storage.
Sources: session_manager.py:165-180, memory-bank/memories/67944906-43bc-4c85-9424-f2261850bc97.md:12-20
Implementation Details
The retrieval system utilizes UnifiedSessionManager to re-hydrate memories from standalone files. Unlike thoughts, which are primarily session-bound, memories have dual persistence: they are embedded in session files and written as standalone .md files in memory-bank/memories/.
Retrieval Components
- Standalone Memory Files: Located at
memory-bank/memories/{id}.md. - Re-hydration: The system reloads memories from standalone files upon session restoration to ensure continuity.
- Metadata Store: Owns the lifecycle state, including provenance, scope, and staleness.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:32-37, CLAUDE.md:29-31, session_manager.py:465-495
Code Interaction Sequence
The Zvec retrieval process follows a specific call path from the MCP tool interface down to the markdown storage layer.
Conclusion
Zvec Promoted Memory Retrieval establishes a boundary between disposable chain-of-thought and durable, reusable artifacts. By focusing on promoted memories, investigation summaries, and architecture decisions, it ensures that the retrieval system remains efficient and scoped to the active task. This separation prevents the over-saturation of context and facilitates reliable handoffs between agents by prioritizing high-confidence conclusions over raw transcripts.
Sources: README.md:33-38, 52-57, CLAUDE.md:33-34, 43-45