Codebase Memory

codebase-memory-mcp is a free, open-source MCP server that builds a persistent local knowledge graph of your repository.

It indexes functions, classes, imports, call paths, routes, configuration files, and other code relationships so Claude Code, Codex, Gemini CLI, and other MCP clients can query repository structure without rereading the codebase file by file.

This is useful for larger repositories where a simple question can trigger many searches and file reads. You can ask what calls a function, trace an API route through several services, inspect the likely impact of a Git diff, find unused code, or get an architecture overview from the indexed graph.

The MCP server handles local indexing and structural analysis. Your connected coding agent remains the language model that interprets your request, chooses graph tools, and turns the returned evidence into an explanation or code change.

Codebase Memory MCP at a Glance

How Codebase Memory Works

After you index a repository, codebase-memory-mcp stores its structural graph in SQLite under ~/.cache/codebase-memory-mcp/ by default. The graph records symbols and relationships such as imports, calls, routes, type usage, cross-service links, and file relationships.

Your coding agent can then call MCP tools such as search_graph, trace_path, get_architecture, and detect_changes. Current releases also include check_index_coverage, which helps the agent identify files or ranges that the graph did not fully represent before it makes broad or negative claims about the codebase.

Semantic search is bundled into the project, while BM25, structural search, graph traversal, and code search provide other retrieval paths. You do not need a separate embedding API or an API key for codebase-memory-mcp itself.

Features

• Builds a persistent SQLite knowledge graph from repository files, AST parsing, imports, calls, routes, package metadata, and other structural relationships.
• Parses 158 languages through bundled Tree-sitter grammars.
• Uses Hybrid LSP type resolution for Python, TypeScript, JavaScript, JSX, TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl.
• Supports semantic search, BM25 full-text search, structural graph search, and graph-augmented code search.
• Traces inbound and outbound function paths across files, packages, and indexed repositories.
• Maps Git changes to affected symbols and likely blast radius.
• Detects functions with zero callers while excluding known entry points.
• Identifies HTTP, gRPC, GraphQL, tRPC, Socket.IO, EventEmitter, and other supported cross-service relationships.
• Includes 15 MCP tools for indexing, structural queries, code search, architecture analysis, ADRs, runtime traces, and index coverage checks.
• Stores graph data locally under ~/.cache/codebase-memory-mcp/ by default.
• Configures 43 client surfaces through automatic, conditional, or explicit installer integrations. Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, OpenCode, Windsurf, Kiro, Cline, Qwen Code, and other coding clients are included in the current integration matrix.
• Includes a local 3D graph visualization in current release binaries.
• Uses a shared coordination daemon for MCP sessions, indexing coordination, file watching, and the graph UI.
• Exports an optional compressed graph artifact that teams can keep beside the repository for faster bootstrap on another machine.

Use Cases

• Trace inbound and outbound call chains before changing a shared function.
• Map API routes, handlers, services, and downstream dependencies in a multi-service project.
• Inspect Git changes before a refactor touches code outside the current feature branch.
• Check which source ranges are missing or only partly represented in the graph before relying on a repository-wide conclusion.
• Find unused functions after a migration or framework rewrite.
• Give Claude Code, Codex, or another MCP-capable coding agent a structural view of a repository before it edits files.
• Share a compressed graph snapshot so teammates can avoid a full first-time index.

How to Use It

1. Install on macOS or Linux

Run the current one-line installer. The installer downloads the current binary and configures compatible coding clients that it can safely detect. Use the binary-only option later in this guide if you prefer to manage MCP configuration yourself.

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

2. Install on Windows

Download the PowerShell installer, inspect it, remove the Mark-of-the-Web flag, and run it:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
notepad install.ps1
Unblock-File .\install.ps1
.\install.ps1

3. Restart your coding agent and index the repository

Restart Claude Code, Codex CLI, Gemini CLI, or your selected MCP client after installation. Then ask the agent to index the current repository:

Index this project.

4. Open the built-in graph visualization

Current release binaries already include the graph UI, so you do not need a separate UI variant. Start it with:

codebase-memory-mcp --ui=true --port=9749

Open http://localhost:9749 in your browser to inspect graph nodes, relationships, projects, and index coverage.

5. Ask structural questions

Use questions that benefit from repository-wide relationships:

What calls ProcessOrder?

Show the API route, handler, service, and database calls for user signup.

What code could this Git diff affect?

Find functions with no callers outside test files.

Check index coverage for the files used in this answer.

6. Enable automatic indexing

Automatic indexing can register a new project when an MCP session starts:

codebase-memory-mcp config set auto_index true

Set a file threshold for automatic indexing:

codebase-memory-mcp config set auto_index_limit 50000

The background watcher is controlled separately and defaults to enabled. Disable it when you want indexing to happen only when requested:

codebase-memory-mcp config set auto_watch false

7. Keep agent configuration under your control

Use the binary-only path when you do not want the installer to configure supported coding clients:

codebase-memory-mcp install --skip-config

Add the MCP entry manually for Claude Code through ~/.claude.json or a project .mcp.json file:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

CLI examples

The current CLI supports flags generated from each tool schema. This format is easier to read and avoids the older inline-JSON form, which remains available for backward compatibility.

codebase-memory-mcp cli index_repository --repo-path /absolute/path/to/repo

codebase-memory-mcp cli list_projects

codebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function

codebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both

codebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Function) RETURN f.name LIMIT 5'

MCP tools

