Layered Memory Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Layered Memory Architecture organizes project data into distinct tiers to support structured reasoning, session persistence, and semantic recall for coding agents. It separates human-maintained documentation (canonical truth) from machine-generated artifacts (semantic recall) and ephemeral processing states (reasoning model). This architecture ensures that long-running tasks maintain context without overloading the active token window.
Sources: README.md:1-8, CLAUDE.md:21-27
Storage and Retrieval Layers
The system divides data ownership across specialized components to prevent retrieval systems from overlapping or conflicting. Each layer has specific responsibilities for different types of artifacts.
Architectural Components
| Component | Responsibility | Format/Storage |
|---|---|---|
| Markdown Layer | Canonical human truth (Design docs, ADRs, module maps) | .md files in memory-bank/ |
| qmd | Retrieval for canonical documentation and collections | Indexed document search |
| Zvec | Semantic retrieval for promoted memory and non-doc artifacts | Vector-based search |
| Metadata Store | Lifecycle tracking (confidence, evidence, promotion status) | Structured store |
| Cloud Overlay | Optional continuity layer for remote access | Cloud provider sync |
Sources: README.md:14-22, README.md:37-43, CLAUDE.md:29-35
Data Flow Diagram
The following diagram shows how information flows from the Model Context Protocol (MCP) interface into the various storage layers through the UnifiedSessionManager.
Memory Model and Promotion
The architecture distinguishes between disposable data and durable knowledge. Only information that meets specific criteria becomes a permanent part of the memory bank.
Reasoning Lifecycle
- Scratch Reasoning: Ephemeral, local, and bounded data used for immediate processing.
- Checkpoint Summaries: Compact recovery artifacts generated at subtask boundaries.
- Promoted Conclusions: Reusable machine memory derived from reasoning.
- Canonical Docs: Durable human-maintained truths like Architectural Decision Records (ADRs).
Sources: README.md:47-52, CLAUDE.md:39-44
Promotion Gating
The system prevents raw chain-of-thought data from cluttering long-term storage. To become durable memory, an artifact must satisfy:
- Evidence: Concrete proof of the finding.
- Confidence: High certainty score (default baseline is 0.8).
- Stability: Value that persists beyond the current task.
- Reuse: Likely future utility in different contexts.
Sources: README.md:54-58, models.py:38-42, CLAUDE.md:45-46
Session Persistence
The UnifiedSessionManager orchestrates the persistence of reasoning sessions into the memory-bank/ directory.
Session Structure
A UnifiedSession acts as the aggregate root for all related data objects.
Sources: models.py:16-30, session_manager.py:65-151
Storage Implementation
The UnifiedSessionManager implements file-based persistence using the following structure:
- Sessions: Stored in
memory-bank/sessions/{uuid}.md. - Memories: Stored as standalone files in
memory-bank/memories/{uuid}.md. - Index: A central
index.mdtracks active and archived sessions.
Sources: session_manager.py:31-40, session_manager.py:246-271, README.md:120-130
Token and Context Management
The architecture treats token ceilings as a first-class design constraint to maintain performance.
Management Policies
- Active Context Ceiling: Targeted at
64Ktokens. - Compaction Trigger: Compresses context when it reaches
45Ktokens. - Handoff Bundles: Passes summaries and compact bundles between agents instead of raw transcripts.
- On-Demand Retrieval: Scopes retrieval to the active task rather than preloading the entire codebase.
Sources: README.md:65-71, CLAUDE.md:48-52
Integration Interface
The Model Context Protocol (MCP) provides the stable interface for interacting with the layered memory.
| Tool Name | Action |
|---|---|
retrieve_context | Retrieves task-specific context from indices. |
promote_memory | Gathers evidence to move data to durable storage. |
summarize_session | Generates a compact recovery artifact. |
search_docs | Queries the qmd index for canonical truths. |
search_memory | Queries the Zvec index for semantic matches. |
Sources: README.md:79-88, CLAUDE.md:55-57
Summary
The Layered Memory Architecture ensures the sequential-thinking-mcp-v2 project provides a reliable foundation for agentic workflows. By separating ephemeral reasoning from durable canonical truth and utilizing specialized retrieval layers (qmd, Zvec, and Markdown), the system maintains high data integrity while operating within strict token limits.
Sources: README.md:1-25, CLAUDE.md:21-46