codebase-memory-mcp

A Docker stdio-based MCP Server providing code graph intelligence and memory capabilities.
Inspired by DeusData/codebase-memory-mcp, optimized for token efficiency.

🚀 Token Efficiency

Estimated 20-50x token reduction for structural queries.

Related MCP server: Mono Memory MCP

Features (19 Tools)

📊 Graph Intelligence (NEW - 13 tools)

💾 Memory (Original - 4 tools)

🔍 Codebase Search (Original - 2 tools)

Token-Optimization Roadmap

This roadmap focuses on generic mechanisms that reduce AI token usage by replacing repeated grep/read/reason loops with reusable structured evidence.

Low Cost, High Return ✅ COMPLETED

Delivered in v2.1.0:

• file_summaries schema keyed by project + path + hash

• Auto-generation during index_project / sync_index

• 4 new MCP tools for summary queries

• Token savings: 10-100x for common exploration tasks

Mid Term

Concrete deliverables

• Extend symbols schema to persist ownership relationships directly

• Add edge builders in the parser/indexer for imports and definitions

• Add a detect_changes MCP tool backed by git diff + graph traversal

Long Term

Concrete deliverables

• Add a vector index for file/symbol summaries and blend retrieval with graph constraints

• Introduce module and route nodes in the graph model

• Export reusable project graph artifacts to accelerate first-time sessions

Prioritized Execution Order

1. Add tool routing policy and evidence-first response shaping ✅

2. Add file summary cache keyed by file hash ✅

3. Add owner_symbol_id / parent_symbol_id to support exact ownership queries

4. Add IMPORTS / DEFINES graph edges

5. Add detect_changes for git-aware impact analysis

6. Add hybrid semantic + structural retrieval

Success Metrics

Track roadmap progress using these measurable outcomes:

Quick Start

Build Docker Image

cd /path/to/codebase-memory-mcp
podman build -t codebase-memory-mcp .

With Persistent Data (Recommended)

# Create data directory for persistent indexes
mkdir -p ~/.codebase-memory-data

podman run -i --rm \
  -v "${PWD}:/app/workspace:ro" \
  -v "$HOME/.codebase-memory-data:/app/data" \
  codebase-memory-mcp

VS Code Configuration

Create .vscode/mcp.json in your project root:

Windows Host + WSL Container (Recommended)

For VS Code running on Windows, with Podman/Docker inside WSL:

{
  "servers": {
    "codebase-memory": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "podman", "run", "-i", "--rm",
        "-v", "/mnt/c/Users/YourName/Projects/my-project:/app/workspace:ro",
        "-v", "/home/youruser/.codebase-memory-data:/app/data",
        "codebase-memory-mcp"
      ]
    }
  }
}

Important for Windows + WSL:

1. Replace Ubuntu-22.04 with your WSL distro (run wsl -l -v to list)

2. Replace /mnt/c/Users/YourName/Projects/my-project with your Windows project path converted to WSL format:

   • C:\Users\YourName\Projects → /mnt/c/Users/YourName/Projects

   • D:\code\myapp → /mnt/d/code/myapp

3. Create persistent data directory in WSL:

   wsl -d Ubuntu-22.04 mkdir -p ~/.codebase-memory-data

Windows Host + WSL (Dynamic Workspace Path)

For projects stored in Windows filesystem with dynamic path:

{
  "servers": {
    "codebase-memory": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "bash", "-c",
        "podman run -i --rm -v \"$(wslpath '${workspaceFolder}'):/app/workspace:ro\" -v \"$HOME/.codebase-memory-data:/app/data\" codebase-memory-mcp"
      ]
    }
  }
}

Note: ${workspaceFolder} is a VS Code variable that expands to the Windows path. The wslpath command converts it to WSL format.

Linux / macOS (Native)

With Persistent Storage (Recommended)

{
  "servers": {
    "codebase-memory": {
      "type": "stdio",
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/app/workspace:ro",
        "-v", "${env:HOME}/.codebase-memory-data:/app/data",
        "codebase-memory-mcp"
      ]
    }
  }
}

Without Persistence (Ephemeral)

{
  "servers": {
    "codebase-memory": {
      "type": "stdio",
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/app/workspace:ro",
        "codebase-memory-mcp"
      ]
    }
  }
}

Usage Examples

1. Index Your Project (First Time)

You: "Index this project"
AI: [calls index_project]
→ ✅ Indexed 150 files in 2.3s
   📊 Total: 1,234 symbols, 567 edges
   📁 Types: function=456, class=78, method=234, ...

2. Find Who Calls a Function

