Component Overview

Relevant source files

The following files were used as context for generating this wiki page:

• session_manager.py
• mcp_tools.py
• models.py
• README.md
• memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md
• CLAUDE.md
• memory-bank/memories/1eba30a1-6283-44a2-a372-82e9fe92460d.md

Sequential Thinking MCP v2 provides a Model Context Protocol (MCP) server that manages structured reasoning, session persistence, and project memory. The system records thoughts, creates branches for alternative reasoning paths, and stores durable memories using a local-first markdown storage strategy.

Sources: README.md:1-5, memory-bank/memories/1eba30a1-6283-44a2-a372-82e9fe92460d.md:10-15

System Architecture

The codebase follows a 5-layer architecture that separates transport protocols from domain logic and persistence.

1. Transport Layer: Uses the mcp library for stdio-based communication.
2. Dispatch Layer (main.py): Routes MCP tool requests to appropriate handlers.
3. Adapter Layer (mcp_tools.py): Maps tool arguments to business logic methods.
4. Logic Layer (session_manager.py): Manages session lifecycles, branching logic, and memory processing.
5. Domain Models (models.py): Defines the structure for sessions, thoughts, and memories.

Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:28-33, CLAUDE.md:65-72

System Data Flow

This diagram illustrates how a tool request propagates from the user to the file system.

The system captures all tool invocations through main.py, which validates the method exists on MCPToolsHandler before execution.

Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:46-52

Core Components

UnifiedSessionManager

The UnifiedSessionManager class manages all business logic and file system interactions. It ensures the existence of the memory-bank directory structure and handles the conversion between Python objects and Markdown files.

• Persistence: Saves sessions to memory-bank/sessions/ and standalone memories to memory-bank/memories/.
• Directory Management: Enforces a structure including sessions, memories, and patterns.
• Session State: Tracks the current_session object for active reasoning tasks.

Sources: session_manager.py:24-40, CLAUDE.md:79-84

MCPToolsHandler

The MCPToolsHandler serves as the interface between the MCP protocol and the session manager. Each method corresponds to an MCP tool.

Tool Method	Description
start_session	Initializes a new reasoning session with a specific problem and success criteria.
add_thought	Records a discrete step in the reasoning process with a confidence score.
create_branch	Initiates a parallel reasoning path from a specific thought.
store_memory	Records durable information with tags and optional code snippets.
record_decision	Documents an architecture decision including context and rationale.
export_session	Generates a Markdown or JSON export of the current session data.

Sources: mcp_tools.py:16-160, memory-bank/memories/1eba30a1-6283-44a2-a372-82e9fe92460d.md:14-22

Data Models

The system uses Python dataclasses to maintain data integrity before persistence.

UnifiedSession acts as the aggregate root. While Branch objects track alternative paths, Thought objects contain a branch_id to link them to their respective branch.

Sources: models.py:72-238, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:37-42

Memory and Storage Strategy

The system prioritizes human-readable persistence. Markdown acts as the canonical source of truth for all sessions and memories.

Storage Layout

• memory-bank/sessions/: Contains full session history including thoughts and decisions.
• memory-bank/memories/: Contains individual memory files indexed by ID for cross-session retrieval.
• memory-bank/index.md: Serves as the registry for all active and archived sessions.

Sources: session_manager.py:30-36, CLAUDE.md:79-84, memory-bank/index.md:1-12

Session Lifecycle

This sequence diagram shows how the system recovers state during a startup or session load.

Technical Implementation Details

Thought Processing

When adding a thought, the system optionally explores local package metadata if the session type is coding. It calculates a relevance score for installed libraries against the task description.

# From session_manager.py:270-290
def explore_packages(self, task_description: str, language: str = "python") -> List[str]:
    installed_packages = []
    for dist in importlib.metadata.distributions():
        package_name = dist.metadata["name"]
        relevance_score = self._calculate_relevance(package_name, task_description)
        if relevance_score > 0.3:
            # Record package info in session...

Sources: session_manager.py:270-290

Error Handling

The system implements specific exception types including NoActiveSessionError, ValidationError, and StorageError. The MCPToolsHandler catches these exceptions and returns them as structured error messages to the MCP client instead of allowing the server to crash.

Sources: errors.py:1-40, mcp_tools.py:155-160, memory-bank/memories/67944906-43bc-4c85-9424-f2261850bc97.md:15-18

Sequential Thinking MCP v2 ensures that complex agent reasoning remains persistent, branchable, and retrievable through a robust local markdown-based storage architecture.