Memory Bank MCP Server

This is a Model Context Protocol (MCP) server designed to manage project-specific "memory bank" data. It utilizes an SQLite database to store and retrieve contextual information related to a project, such as product background, decision logs, progress updates, etc.

Features

• Project-Based: Maintains a separate memory bank for each specified project path.
• SQLite Storage: Stores data in a memory-bank/memory.db file within the project directory, providing structured and efficient access.
• Modular: Encapsulates memory bank management logic into an independent MCP service.
• Standardized Interface: Provides a set of MCP tools for interacting with the memory bank.

Running with npx (Recommended)

This server is published to npm and can be run directly using npx without manual cloning, installation, or building.

Running the Server

The primary way to run this server is using npx, which executes the package directly from the npm registry:

npx @telagod/memory-bank-mcp-server

Node.js Version Requirement:

• You need Node.js version 18.0.0 or higher (>=18.0.0) installed.

Platform-Specific Considerations:

• Windows: If you have Node.js v18+ installed correctly and it's added to your system's PATH environment variable, the npx command should work directly in Command Prompt, PowerShell, or Windows Terminal.

• macOS / Linux / WSL (Windows Subsystem for Linux):

  • Check your Node.js version: Run node -v.
  • Potential Issue: The default Node.js version provided by system package managers (like apt on Ubuntu/Debian) might be outdated (e.g., v12.x). Running npx with an old Node.js version will likely fail.
  • Recommended Solution: Use a Node Version Manager like NVM (Node Version Manager) or NodeSource to install and manage Node.js versions. System repositories often lag behind the latest Node.js releases.
  • Using NVM (Example):
    1. Install NVM (check the official NVM repository for the latest command):

       curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
       

    2. Restart your terminal or run the commands indicated by the NVM installer.
    3. Install a Node.js v18+ version: nvm install 18 (or a specific version like nvm install 18.17.0)
    4. Use the installed version: nvm use 18
    5. Now, the npx @telagod/memory-bank-mcp-server command should work correctly.

This server is typically started automatically by an MCP host application (like Roo Code) based on its configuration (e.g., mcp_settings.json), but the npx command is the underlying method used.

Integration Guide (Using npx)

You can integrate this Memory Bank MCP Server into MCP-enabled applications (like RooCode). Using npx to run the server is recommended.

RooCode Configuration Example

1. Open RooCode's mcp_settings.json configuration file.

2. Add a new server configuration entry to the servers object as shown below. The key (e.g., "memory-bank-server") is the unique identifier you'll use to refer to this server:

   {
     "servers": {
       "memory-bank-server": {
         "name": "Memory Bank Server (npx)",
         "command": "npx",
         "args": [
           "-y",
           "@telagod/memory-bank-mcp-server"
         ],
         "type": "stdio",
         "alwaysAllow": [
           "initialize_memory_bank",
           "get_memory_bank_status",
           "read_memory_bank_section",
           "update_memory_bank_entry"
         ],
         "disabled": false
       }
     }
   }
   

3. Important: Ensure the package name @telagod/memory-bank-mcp-server is correct. If you are using a fork or a different version, update the name accordingly.

4. Optional Arguments: If the server supports additional command-line arguments (like a configuration file path), you can add them as separate strings within the args array after the package name.

5. Save the mcp_settings.json file.

6. Restart RooCode to load the new MCP server.

Other MCP Clients

For other MCP-enabled clients, refer to their documentation on how to configure stdio or SSE type MCP servers launched via the command line. Typically, you will need to provide the npx command and corresponding arguments as shown in the example above.

MCP Tools

The server provides the following MCP tools:

1. initialize_memory_bank

   • Description: Initializes the memory bank storage for the specified project path. Creates the memory-bank/ directory and memory.db file if they do not exist.
   • Input:
     • project_path (string, required): The absolute path to the project.
   • Output: An object containing a status message and the database path.

2. get_memory_bank_status

   • Description: Checks the status of the memory bank for the specified project path (whether the database file exists).
   • Input:
     • project_path (string, required): The absolute path to the project.
   • Output: An object containing exists (boolean), db_path (string), and message (string).

