RELATED 01
State Memory MCP
Local SQLite graph of tasks, decisions and blockers that coding assistants keep across sessions
41GitHub stars
176/wknpm downloads
38popularity score
codebase-memory-mcp
Builds a local graph of a codebase so an agent can query calls, routes, change impact and code.
By Martin Vogel (individual) Local · stdio Developer toolsKnowledge and memory
77 popularity score ★ 48k ↓ 16k/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
Claude CodeTerminal
claude mcp add codebase-memory -- npx -y codebase-memory-mcpClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"codebase-memory": {
"command": "npx",
"args": [
"-y",
"codebase-memory-mcp"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"codebase-memory": {
"command": "npx",
"args": [
"-y",
"codebase-memory-mcp"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"codebase-memory": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codebase-memory-mcp"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.codebase-memory]
command = "npx"
args = ["-y", "codebase-memory-mcp"]Gemini CLITerminal
gemini mcp add --scope user codebase-memory npx -- -y codebase-memory-mcpLocal (from source)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
FirstTerminal
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh --with-uiClaude CodeTerminal
claude mcp add codebase-memory -- '<ABSOLUTE_PATH_TO_CLONE>/build/c/codebase-memory-mcp'Claude Desktopclaude_desktop_config.json
{
"mcpServers": {
"codebase-memory": {
"command": "<ABSOLUTE_PATH_TO_CLONE>/build/c/codebase-memory-mcp",
"args": []
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"codebase-memory": {
"command": "<ABSOLUTE_PATH_TO_CLONE>/build/c/codebase-memory-mcp",
"args": []
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"codebase-memory": {
"type": "stdio",
"command": "<ABSOLUTE_PATH_TO_CLONE>/build/c/codebase-memory-mcp",
"args": []
}
}
}Codex~/.codex/config.toml
[mcp_servers.codebase-memory]
command = "<ABSOLUTE_PATH_TO_CLONE>/build/c/codebase-memory-mcp"
args = []Gemini CLITerminal
gemini mcp add --scope user codebase-memory '<ABSOLUTE_PATH_TO_CLONE>/build/c/codebase-memory-mcp'Settings 1
CBM_DOWNLOAD_URL |
Optional: Base address the npm package fetches the binary and checksums from. Must be https, or plain http to localhost. |
|---|
What it does
Indexes a repository into a graph of functions, classes, calls, HTTP routes and links between services, so a coding agent asks one structural question where it would otherwise grep and open files for many rounds. The parser covers 162 languages through tree-sitter grammars built into the program, and some of the main ones get extra type resolution on top.
The graph lives in SQLite files under ~/.cache/codebase-memory-mcp unless CBM_CACHE_DIR points elsewhere. On first use a background daemon starts for your account and is shared by every session after that. Indexing runs when the agent asks for it. Turn on auto_index and it also happens at session start, after which a watcher keeps watched git projects in sync. There is an optional graph viewer for the browser too, called CBM Lens, still in beta.
You can narrow what a client sees. Started with --tool-profile analysis it offers 13 read-only tools, and --tool-profile scout trims that to 8. In both cases the HTTP side stays off, because the source lets only the full profile serve it (src/mcp/mcp.c at the published tag). Log output can also be switched to JSON with CBM_LOG_FORMAT=json, a setting read in src/foundation/log.c that the README table does not list.
What it needs
| Runtime | A prebuilt binary |
|---|---|
| Runs on | macOS, Windows, Linux |
The npm way needs Node.js 18 or later, which downloads, checks and starts the native binary for macOS, Linux or Windows on arm64 or amd64. The install script and the source build give a standalone executable instead. After any of them, `codebase-memory-mcp install` writes the config for the agents it finds. In Claude Code you can add just the server with `claude plugin marketplace add DeusData/codebase-memory-mcp` and `claude plugin install codebase-memory@codebase-memory`.
Limits
- Early release CBM Lens, the browser graph viewer, is an open beta.
- Not covered By default the file watcher polls git projects alone. Set watch_non_git to true to cover other folders.
- Size cap With index_max_files or index_max_source_mb set, going over either fails the whole index and keeps the old graph.
- Limit A blocking index of a big repository can outlast a client's call deadline. The README says to pass async: true and poll with status.
- Limit The Claude Code plugin and the install command each register the server, so using both runs it twice under two tool names.
- Limit Microsoft Defender may flag the binary as Trojan:Script/Wacatac.B!ml, which the README calls a false positive.
- Limit All sessions for one account must use the same build and cache directory, since they share one daemon.
Who it suits
A good fit when you work in a large or multi-language codebase on your own machine and want the agent to answer questions about calls, impact and structure without reading file after file. Nothing has to leave the machine and no key is needed. If a client should only look and never change the index, start it with --tool-profile analysis. For a small project, plain file search in your agent may be enough, since the graph has to be built before it pays off.
Tools 17
13 only read, 1 changes things, 3 can delete or overwrite. A ? marks an optional parameter.
index_repositorychanges- Parses a repository and stores its graph in the local cache, waiting for the result unless async is set.
repo_path: stringmode?: enumtarget_projects?: arrayname?: stringpersistence?: booleandoc_candidates?: booleanasync?: booleanstatus?: boolean list_projects- Lists the indexed projects, with node and edge counts when asked.
detail?: enumlimit?: integer delete_projectdeletes- Removes a project's graph and its stored architecture records.
project: string index_status- Shows whether a project is indexed and how fresh its graph is.
project: stringdiagnostics?: string check_index_coverage- Checks whether given paths or scopes are in the index and up to date.
project: stringpaths?: arrayscopes?: array search_graph- Finds symbols by name pattern, label, file, full text or meaning.
project: stringquery?: stringlabel?: stringname_pattern?: stringqn_pattern?: stringfile_pattern?: stringsemantic_query?: arraylimit?: integeroffset?: integer query_graph- Runs a read-only Cypher-like query over the graph.
query: stringproject: stringgraph?: enummax_rows?: integercursor?: stringformat?: string trace_path- Follows callers and callees, data flow, service links or deploy chains from a function.
function_name: stringproject: stringdirection?: stringdepth?: integerlimit?: integermode?: enuminclude_tests?: boolean get_code_snippet- Returns the source of a symbol by its qualified name.
qualified_name: stringproject: stringsource_mode?: enummax_lines?: integer get_file_outline- Lists the declarations in one file in source order.
project: stringfile_path: stringlimit?: integer get_graph_schema- Shows the node and edge types in a project's graph with their counts.
project: stringdiagnostics?: enum compare_graphs- Reports nodes and edges added or removed between two indexed snapshots.
base_project: stringtarget_project: stringlimit?: integer get_architecture- Gives an overview of languages, packages, routes, hotspots and clusters.
project: stringpath?: stringaspects?: array search_code- Text or regex search across the indexed files of a project.
pattern: stringproject: stringmode?: enumregex?: booleanlimit?: integer detect_changes- Maps a git diff to the symbols it touches and rates the risk.
project: stringscope?: enumdepth?: integerbase_branch?: stringsince?: string manage_adrdeletes- Reads or rewrites the project's architecture decision record, whole or by section.
project: stringmode?: enumcontent?: stringsection_updates?: object ingest_tracesdeletes- Stores observed runtime call pairs under a run label, which can push out older runs.
traces: arrayproject: stringlabel?: string