Session Manager Operations
Relevant source files
The following files were used as context for generating this wiki page:
Session Manager Operations encompass the business logic and persistence mechanisms for the sequential-thinking-mcp-v2 project. The UnifiedSessionManager class manages the lifecycle of reasoning sessions, including thought generation, memory storage, and architectural decision tracking. It serves as the core orchestration layer between the Model Context Protocol (MCP) tool handlers and the physical Markdown-based storage.
Sources: session_manager.py:27-46, mcp_tools.py:12-15, README.md:126-130
Core Architecture
The system follows a layered architecture where the UnifiedSessionManager acts as the central engine for state management. It persists all data as Markdown files within a structured memory-bank directory.
Component Relationship
The diagram shows the 5-layer call path from the MCP client to the physical storage layer.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:38-42, session_manager.py:30-35, README.md:120-130
Storage Structure
The UnifiedSessionManager initializes and maintains the following directory structure:
| Path | Purpose |
|---|---|
memory-bank/sessions/ | Contains detailed Markdown files for individual reasoning sessions. |
memory-bank/memories/ | Stores standalone memory artifacts for cross-session retrieval. |
memory-bank/patterns/ | Reserved for storing reusable code and logic patterns. |
memory-bank/index.md | Acts as a registry for active and archived sessions. |
Sources: session_manager.py:31-36, session_manager.py:48-54, CLAUDE.md:73-77
Session Lifecycle Management
A session begins with a defined problem and success criteria. The manager tracks the "current_session" in memory while synchronizing all updates to the filesystem.
Session Initialization Flow
The sequence diagram illustrates the synchronous creation of a session and its immediate persistence to disk.
Sources: session_manager.py:61-82, mcp_tools.py:17-43, tests/test_session_manager.py:46-59
Key Methods
- start_session: Initializes a new
UnifiedSessionobject, saves it to a file, and sets it as the active session. - load_session: Parses a Markdown file by ID, hydrates a session object, and loads associated memory files.
- list_sessions: Scans the index file or the sessions directory to return metadata about available sessions.
- analyze_session: Generates summary statistics (total thoughts, memories, branches) for the active session.
Sources: session_manager.py:61-82, session_manager.py:342-368, session_manager.py:304-339, session_manager.py:291-302
Reasoning and Memory Operations
The manager facilitates structured thinking through thoughts and branches, as well as durable knowledge through memories.
Thinking and Branching Logic
Thoughts are sequential reasoning steps. Branches allow the system to explore alternative solutions without polluting the main reasoning path.
This diagram represents how branches diverge from specific thoughts to explore alternative reasoning paths.
Sources: session_manager.py:166-218, tests/test_session_manager.py:112-146
Memory Persistence
Unlike thoughts which are primarily stored inside session files, Memory objects have dual persistence. They are embedded in the session Markdown and written as standalone files for cross-session indexing.
# session_manager.py:220-227
def store_memory(self, content: str, confidence: float = 0.8, code_snippet: str = "",
language: str = "", tags: str = "") -> str:
if not self.current_session:
raise ValueError("No active session")
memory = Memory(
session_id=self.current_session.id,
content=content,
confidence=confidence,
code_snippet=code_snippet,
language=language,
tags=tags.split(",") if tags else [],
)
self.current_session.memories.append(memory)
self._save_memory_to_file(memory) # Standalone file
self._save_session_to_file(self.current_session) # Session update
return memory.id
Sources: session_manager.py:220-237, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:44-48
Data Querying and Retrieval
The manager provides filtering capabilities for retrieved memories based on tags or content.
Query Parameters
| Parameter | Logic | Description |
|---|---|---|
tags | Comma/Pipe separator | Performs "OR" search by default; uses & for "AND" logic. |
content_contains | Substring or Regex | Searches memory content; supports /pattern/ for regex. |
Sources: session_manager.py:251-267, mcp_tools.py:101-118
Package and Decision Tracking
For coding-specific sessions, the manager automates package discovery and formalizes architectural decisions.
- explore_packages: Uses
importlib.metadatato scan installed Python distributions and matches them against a task description to calculate relevance scores. - record_decision: Captures the context, options considered, chosen option, and rationale for architectural changes. This is stored in the
Architecture Decisionssection of the session Markdown.
Sources: session_manager.py:440-458, session_manager.py:270-289, mcp_tools.py:120-141
Summary
Session Manager Operations provide a robust, local-first state management system for reasoning agents. By using Markdown as the canonical source of truth, the system ensures that reasoning paths and project memories remain human-readable while supporting complex programmatic operations like branching, merging, and semantic querying.
Sources: README.md:33-40, CLAUDE.md:21-25