Current State vs Target Architecture
Relevant source files
The following files were used as context for generating this wiki page:The Sequential Thinking MCP v2 project is transitioning from a markdown-based storage system to a layered memory and reasoning architecture. The current implementation focuses on local persistence through structured markdown files, while the target architecture introduces semantic retrieval, explicit memory promotion, and cloud-assisted scalability.
This document outlines the differences between the existing transitional codebase and the approved architectural design documented in the project's strategy plans.
Sources: README.md:3-9, CLAUDE.md:8-14
Memory Storage Layers
The current system persists all session data—including thoughts, branches, and decisions—into a flat markdown directory structure. The target architecture replaces this with a specialized retrieval split to prevent overlapping systems from conflicting.
Storage Comparison
| Component | Current State (Transitional) | Target Architecture |
|---|---|---|
| Canonical Truth | Markdown files in memory-bank/ | Markdown remains the human-readable authority. |
| Document Retrieval | Regex-based parsing of markdown files. | qmd indexes and retrieves document collections. |
| Semantic Recall | Not implemented. | Zvec indexes promoted artifacts and non-doc objects. |
| Metadata Tracking | Basic fields in dataclasses. | Structured store for confidence, evidence, and sync state. |
| Persistence | Synchronous file writes to .md files. | Batched/queued indexing with cloud-first, local-fallback. |
Sources: README.md:23-45, CLAUDE.md:16-25, session_manager.py:30-45
Current Data Flow Diagram
The current architecture operates via a direct path from the MCP tool interface to the local file system.
Reasoning and Promotion Model
The reasoning model is shifting from a comprehensive log of all thoughts to a gated promotion system. Currently, the session_manager.py records every Thought and Memory object created via tools.
Reasoning Lifecycle
The target architecture enforces a distinction between ephemeral reasoning and durable memory:
- Scratch Reasoning: Ephemeral, bounded, and disposable.
- Checkpoint Summaries: Compact recovery points for long tasks.
- Promoted Conclusions: Reusable machine memory requiring evidence and confidence.
- Canonical Docs: Durable human truth (ADRs, Runbooks).
Sources: README.md:47-64, CLAUDE.md:27-32
Memory Promotion Sequence
This diagram illustrates the target logic for promoting raw reasoning into durable project memory.
Sources: README.md:58-64, CLAUDE.md:32-34
MCP Tool Interface Evolution
The project currently exposes 12 tools through main.py and mcp_tools.py. The target architecture seeks to consolidate these into higher-level workflows focused on context management and handoffs.
Tool Mapping
| Existing Tool (Current) | Target Interface Goal |
|---|---|
add_thought | retrieve_context |
store_memory | promote_memory |
create_branch | summarize_session |
explore_packages | map_changed_modules |
query_memories | search_memory / search_docs |
Sources: README.md:66-77, CLAUDE.md:73-80, session_manager.py:169-210
Token and Context Management
The current system has no formal compaction or token ceiling enforcement, relying on local file size. The target architecture introduces strict context boundaries.
- Active Context Ceiling: 64K tokens.
- Compaction Trigger: 45K tokens.
- Mechanism: Summarize old context and pass handoff bundles instead of raw transcripts.
Sources: README.md:79-90, CLAUDE.md:38-40
Implementation Status
As of October 2023, the project is approximately 85% complete regarding its transitional markdown implementation.
# session_manager.py:30-45
# Current initialization logic showing purely local markdown setup
def __init__(self, memory_bank_path: str = "memory-bank"):
self.logger = logging.getLogger(__name__)
self.memory_bank_path = Path(memory_bank_path)
self.sessions_dir = self.memory_bank_path / "sessions"
self.memories_dir = self.memory_bank_path / "memories"
self.patterns_dir = self.memory_bank_path / "patterns"
self.index_file = self.memory_bank_path / "index.md"
self.current_session: Optional[UnifiedSession] = None
Sources: session_manager.py:30-40, memory-bank/memories/1eba30a1-6283-44a2-a372-82e9fe92460d.md:12-25
Conclusion
The Sequential Thinking MCP v2 is moving away from a "chatty" markdown recorder toward a sophisticated memory agent. While the current implementation provides solid CRUD operations for sessions and thoughts, the target architecture addresses weaknesses in semantic recall and context management for large codebases. Implementation efforts now focus on adding the metadata store and semantic indexing layers described in the target design.
Sources: README.md:16-21, CLAUDE.md:86-93