Session Registry (index.md)

Relevant source files

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

• memory-bank/index.md
• session_manager.py
• mcp_tools.py
• models.py
• README.md
• tests/test_session_manager.py

The Session Registry (index.md) tracks all reasoning sessions within the sequential-thinking-mcp-v2 server. It provides a human-readable index of active and archived sessions, memory collections, and code patterns stored in the memory bank. The UnifiedSessionManager maintains this file to ensure session persistence and discoverability across different tool invocations.

Sources: memory-bank/index.md:1-17, session_manager.py:46-49, README.md:120-123

Architecture and Purpose

The registry acts as the central entry point for the file-based storage system. It allows the UnifiedSessionManager to list historical sessions and reload the last active state when the server initializes.

Structural Components

The file follows a structured Markdown format with specific sections for different types of metadata:

Section	Description
Active Sessions	Lists ongoing sessions with IDs, titles, types, and creation dates.
Archived Sessions	Reserved for completed sessions moved out of active rotation.
Memory Collections	References standalone memory artifacts.
Code Patterns	Links to reusable architectural or coding patterns.

Sources: memory-bank/index.md:3-13, session_manager.py:51-53

Logical Data Flow

The UnifiedSessionManager orchestrates all updates to the registry. When a user starts a new session or the system saves an existing one, the manager appends or updates entries in index.md.

The diagram shows the lifecycle of a registry update during session creation.
Sources: session_manager.py:44-53, session_manager.py:127-142

Management Logic

The UnifiedSessionManager class contains the core logic for interacting with the registry file.

Initialization and Recovery

During class instantiation, the manager ensures the directory structure exists. It checks for index.md and creates a default template if the file is missing. The manager then calls _load_last_active_session(), which reads index.md to identify and load the most recent session.

Sources: session_manager.py:35-42, session_manager.py:535-541

Entry Formatting

The manager uses a specific regex-compatible string format to record sessions. Each entry follows this pattern:
- **[SESSION_ID]**: [PROBLEM_STATEMENT] ([TYPE], [YYYY-MM-DD])

# From session_manager.py
def _update_index_with_session(self, session: UnifiedSession):
    if not self.index_file.exists():
        self._create_index_file()
    current_content = self.index_file.read_text()
    session_entry = f"- **{session.id}**: {session.problem} ({session.session_type.value}, {session.created_at.strftime('%Y-%m-%d')})"
    if session.id in current_content:
        return
    new_content = current_content.replace(
        "## Active Sessions\n\n", f"## Active Sessions\n\n{session_entry}\n\n"
    )
    # ... writes updated content ...

Sources: session_manager.py:127-138

Session Discovery

The list_sessions() method parses index.md using regular expressions to return a list of available sessions to the MCP client. If the index file is corrupted or unreadable, the manager falls back to scanning the sessions/ directory for .md files.

Sources: session_manager.py:270-305, mcp_tools.py:175-180

Integration with MCP Tools

The MCPToolsHandler exposes the registry data through several tool endpoints. This allows agents to navigate historical context without manual file inspection.

Tool	Action on Registry
start_session	Triggers _update_index_with_session to add a new entry.
list_sessions	Reads index.md to provide a list of session metadata.
load_session	Uses the ID from the registry to locate the corresponding session file.

The sequence diagram illustrates how an agent retrieves the list of sessions from the registry via the MCP interface.
Sources: mcp_tools.py:175-180, session_manager.py:270-285, tests/test_session_manager.py:257-270

Conclusion

The Session Registry (index.md) serves as the backbone for session persistence in the sequential-thinking-mcp-v2 project. By maintaining a structured Markdown index, it enables the system to provide a searchable history of reasoning tasks while keeping the storage layer human-readable and easily inspectable.

Sources: README.md:12-16, memory-bank/index.md:1-17