3. read_memory_bank_section

   • Description: Reads entries from a specific section of the memory bank.
   • Input:
     • project_path (string, required): The absolute path to the project.
     • section (string, required): The section to read from (e.g., product_context, decisions, progress, focus, system_patterns).
     • limit (number, optional, default: 10): Maximum number of entries to return.
     • offset (number, optional, default: 0): Offset for pagination.
   • Output: An array of objects representing the records from that section.

4. update_memory_bank_entry

   • Description: Adds a new entry to a specific section of the memory bank.
   • Input:
     • project_path (string, required): The absolute path to the project.
     • section (string, required): The section to update (as above).
     • entry_data (object, required): Data for the new entry. Keys should match the column names of the section's database table (excluding id and timestamp).
       • product_context: { "content": "..." }
       • decisions: { "reason": "...", "outcome": "..." }
       • progress: { "update_summary": "...", "status": "..." }
       • focus: { "area": "...", "details": "..." }
       • system_patterns: { "pattern_name": "...", "description": "..." }
   • Output: An object containing a status message and the ID of the newly inserted entry.

How It Works

The following diagram illustrates the basic workflow of the Memory Bank MCP Server:

graph TD
    Client["Client"] -- "Tool Call\n(e.g., update_entry, section='decisions')" --> MCPServer["Memory Bank MCP Server"]
    MCPServer -- "Parse Request" --> Router{"Router/Logic"}

    subgraph "Database Interaction"
        direction LR
        Router -- "section='product_context'?" --> Table_PC["product_context Table"]
        Router -- "section='decisions'?" --> Table_DEC["decisions Table"]
        Router -- "section='progress'?" --> Table_PROG["progress Table"]
        Router -- "section='focus'?" --> Table_FOC["focus Table"]
        Router -- "section='system_patterns'?" --> Table_SP["system_patterns Table"]

        Table_PC -- "Read/Write Ops" --> SQLiteDB["SQLite DB"]
        Table_DEC -- "Read/Write Ops" --> SQLiteDB
        Table_PROG -- "Read/Write Ops" --> SQLiteDB
        Table_FOC -- "Read/Write Ops" --> SQLiteDB
        Table_SP -- "Read/Write Ops" --> SQLiteDB
    end

    SQLiteDB -- "Operation Result" --> MCPServer
    MCPServer -- "Format & Send Response" --> Client

1. Client Request: The client (e.g., RooCode) initiates a tool call request to the Memory Bank MCP Server, typically including a section parameter (e.g., update_memory_bank_entry with section='decisions').
2. Server Parsing: The server core receives and parses the request.
3. Routing Logic: The server's internal routing logic determines the target database table based on the section parameter in the request.
4. Table Interaction: The request is routed to the appropriate table handling logic (product_context, decisions, progress, focus, or system_patterns).
5. Database Operation: Read or write operations are performed on the selected table within the SQLite database (memory-bank/memory.db).
6. Return Results (DB): The SQLite database returns the result of the operation (e.g., queried data or confirmation of successful insertion).
7. Process & Format: The server core processes the results returned from the database and formats them into an MCP response.
8. Send Response: The server sends the final response back to the client.

Database Structure

The core of the memory bank consists of the following SQLite tables, which collectively store key project information:

• product_context: Stores high-level background information about the product or project, goals, scope, etc. This helps understand the "why" of the project.
• decisions: Records important technical choices, architectural decisions, product direction adjustments, etc. Includes the reasons for decisions, options considered, and the final outcome, providing a basis for future review.
• progress: Tracks key progress during development, status updates, completed tasks, or milestones. This helps understand "how things are going" with the project.
• focus: Defines the current or near-term development focus, key issues to be resolved, or areas requiring special attention. This helps the team stay aligned.
• system_patterns: Records reusable patterns, common solutions, or important design principles identified in the codebase or system architecture. This aids knowledge retention and code consistency.

These tables work together to form a dynamic project "memory bank," capturing the project's evolution and key knowledge points.

Acknowledgements

Parts of the design and inspiration for this project come from the RooFlow project. Thanks for the ideas provided for the MCP ecosystem and AI-assisted development workflows.