Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
sequential-thinking-mcp-v2 is a local Model Context Protocol (MCP) server that enables structured reasoning, session persistence, and project memory. The system manages complex problem-solving by organizing thoughts into branches, recording architectural decisions, and persisting findings as markdown snapshots within a local memory-bank/ directory.
The current implementation serves as a transition from a markdown-only persistence model to a layered memory architecture. It aims to solve the limitations of long-running coding-agent tasks by providing mechanisms for semantic recall, checkpointing, and agent handoffs.
Sources: README.md:1-25, CLAUDE.md:3-10
System Architecture
The codebase follows a 5-layer architecture to handle communication between the MCP client and the local storage system.
Architectural Layers
- Transport Layer: Uses the
mcplibrary to handle stdio transport for JSON-RPC communication. - Dispatch Layer (
main.py): Manages MCP protocol dispatch and tool registration. - Adapter Layer (
mcp_tools.py): Converts MCP tool calls into business logic requests for the session manager. - Business Logic Layer (
session_manager.py): Orchestrates session state, persistence, and package discovery. - Domain Model Layer (
models.py): Defines dataclasses for thoughts, memories, branches, and decisions.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:Thought 1, CLAUDE.md:70-76
Request Flow
The following diagram illustrates the path of a tool invocation from the client to the persistence layer:
This diagram shows the synchronous flow of data through the layers, where errors are caught in the dispatch layer to return formatted error messages to the client.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:Thought 3
Core Components and Data Models
The system centers on the UnifiedSession aggregate root, which encapsulates all data related to a specific reasoning task.
Data Entities
| Entity | Description | Primary Fields |
|---|---|---|
| UnifiedSession | The central container for a reasoning task. | id, problem, success_criteria, thoughts, memories, branches. |
| Thought | An individual reasoning step. | id, session_id, branch_id, content, confidence. |
| Branch | A parallel reasoning path. | id, name, from_thought_id, purpose. |
| Memory | Promoted durable artifact. | id, session_id, content, code_snippet, tags. |
| Decision | Record of an architectural choice. | id, decision_title, context, chosen_option, rationale. |
Sources: models.py:10-185, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:Thought 2
Entity Relationships
The relationship between sessions and their child entities is strictly hierarchical, though Memory objects have dual persistence.
The UnifiedSession owns the lifecycle of all entities. While thoughts live on the session, branches store the ID of the thought where the divergence occurred.
Sources: models.py:10-150, session_manager.py:80-150
Memory and Persistence
The server uses a local memory-bank/ directory for persistence. All state is stored in human-readable Markdown format.
Storage Layout
memory-bank/sessions/: Contains markdown files representing full session snapshots.memory-bank/memories/: Contains standalone files for promoted durable memories.memory-bank/index.md: Acts as a registry for active and archived sessions.
Sources: CLAUDE.md:78-83, session_manager.py:27-38
Memory Promotion Logic
The system distinguishes between ephemeral scratch reasoning and durable conclusions.
- Scratch Reasoning: Stored within the session markdown but not promoted.
- Promoted Memories: Extracted to standalone files in
memory-bank/memories/for cross-session retrieval. - Handoffs: Checkpoint summaries used to transition context between agents.
Sources: README.md:55-68, session_manager.py:207-228
Tooling and Functionality
The MCPToolsHandler exposes 12 core tools to MCP clients for managing the reasoning lifecycle.
Key MCP Tools
| Tool | Action | File Reference |
|---|---|---|
start_session | Initializes a new problem-solving context. | mcp_tools.py, session_manager.py:53 |
add_thought | Appends a reasoning step to the current session or branch. | session_manager.py:129 |
create_branch | Forks reasoning from a specific thought. | session_manager.py:170 |
store_memory | Saves a specific finding as a durable memory. | session_manager.py:207 |
record_decision | Logs an architecture decision with rationale. | session_manager.py:339 |
explore_packages | Automatically discovers relevant libraries for a task. | session_manager.py:309 |
Sources: session_manager.py:53-350, tests/test_integration.py:32-150
Target Memory Architecture
The project is transitioning toward a more robust retrieval model.
- Markdown: Remains the canonical "human truth" (ADRs, design docs).
- qmd: Handles retrieval for document collections.
- Zvec: Manages semantic retrieval for non-doc artifacts and promoted memories.
- Metadata Store: Tracks lifecycle states like confidence, evidence, and staleness.
Sources: README.md:27-52, CLAUDE.md:27-42
Summary
sequential-thinking-mcp-v2 provides a structured framework for AI agents to conduct long-form reasoning. By combining an hierarchical data model (Sessions, Thoughts, Branches) with a local markdown-based storage system, it ensures that complex investigations remain traceable, persistent, and recoverable across agent restarts. The current 4-file core architecture supports 100% of the 12 core tools, while the project roadmap prepares for advanced semantic retrieval and token context management.
Sources: memory-bank/memories/1eba30a1-6283-44a2-a372-82e9fe92460d.md, README.md:120-130