Memory Bank Directory Structure

Relevant source files

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

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

The Memory Bank Directory Structure defines the local persistence layer for the Sequential Thinking MCP server. It organizes structured reasoning, session history, and atomic memories into human-readable Markdown files to ensure project continuity and transparency.

Sources: README.md:1-5, session_manager.py:27-32, CLAUDE.md:67-73

Core Directory Layout

The memory-bank/ directory acts as the root for all persisted data. The UnifiedSessionManager initializes this structure and ensures all subdirectories exist during startup.

Path	Component	Description
memory-bank/	Root Directory	The base folder for all reasoning and memory data.
memory-bank/sessions/	Sessions Directory	Contains full reasoning logs, thoughts, and architecture decisions.
memory-bank/memories/	Memories Directory	Stores atomic, reusable knowledge artifacts as individual files.
memory-bank/patterns/	Patterns Directory	Reserved for storing recurring code or reasoning patterns.
memory-bank/index.md	Session Registry	A central index tracking active and archived sessions.

Sources: session_manager.py:36-43, CLAUDE.md:67-73

Directory Visualization

The following diagram illustrates the relationship between the server logic and the physical file structure.

The diagram shows how the UnifiedSessionManager orchestrates data flow into specific subdirectories within the memory-bank root.

Sources: session_manager.py:27-43, CLAUDE.md:67-73

The Sessions Directory (sessions/)

The sessions/ directory stores comprehensive logs of specific reasoning tasks. Each file uses a UUID as its filename (e.g., 3e352229-83f2-4d8e-9416-a813fdc20949.md) and contains the full context of a problem-solving attempt.

Session File Content

Each session file includes the following sections:

• Metadata: Session ID, Type (Coding or General), and Timestamps.
• Problem Statement: The core task or query.
• Thoughts: A chronological list of reasoning steps, including confidence scores and dependencies.
• Architecture Decisions: Records of chosen options, rationales, and consequences.
• Discovered Packages: Relevant libraries found during the session.

Sources: session_manager.py:82-143, models.py:16-29

The Memories Directory (memories/)

The memories/ directory contains standalone Markdown files for atomic knowledge artifacts. Unlike sessions, which track a process, memories represent durable conclusions or code snippets meant for long-term retrieval.

Memory Persistence Logic

1. Dual Storage: When you store a memory, the system adds it to the active session file and creates a standalone file in memories/.
2. Re-hydration: On reload, the UnifiedSessionManager hydrates the UnifiedSession object by reading files directly from the memories/ directory, matching them by session_id.
3. Atomic Retrieval: Tools like query_memories search these individual files for specific tags or content patterns.

Sources: session_manager.py:221-255, session_manager.py:461-487, CLAUDE.md:75-77

The Session Registry (index.md)

The index.md file serves as a central registry for the entire Memory Bank. It provides a human-readable list of all sessions known to the system.

Registry Structure

The file is partitioned into sections:

• Active Sessions: Recently modified or ongoing tasks, formatted as a list with IDs, problem titles, and dates.
• Archived Sessions: Completed tasks moved out of the active flow.
• Memory Collections: Summaries of stored knowledge groups.

Sources: session_manager.py:45-48, session_manager.py:163-176, memory-bank/index.md:1-15

File Persistence Flow

This sequence diagram describes how a tool call results in a file system update within the Memory Bank structure.

The flow ensures that every piece of information is captured in both the specific memory artifact and the broader session context.

Sources: session_manager.py:221-240, mcp_tools.py:84-96

Summary of Storage Standards

The Memory Bank follows a "Markdown as Canonical Truth" policy. All data structures defined in models.py must be serializable into the specific Markdown formats processed by the UnifiedSessionManager parsing logic. This approach allows users to manually inspect or edit the reasoning history without breaking server functionality, provided the section headers and metadata tags remain intact.

Sources: CLAUDE.md:23, session_manager.py:348-460