Codebase Memory

codebase-memory-mcp is a free, open-source MCP server that indexes your repository into a persistent local code graph.

It maps functions, classes, imports, call paths, HTTP routes, configuration files, and code relationships so an AI coding agent can query structure instead of repeatedly scanning files.

Large repositories create a context problem for Claude Code, Codex CLI, Gemini CLI, and similar agents. A request such as “What calls this function?” may require many searches, file reads, and guesses about imports.

codebase-memory-mcp stores that structure locally, then returns graph results for search, architecture summaries, impact analysis, dead-code checks, and cross-service tracing.

Features

• Builds a persistent SQLite code graph from repository files, AST parsing, imports, calls, routes, and package metadata.
• Parses 158 languages through bundled Tree-sitter grammars.
• Adds Hybrid LSP type resolution for Python, TypeScript, JavaScript, PHP, C#, Go, C, C++, Java, Kotlin, and Rust.
• Searches indexed code through semantic, BM25, structural, and graph-aware text queries.
• Traces inbound and outbound function paths across files and packages.
• Maps uncommitted 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, and pub-sub relationships.
• Stores graph data locally under ~/.cache/codebase-memory-mcp/.
• Configures 11 coding agents through its installer, including Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.
• Runs an optional local graph visualization at localhost:9749.
• Exports a compressed graph artifact that teammates can commit beside the repository.

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.
• Find unused functions after a migration or framework rewrite.
• Give Claude Code or Codex a structural view of a repository before it edits files.
• Share a compressed graph snapshot so teammates can skip a full first-time index.

How to Use It

1. Install the standard binary

macOS and Linux can install the standard MCP server with this command:

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

The installer detects supported coding agents and adds configuration automatically.

2. Install the graph visualization variant

The UI build starts a local graph explorer after installation.

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

Start the local visualization server with this command:

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

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

3. Install on Windows

Download and inspect the PowerShell installer before execution.

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

4. Restart your coding agent

Restart Claude Code, Codex CLI, Gemini CLI, or your selected MCP client after installation.

Ask the agent to index the current repository:

Index this project.

The server creates a project graph and keeps the index available across future sessions.

5. Ask structural questions

Use direct questions that require repository-wide context.

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.

6. Enable automatic indexing

Automatic indexing registers projects when an MCP session begins.

codebase-memory-mcp config set auto_index true

Set a file threshold if your machine handles large repositories:

codebase-memory-mcp config set auto_index_limit 50000

7. Keep agent configuration under your control

Use the binary-only path when you do not want automatic changes to agent files.

codebase-memory-mcp install --skip-config

Add the MCP entry manually if you use Claude Code:

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

Use an absolute path for the binary. Restart the client, then run /mcp to confirm the server appears.

CLI examples

codebase-memory-mcp cli index_repository '{"repo_path": "/absolute/path/to/repo"}'

codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'

codebase-memory-mcp cli trace_path '{"function_name": "Search", "direction": "both"}'

codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

codebase-memory-mcp cli list_projects

MCP tools

Run get_graph_schema before writing complex Cypher queries. The query engine accepts a read-only subset of openCypher. Write clauses such as MERGE and CALL do not run.

Environment variables

Use a custom cache location when repository indexes belong on a separate 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 adds the most value in repositories where source structure carries more context than individual files. A small script repository rarely needs a local graph database. A large monorepo, service backend, or long-lived application often does.

The project ignores .git, node_modules, symlinks, .gitignore patterns, and .cbmignore rules. Add a .cbmignore file when generated output, internal fixtures, or large vendor folders do not belong in the index.

Hybrid LSP adds stronger type-aware resolution for selected languages. Other supported languages still receive Tree-sitter parsing and textual resolution, but call-path accuracy can vary with language features, dependency patterns, generated code, and project conventions.

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

Alternatives and Related Tools

• Claude Context Local: Use local semantic code search when you want concept-based retrieval inside Claude Code.
• Claude Code Commands Cheat Sheet: Configure and operate Claude Code before adding code-intelligence MCP servers.
• The Ultimate Claude Code Resource List: Browse agent tools, skills, plugins, and repositories for Claude Code workflows.
• Best CLI AI Coding Agents: Compare terminal-based coding agents across local and cloud model workflows.
• MCP Server Directory: Find MCP servers for coding, search, security, productivity, and external services.

Pros

• MIT-licensed open-source project.
• Local repository indexing.
• No API key required.
• Static binaries for major platforms.
• 14 MCP analysis tools.
• Optional local graph UI.

Cons

• Requires an MCP-capable agent.
• No bundled language model.
• Installer edits agent configuration.
• Hybrid resolution varies by language.
• Cypher queries remain read-only.

FAQs

Q: Is codebase-memory-mcp free?
A: codebase-memory-mcp uses the MIT license and does not require an API key for local indexing, graph storage, semantic search, or structural queries. Your connected coding agent may still require a paid subscription or API credits for model access.

Q: Does codebase-memory-mcp send code to the cloud?
A: The MCP server indexes code, stores graph data, and runs graph queries locally. Your AI coding agent may still send prompts or selected code context to a cloud model provider, depending on the agent and model settings.

Q: Does codebase-memory-mcp replace Claude Code or Codex?
A: No. codebase-memory-mcp acts as a structural code-intelligence layer. Claude Code, Codex, Gemini CLI, or another MCP client translates your request into graph queries and turns the result into an answer or coding action.

Q: Which coding agents can connect to codebase-memory-mcp?
A: The installer detects Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro. Manual MCP configuration also works when your client accepts a local stdio server.

Q: Which programming languages receive the strongest code resolution?
A: The server parses 158 languages through Tree-sitter. Hybrid LSP type resolution adds deeper cross-file analysis for Python, TypeScript, JavaScript, PHP, C#, Go, C, C++, Java, Kotlin, and Rust.

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 a teammate can import after cloning the repository. Keep the folder in .gitignore when local indexes should stay private to each machine.

Q: Does codebase-memory-mcp index every project file?
A: No. The indexer applies hard exclusions, .gitignore rules, .cbmignore rules, and symlink exclusions. Add project-specific ignore rules before indexing generated output or large dependency folders.