You: "Who calls the processOrder function?"
AI: [calls trace_calls(function_name="processOrder", direction="inbound")]
→ Callers of processOrder (depth=3)
   → OrderController.handleOrder (method) - src/controllers/order.ts:45
     → Router.post (function) - src/routes/index.ts:12
   → BatchProcessor.run (method) - src/jobs/batch.ts:89

3. Get Architecture Overview

You: "Give me an overview of this project's architecture"
AI: [calls get_architecture]
→ # 🏗️ Architecture Overview: default
   ## Statistics
   - Files: 45
   - Symbols: 1,234
   - Relationships: 567
   
   ## Hotspots (most called)
   1. validateInput - 23 callers
   2. formatResponse - 18 callers
   ...

4. Find Dead Code

You: "Find any potentially unused functions"
AI: [calls find_dead_code]
→ ⚠️ Potentially Dead Code (12 functions with no callers)
   - legacyHandler - src/handlers/old.ts:45
   - deprecatedUtil - src/utils/deprecated.ts:12
   ...

5. Custom Graph Query

You: "Show me all classes and their method counts"
AI: [calls query_graph]
→ SELECT 
     (SELECT name FROM symbols WHERE id = s.id AND type = 'class') as class_name,
     COUNT(*) as method_count
   FROM symbols s
   WHERE type = 'method'
   GROUP BY parent

Supported Languages

Claude Desktop Configuration

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.config/Claude/claude_desktop_config.json (macOS/Linux):

{
  "mcpServers": {
    "codebase-memory": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/project:/app/workspace:ro",
        "-v", "/path/to/.codebase-memory-data:/app/data",
        "codebase-memory-mcp"
      ]
    }
  }
}

Environment Variables

Directory Structure

Inside container:
/app
├── dist/           # Compiled JS
├── node_modules/
├── data/           # SQLite DB (persist via volume mount!)
│   └── memory.db   # Contains: memories, symbols, edges, indexed_files
└── workspace/      # Project code (mounted via -v)
    └── ...

Verify Installation

Test MCP Server Startup

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | podman run -i --rm codebase-memory-mcp

Confirm Tools Count

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | podman run -i --rm codebase-memory-mcp 2>/dev/null | tail -1 | jq '.result.tools | length'

Output: 19

Comparison with DeusData/codebase-memory-mcp

Choose This Project If:

• You want easy customization and extension

• You prefer Docker-based deployment

• Your codebase is primarily TypeScript/Python/Go

• You want to learn MCP development

Choose DeusData If:

• You need maximum token efficiency

• You have a large monorepo (millions of LOC)

• You need 158 language support

• You want zero-dependency deployment

License

MIT

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | docker run -i --rm codebase-memory-mcp 2>/dev/null | tail -1 | jq '.result.tools[].name'

Output:

"store_memory"
"retrieve_memory"
"list_memories"
"delete_memory"
"search_codebase"
"summarize_file"

Verify AI Can Use Tools

Once configured in VS Code or Claude Desktop, test with these prompts:

Test 1: Store and retrieve memory

Please store a memory with key "test" and content "Hello MCP", then list all memories.

Expected: AI calls store_memory then list_memories, showing the stored entry.

Test 2: Search codebase

Search for "function" in the codebase.

Expected: AI calls search_codebase and returns matching lines.

Test 3: Summarize file

Summarize the package.json file.

Expected: AI calls summarize_file and provides a summary of dependencies.

Troubleshooting

• If tools don't appear: Check MCP panel in VS Code (View → MCP Servers) or restart the editor

• If container fails: Run docker run -i --rm codebase-memory-mcp manually to see errors

• If path mount fails: Verify the workspace path exists and is accessible

FAQ

Q: When does memory disappear?

A: Memory is cleared each time the container exits (conversation ends or VS Code restarts). This is by design, allowing AI to re-understand the project each session.

Q: How to auto-initialize memory?

A: Use .github/copilot-instructions.md to set instructions, or explicitly request memory initialization at conversation start. See "Auto-Initialize Memory on Each Session" section above.

Q: What if I need persistent memory?

A: Add volume mount back:

"args": [
  "run", "-i", "--rm",
  "-v", "codebase-memory-data:/app/data",
  "-v", "${workspaceFolder}:/app/workspace:ro",
  "codebase-memory-mcp"
]

Then run podman volume create codebase-memory-data.

Q: Windows path conversion issues?

Docker Desktop automatically handles C:\ → /c/ conversion. For WSL Docker, store projects in WSL filesystem (e.g., /home/user/projects) to avoid path issues.