# Codebase Memory MCP

> Codebase Memory MCP

- Skill: `lucadominguez/codebase-memory-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lucadominguez/codebase-memory-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucadominguez/codebase-memory-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lucadominguez (https://skillmd.com/u/lucadominguez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucadominguez/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)
```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
```

### With 3D graph visualization UI
```bash
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui
```

### Windows (PowerShell)
```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
```bash
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
```bash
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
| Var | Purpose | Default |
|---|---|---|
| `CBM_CACHE_DIR` | Override DB storage dir | `~/.cache/codebase-memory-mcp/` |
| `CBM_LOG_LEVEL` | debug/info/warn/error/none | info |
| `CBM_WORKERS` | Parallel worker count | auto |
| `CBM_ALLOWED_ROOT` | Restrict indexing to this dir | (unrestricted) |
| `CBM_MEM_BUDGET_MB` | In-memory graph budget | auto |
| `CBM_DIAGNOSTICS` | Set to 1 for diagnostics | off |

### 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
| Tool | Purpose |
|---|---|
| `index_repository` | Index a repo (absolute path required) |
| `list_projects` | List all indexed projects |
| `delete_project` | Remove a project from the graph |
| `index_status` | Check indexing progress/status |

### Querying
| Tool | Purpose |
|---|---|
| `search_graph` | Structured search by label, name pattern, file, degree |
| `trace_path` | BFS traversal — who calls X, what X calls (alias: trace_call_path) |
| `detect_changes` | Git diff → affected symbols + blast radius |
| `query_graph` | Cypher-like read-only graph queries |
| `get_graph_schema` | Node/edge counts, property definitions |
| `get_code_snippet` | Read source for a function by qualified name |
| `get_architecture` | Codebase overview (structure, layers) |
| `search_code` | Grep-like text search within indexed files |
| `manage_adr` | CRUD for Architecture Decision Records |
| `ingest_traces` | Ingest runtime traces to validate HTTP_CALLS edges |
| *(semantic_search)* | Bundled Nomic embeddings, covered by search_graph |

## Visualization (3D Graph UI)

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

```bash
# 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.