codebase-memory-mcp

A Docker stdio-based MCP Server providing codebase memory and search capabilities.

Features (6 Tools)

Tool	Description
store_memory	Store or update memory entries (supports tags)
retrieve_memory	Search memories by keyword/tag
list_memories	List all stored memories
delete_memory	Delete a specific memory
search_codebase	Search code using ripgrep (supports regex)
summarize_file	Read file content for LLM summarization

Quick Start

Build Docker Image

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

---

VS Code Configuration

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

Windows / macOS / Linux (Universal)

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

Windows (Docker via WSL)

If Docker is installed in WSL instead of Docker Desktop:

{
  "servers": {
    "codebase-memory": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "podman", "run", "-i", "--rm",
        "-v", "/mnt/d/xxxx:/app/workspace:ro",
        "codebase-memory-mcp"
      ]
    }
  }
}

Replace Ubuntu-22.04 with your WSL distribution name. Run wsl -l -v to list available distributions.

---

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", "C:\\Users\\YourName\\Projects\\my-project:/app/workspace:ro",
        "codebase-memory-mcp"
      ]
    }
  }
}

Replace C:\\Users\\YourName\\Projects\\my-project with your project path (Windows requires double backslashes).

---

Auto-Initialize Memory on Each Session

Since memory is not persisted (cleared when container exits), create an instruction file so AI automatically scans the project and builds memory at the start of each conversation.

Method 1: Create .github/copilot-instructions.md

## Project Memory Initialization

At the start of each conversation, execute these steps to build project memory:

1. Use `summarize_file` to read `package.json` for dependencies
2. Use `summarize_file` to read `README.md` for project purpose
3. Use `search_codebase` to explore main code structure
4. Use `store_memory` to save:
   - key: `project-overview` - Project summary
   - key: `tech-stack` - Tech stack (framework, language, main dependencies)
   - key: `architecture` - Directory structure and architecture

## Project Info

- Project name: {your-project-name}
- Language: TypeScript
- Framework: Next.js 14
- Database: PostgreSQL

Method 2: Explicit Request at Conversation Start

At the beginning of each conversation, say:

Please initialize project memory:
1. Read package.json and README.md
2. Search main files in src/ directory
3. Store project architecture in store_memory(key: "architecture")
4. Store tech stack in store_memory(key: "tech-stack")

Method 3: Memory Init Script (Advanced)

Create MEMORY_INIT.md in project root:

# Memory Initialization Checklist

Execute these store_memory calls in order:

store_memory(key: "project", content: "This is a Next.js 14 project using TypeScript...")
store_memory(key: "conventions", content: "File naming: kebab-case, Components: PascalCase...")
store_memory(key: "architecture", content: "src/app/ for routes, src/components/ for components...")

Then tell the AI: "Please read MEMORY_INIT.md and execute the memory initialization inside"

---

Environment Variables

Variable	Default	Description
DATA_PATH	/app/data	SQLite database directory (in-container, not persisted)
WORKSPACE_PATH	/app/workspace	Mounted codebase root directory
MEMORY_DB_PATH	$DATA_PATH/memory.db	Full path to database file

---

Directory Structure

Inside container:
/app
├── dist/           # Compiled JS
├── node_modules/
├── data/           # SQLite DB (in-container, reset each run)
│   └── memory.db
└── 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' \
  | docker run -i --rm codebase-memory-mcp

Should return a JSON response containing 6 tools.

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' \
  | docker run -i --rm codebase-memory-mcp 2>/dev/null | tail -1 | jq '.result.tools | length'

Output: 6

List All Tool Names

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.