Codebase Memory MCP

Codebase Memory MCP

An MCP server that indexes codebases into a persistent knowledge graph (SQLite, zero runtime deps, pure C binary). Provides 15 MCP tools for structural querying — dramatically fewer tokens than file-by-file exploration.

Repo: https://github.com/DeusData/codebase-memory-mcp

Trigger conditions

• User wants to understand a codebase structure (what calls what, dependency graph, architecture overview)
• User asks "how does X connect to Y", "who calls this function", "what's affected if I change this"
• User wants dead code detection, diff impact analysis, or cross-repo intelligence
• User says "index this repo" or "analyze this codebase"
• First time setup: user wants to install and configure it

How it works

• Indexes code into a graph: nodes = functions, classes, files, packages, routes, etc. Edges = CALLS, IMPORTS, HTTP_CALLS, etc.
• You call MCP tools → server runs graph queries → returns structured results → you translate to natural language
• No embedded LLM — your agent is the intelligence layer

Node/Edge Types

Nodes: Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Resource Edges: CONTAINS_PACKAGE, CONTAINS_FOLDER, CONTAINS_FILE, DEFINES, DEFINES_METHOD, IMPORTS, CALLS, HTTP_CALLS, ASYNC_CALLS, IMPLEMENTS, HANDLES, USAGE, CONFIGURES, WRITES, MEMBER_OF, TESTS, USES_TYPE, FILE_CHANGES_WITH, EMITS, LISTENS_ON, DATA_FLOWS, SIMILAR_TO, SEMANTICALLY_RELATED, CROSS_* (cross-repo)

Installation

Quick install (macOS/Linux)

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

With 3D graph visualization UI

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

Windows (PowerShell)

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

Post-install PATH

export PATH="$HOME/.local/bin:$PATH"

The install script auto-detects installed coding agents (Hermes, Claude Code, Cursor, etc.) and configures them. It writes to $HERMES_HOME/config.yaml for Hermes.

Configuration

CLI config

codebase-memory-mcp config list
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000
codebase-memory-mcp config set auto_watch false
codebase-memory-mcp config reset auto_index

Environment variables

Config files

• Global: ~/.config/codebase-memory-mcp/config.json
• Per-project: .codebase-memory.json in repo root
• Runtime: ${CBM_CACHE_DIR}/_config.db

MCP Tools Reference (15 tools)

Indexing

Querying

Visualization (3D Graph UI)

The binary ships a built-in 3D graph visualization accessible via browser:

# Start the server with UI enabled
export PATH="$HOME/.local/bin:$PATH"
tail -f /dev/null | codebase-memory-mcp --ui=true --port=9749 &

# Open in browser
# http://localhost:9749

Important: codebase-memory-mcp is an MCP stdio server first — it exits when stdin closes. The tail -f /dev/null | ... trick keeps stdin open so the server stays alive. The --ui=true flag is persisted; once enabled, even codebase-memory-mcp without flags serves the UI.

• Dark-themed 3D force-directed graph
• All indexed projects available in a single UI
• Default port: 9749 (change with --port=N)
• Port and UI settings persist across restarts
• To disable: codebase-memory-mcp --ui=false

Index a repo

index_repository(repo_path="/absolute/path/to/repo")

After indexing, call list_projects to get the project name for subsequent queries.

Find functions by pattern

search_graph(project="my-project", name_pattern=".*Handler.*", label="Function")

Trace call paths

trace_path(project="my-project", function_name="Search", direction="both")
# direction: "inbound" (who calls X), "outbound" (what X calls), "both"

Cypher-like queries

query_graph(project="my-project", query="MATCH (f:Function) WHERE f.name CONTAINS 'auth' RETURN f.name, f.file ORDER BY f.name")

Diff impact analysis

detect_changes(project="my-project")
# Returns affected symbols and blast radius from unstaged changes

Get source for a symbol

get_code_snippet(project="my-project", qualified_name="my-project.src.auth.login")

Architecture overview

get_architecture(project="my-project")

Dead code detection

query_graph(project="my-project", query="MATCH (f:Function) WHERE f.incoming_calls = 0 AND f.outgoing_calls = 0 RETURN f.name, f.file")

Pitfalls

1. Absolute paths required — index_repository needs absolute paths. Use $PWD or $(pwd).
2. Trace needs exact names — trace_path returns 0 results for partial/inexact names. Use search_graph first to find the exact qualified name.
3. Always scope with project — queries without project may return results from the wrong project. Use list_projects to confirm names.
4. Index time — large repos take minutes. Linux kernel (28M LOC) takes ~3 min. Check index_status for progress.
5. Cypher is read-only AND syntax-limited — query_graph only supports simple MATCH with exact = comparisons. STARTS WITH, CONTAINS, >, <, >= all silently return empty rows (no error — just 0 results). The property names available to Cypher may also differ from what get_architecture reports. Prefer trace_path, search_graph, and get_architecture for structural queries; reserve query_graph for simple exact-match MATCH patterns only.
6. Auto-index has a file limit — default 50,000 files. Bump with config set auto_index_limit for monorepos.
7. Graph reset — to re-index from scratch: rm -rf ~/.cache/codebase-memory-mcp/
8. Binary updates — codebase-memory-mcp update self-updates the binary.
9. Windows SmartScreen — may warn for unsigned binary, click "More info" → "Run anyway".
10. Qualified name format — <project>.<path_parts>.<name>, e.g. my-project.src.auth.login_handler.authenticate.
11. Background watcher — auto_watch uses git polling. Disable with config set auto_watch false if unwanted.
12. No telemetry — all processing is 100% local, SQLite at ~/.cache/codebase-memory-mcp/.
13. CLI output mixes log lines with JSON — cli subcommands print level=info lines before JSON. When piping to python3 for parsing, filter first: 2>&1 | grep -v '^level=' or use tail -n +2.
14. Install script may not detect Hermes on WSL — the auto-detection relies on pgrep and known agent paths. On WSL, it may report "(none)". Fall back to manual CLI usage (codebase-memory-mcp cli ...) or register the MCP server manually in ~/.hermes/config.yaml.
15. Project name derivation — project names are derived from the indexed path with slashes replaced by dashes. /mnt/c/Users/Lenovo/Desktop/AI/daemon becomes mnt-c-Users-Lenovo-Desktop-AI-daemon. Use list_projects to confirm the actual name after indexing.