Session Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:The Session Lifecycle governs the creation, persistence, and restoration of reasoning sessions within the Sequential Thinking MCP server. It manages the transition of data from ephemeral memory into durable Markdown storage located in the memory-bank/ directory.
The UnifiedSessionManager orchestrates this lifecycle. It ensures that thoughts, memories, and architecture decisions remain available across different agent interactions. Sources: session_manager.py:27-40, README.md:1-5
Session Initialization and Creation
The lifecycle begins when the UnifiedSessionManager initializes the storage structure. It creates specific directories for sessions, memories, and patterns. If the index.md file is missing, the manager generates a new registry to track active and archived sessions. Sources: session_manager.py:42-52, CLAUDE.md:73-80
You start a session by providing a problem statement and success criteria. The system creates a UnifiedSession object and assigns a unique ID. It then saves the initial state as a Markdown file. Sources: session_manager.py:54-73, tests/test_session_manager.py:38-51
Data Flow for Session Creation
This diagram shows how a new session moves from the tool call into persistent storage.
Active Session Management
An active session allows for the iterative addition of thoughts, memories, and architectural decisions. Each addition triggers a write operation to ensure persistence. Sources: session_manager.py:171-180, mcp_tools.py:41-59
Thought and Branch Management
Thoughts represent individual reasoning steps. You can organize thoughts into branches to explore alternative solutions. A branch references a specific from_thought_id. Merging a branch appends a notification to a target thought, linking the alternative path back to the main reasoning chain. Sources: session_manager.py:182-209, session_manager.py:211-253
Memory Persistence
Memories carry higher durability than thoughts. When you store a memory, the system performs two actions:
- It appends the memory data to the session Markdown file.
- It creates a standalone Markdown file in
memory-bank/memories/for cross-session retrieval. Sources: session_manager.py:255-274, CLAUDE.md:76
Component Relationships
This class diagram represents the relationships within a single session during its active state.
Sources: models.py, session_manager.py:75-132
Session Restoration and Loading
The lifecycle supports continuity through the load_session function. When you load a session, the UnifiedSessionManager reads the Markdown file and parses the content back into a UnifiedSession object. Sources: session_manager.py:465-485, tests/test_session_manager.py:253-270
Loading Logic
- The manager validates the existence of the session file.
- The
_parse_session_markdownmethod uses regex to extract the problem statement, criteria, and constraints. - It iterates through thought blocks and architecture decisions to rebuild the session state.
- It calls
_load_session_memoriesto re-hydrate memory objects from the standalone memory files. Sources: session_manager.py:503-625
Session Analysis and Export
At any point in the lifecycle, you can analyze the session state. The system provides metadata including the total count of thoughts, memories, and decisions. Sources: session_manager.py:408-419, mcp_tools.py:199-204
You can export the session into external formats. The export_session tool generates files outside the primary memory-bank/ if requested, though internal consistency is maintained within the registry. Sources: mcp_tools.py:151-185, tests/test_mcp_tools.py:192-212
Summary Table: Session Lifecycle Tools
| Action | Function | Storage Effect |
|---|---|---|
| Start | start_session | Creates sessions/{id}.md and updates index.md |
| Reason | add_thought | Updates sessions/{id}.md |
| Remember | store_memory | Updates sessions/{id}.md and creates memories/{id}.md |
| Branch | create_branch | Updates sessions/{id}.md |
| Restore | load_session | Reads Markdown and populates current_session |
| Analyze | analyze_session | Returns JSON metadata from current object |
Sources: session_manager.py:54-280, mcp_tools.py:23-204
Conclusion
The Session Lifecycle ensures that reasoning is not lost between agent turns. By treating Markdown as the "canonical human truth," the system allows for both machine-driven updates and manual human inspection of the reasoning process. This structure supports complex, long-running coding tasks by maintaining a stable, retrievable history of all thoughts and decisions. Sources: README.md:17-25, CLAUDE.md:21-27