Environment variables

Use a custom cache location when repository indexes belong on a different drive:

export CBM_CACHE_DIR=~/my-projects/cbm-data

Custom file extensions

Add project-specific language mappings through .codebase-memory.json.

{
  "extra_extensions": {
    ".blade.php": "php",
    ".mjs": "javascript"
  }
}

Add global mappings through ~/.config/codebase-memory-mcp/config.json when several projects use the same extensions.

What to Check Before Installation

codebase-memory-mcp is most useful when repository structure contains relationships that are expensive for an agent to reconstruct repeatedly. A small script or compact library may not need a persistent graph. Large applications, monorepos, service backends, and unfamiliar codebases offer clearer reasons to keep one.

The project ignores .git, node_modules, symlinks, .gitignore patterns, and .cbmignore rules. Use check_index_coverage when an answer depends on files that may not have been fully represented. A clean coverage result means the tool has not recorded a known gap; it does not prove that every relationship in the repository is complete.

Hybrid LSP adds deeper type-aware resolution for selected languages. Other supported languages still receive Tree-sitter parsing and textual or structural resolution, but call-path accuracy varies with language features, dependency patterns, generated code, dynamic dispatch, and project conventions.

The installer can edit MCP configuration and supporting context files for compatible coding clients. Use --skip-config when you want to inspect and maintain those files yourself. The current integration matrix also includes client-specific limitations, so automatic configuration does not imply identical hooks, subagent support, or context behavior across every client.

Repository indexing and graph queries run locally, and codebase-memory-mcp does not collect telemetry. The coding agent connected to the MCP server is a separate part of the workflow. A cloud-backed agent can send prompts or selected code context to its model provider according to that product’s settings and policies.

Large indexes use local CPU, memory, and disk. The v0.10.6 release fixes major indexing regressions reported in earlier 0.10.x builds, so update before diagnosing poor performance on large Java, C#, or TypeScript repositories. You can also adjust CBM_WORKERS, CBM_MEM_BUDGET_MB, and background watching when resource use needs tighter control.

The team graph artifact is optional. Commit .codebase-memory/graph.db.zst when teammates benefit from a shared starting point. Add .codebase-memory/ to .gitignore when each machine should maintain an independent index.

Alternatives and Related Tools

• Claude Context Local: Use local semantic code search when concept-based retrieval is more important than a persistent structural graph.
• Claude Code Commands Cheat Sheet: Keep a quick reference for Claude Code commands and configuration while setting up coding MCP servers.
• Claude Code Resource List: Browse tools, skills, plugins, repositories, and supporting resources for Claude Code workflows.
• Best CLI AI Coding Agents: Compare terminal-based coding agents that can serve as the model and interaction layer around tools such as codebase-memory-mcp.
• MCP Server Directory: Find additional MCP servers for coding, search, security, productivity, and connected services.

Pros

• Local repository indexing and graph queries.
• No API key required for codebase-memory-mcp itself.
• Native releases for macOS, Linux, and Windows.
• 15 MCP tools plus semantic, BM25, structural, and code-search paths.
• Built-in local graph UI.

Cons

• No bundled language model.
• Automatic installation can modify client configuration, context, skill, or hook files for supported integrations.
• Graph coverage and type resolution vary by language and code pattern.
• Cypher graph queries are read-only.

FAQs

Q: Is codebase-memory-mcp free?
A: Yes. The project uses the MIT license, and codebase-memory-mcp does not require an API key for local indexing or graph queries. Your connected coding agent can have its own subscription or API costs.

Q: What does “memory” mean in Codebase Memory MCP?
A: It refers to a persistent structural knowledge graph of your repository. The graph keeps code relationships available across sessions. It is not a general conversation-memory system for storing everything you discuss with an AI agent.

Q: Does codebase-memory-mcp send source code to the cloud?
A: codebase-memory-mcp performs indexing, graph storage, graph queries, and its own diagnostics locally and does not collect telemetry. A connected cloud-based coding agent can still send prompts or selected code context to its model provider.

Q: Does codebase-memory-mcp replace Claude Code, Codex, or Gemini CLI?
A: No. The MCP server supplies structural code intelligence. Claude Code, Codex, Gemini CLI, or another compatible agent interprets your request, calls the appropriate tools, and uses the results in its answer or coding workflow.

Q: Which coding agents can connect to codebase-memory-mcp?
A: The current installer supports 43 client surfaces across automatic, conditional, and explicit integration paths. Major examples include Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, OpenCode, Windsurf, Kiro, Cline, Qwen Code, GitHub Copilot CLI, and several others. Support depth differs by client.

Q: Do I need a separate graph UI package?
A: No. Current release binaries include the 3D graph UI. Start the local UI with codebase-memory-mcp --ui=true --port=9749 and open http://localhost:9749.

Q: Which programming languages receive deeper type resolution?
A: The project parses 158 languages through Tree-sitter. Hybrid LSP type resolution currently provides deeper analysis for Python, TypeScript, JavaScript, JSX, TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl.

Q: How can I tell if the graph missed part of the codebase?
A: Use check_index_coverage for the relevant files or paths. It reports known gaps in graph representation so an agent can read affected source directly before making a broad conclusion.

Q: Can a team share an existing graph index?
A: Yes. The project can create .codebase-memory/graph.db.zst, a compressed graph artifact that another machine can use as a starting point. Keep .codebase-memory/ in .gitignore when you do not want the artifact in the repository.