What Is codebase-memory-mcp? Code Graph, Installation, What It Writes to Agent Settings and Uninstalling

You ask the agent a question like "who calls this function"; because codebase-memory-mcp indexes the project's code (functions, classes, imports, HTTP routes and the relationships between them) into a persistent knowledge graph on your computer, the agent answers without reading files one by one. It's served to coding agents like Claude Code and Codex through MCP; it's MIT-licensed open source (developer: DeusData), and no account or API key is needed. You install it with a script or npm, and the `install` command writes MCP entries, skills, subagents and, for some agents, hooks into the settings of the agents it detects. The project's own security document says the program interacts deeply with the file system.

What it does: Indexes the project's code into a graph the agent can query
Type: MCP server (local program)
Where: Claude Code, Codex, Gemini CLI, Cursor, VS Code and ~45 surfaces
Account: None; no key needed
Writes to agent settings: MCP entry, skill, agent, hook, instructions file
Turkish: Not stated in the official documentation
Cost: Free (MIT)

What Is codebase-memory-mcp For?

To understand a large project, a coding agent reads lots of files, which costs time and tokens. This program indexes the project once and stores its structure as a graph. The agent then asks the graph questions like "who calls this function," "what does this change affect" and "what's the architecture." MCP is the standard for connecting AI programs to external tools.

YouYou ask a question about the code

AssistantClaude Code, Codex, Gemini CLI, Cursor

codebase-memory-mcpRuns on your computer

Code graphFunctions, classes, imports, routes and their relationships

No account or key; the install command writes MCP entries, skills and hooks into agent settings.

Answer call and impact questions from the graphWhat you get: Search and call trace resultsNeeds a separate setup Browse the architecture in the browserWhat you get: Browser interfaceNeeds a separate setup

Tools: indexing the repository, structural and semantic search, call path tracing, mapping a git diff to the affected symbols, a read-only Cypher-like graph query, reading code snippets, an architecture summary, and managing architecture decision records (ADRs). The README for the released version 0.11.0 lists 15 tools; the main branch README lists 17 and also describes features that haven't been released yet. There's also an optional local web interface (127.0.0.1:9749).

Who it's for: developers working with a coding agent on a large or old codebase. On a small project, reading the files may already be enough. Claims in the README like "120x fewer tokens" are the project's own measurements.

How Do You Install codebase-memory-mcp?

Know what it writes first: the install command touches the configuration of the agents it detects (see "What does it access?" below). The commands are taken verbatim from the README.

1. Install the package› npm install -g codebase-memory-mcp

2. Register with your agents› codebase-memory-mcp install

Restart your agent and say "Index this project." During installation, the npm package downloads the binary for your platform from GitHub Releases. Requires Node.js 18+.

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

This command downloads the script from the main branch and runs it directly. The README says "download, inspect, run" for Windows; on macOS and Linux, too, it's safer to download the file first and look at its contents.

The --skip-config option installs only the binary and doesn't touch agent settings.

1. Download the script

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

2. Look at its contents (notepad install.ps1). 3. Unblock it and run it:

Run› Unblock-File .\install.ps1

Then› .\install.ps1

If you get an execution policy error, the README suggests Set-ExecutionPolicy -Scope Process Bypass or PowerShell -ExecutionPolicy Bypass -File .\install.ps1. If Defender flagged a release as a false positive, see the "Common problems" section.

With pip› pip install codebase-memory-mcp

Then run codebase-memory-mcp install. If you want to install manually, download the archive for your platform from the Releases page and verify its SHA-256 with checksums.txt. If you don't want the install command, you can also write the MCP entry by hand:

~/.claude.json or the project's .mcp.json› {"mcpServers": {"codebase-memory-mcp": {"command": "/path/to/codebase-memory-mcp", "args": []}}}

To see what the installation will write to agent settings, first install only the binary with --skip-config, then add the MCP entry by hand. Don't turn on hooks without reviewing them.

How Do You Use codebase-memory-mcp?

After installing, restart your agent, open it in the project folder and ask it to index. On large repositories, indexing can time out in the client; the tool supports an asynchronous mode (start with async: true, check with status: true).

Index"Index this project."

Find the callers"Who calls the processPayment function? If I change this function, which files are affected?"

Impact of the git diff"List the symbols affected by the changes I've made since the last commit, and which ones are risky."

Open the local interface (optional)› codebase-memory-mcp daemon start --open --port=9749

A shared background process (daemon) runs and watches for changes in git projects. To stop it, run codebase-memory-mcp daemon stop.

Which Agents Does codebase-memory-mcp Work With?

Claude CodeYes	Detected automatically; MCP entry in ~/.claude.json; a skill, three graph agents and hooks are written.
Codex CLIYes	config.toml, an AGENTS.md pointer, a skill and three read-only agents; you need to review and trust the hooks with /hooks.
Gemini CLI, Cursor, VS Code (Copilot)Yes	Detected automatically; writes to the relevant settings files.
Zed, OpenCode, Windsurf, Kiro, Cline and othersYes	The README lists 45 client surfaces in total (39 detected automatically, 6 conditional).
Claude Desktop, claude.aiUnclear	Not mentioned in the README's client list; that doesn't mean it "doesn't work."

Platforms: macOS and Linux (arm64, amd64), Windows (amd64). The npm page also lists Windows arm64; the README only says amd64.

What Does codebase-memory-mcp Access and Write?

Reads

The source code and git status of the indexed project; during installation, the configuration files of the agents it detects.

Writes

It writes graph indexes under ~/.cache/codebase-memory-mcp. The install command adds entries to the agents' MCP settings and to skill, subagent, hook and instructions files (like AGENTS.md and GEMINI.md). A shared daemon runs in the background and watches git projects. The manage_adr tool writes or updates the project's architecture decision record inside the index.

Hooks (Claude Code)

README: hooks are written for session start, subagent start, before Grep/Glob/Bash (non-blocking) and after Read for coverage checks.

Deletion

The delete_project tool deletes a project's graph data, not its source code. uninstall removes the agent entries and the binary.

Data: the README says it's "100% local, collects no telemetry; your code, queries, environment variables and usage never leave your machine." Indexed code can end up in query results that go to the model used by the connected agent; that's subject to that agent's data policy. The local chat feature downloads an optional in-browser model (Hugging Face, about 567 MB by default), and only if you start it.

The README and the project's SECURITY.md file contradict each other on background version checks. The README says "no background version checks, nothing phones home." SECURITY.md, on the other hand, describes a background update-check thread that requests the latest release information from GitHub when MCP starts (curl, limited to 5 seconds, sends no project data). The documents don't make clear which applies to the released version. SECURITY.md also states plainly that the program "reads source files, writes to agent configuration files and starts background processes," and recommends reviewing the source before installing. No advisories are listed in GitHub Security Advisories or in an OSV scan; that doesn't mean "safe."

Is codebase-memory-mcp Free?

Yes. It's MIT-licensed open source; no plan, account or API key. The subscription and token costs of the coding agent you use are separate; indexing and graph queries run on your computer.

Allowed

MIT: you're free to use it, modify it and use it in commercial work

Not allowed

Building from source requires a C/C++ compiler and zlib; building the interface requires Node.js 22+

Source: README and LICENSE. This is not legal advice.

Common Problems and Fixes

What's happening	What to do
Windows Defender flags a release as Trojan:Script/Wacatac.B!ml	SECURITY.md says this is a single engine's heuristic match and that the developers believe it's a false positive. Verify it yourself with checksums.txt, the SLSA attestation and the VirusTotal links. This is not a security guarantee.
On Windows the script gives an "execution policy" error	`Unblock-File .\install.ps1` or `Set-ExecutionPolicy -Scope Process Bypass`.
Indexing a large repository times out in the client	Start index_repository with `async: true` and check with `status: true`. In a synchronous call, if the client gives up, the daemon cancels the indexing.
After a new release, the agent runs the old version, or there's a "conflict" error	README: all active processes must have the same version and cache root; restart open agent sessions after installing.
Reported by users Indexing or daemon problems on Windows and slow devices	Open issues #2584, #2569, #2606 (lock error, 30-second client timeout, crashes with some compilers). No fix is documented; use a released binary.

How Do You Uninstall codebase-memory-mcp?

Preview: codebase-memory-mcp uninstall --dry-run shows what will be removed.
Uninstall: codebase-memory-mcp uninstall removes the registered agent entries, the skills, hooks and instructions, and the binary. Indexes are kept by default.
Delete the indexes too: codebase-memory-mcp uninstall -y --delete-indexes.
Background process: codebase-memory-mcp daemon stop.

The install script stays next to the binary; uninstall only prints its path and doesn't delete it.

Frequently asked questions

What is codebase-memory-mcp?

An MIT-licensed open-source program that indexes a project's code into a knowledge graph on your computer and serves it to coding agents like Claude Code and Codex through MCP. The agent answers questions about calls and impact from the graph, without reading files one by one.

Does codebase-memory-mcp collect telemetry?

The README and SECURITY.md say there's no telemetry. However, the two documents contradict each other on background version checks: the README says there's no check, while SECURITY.md says there's a check that requests release information from GitHub. The documentation states that no project data is sent.

Is my code uploaded to the cloud?

According to the README, indexing and graph storage stay on your machine. However, the coding agent you use, and its model, can see the query results.

Which coding agents does it work with?

The README lists 45 client surfaces. Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code and Zed are on the list. A client that isn't on the list can't be called "doesn't work"; it's simply "not in the docs."

What does the install script do, and is it safe?

It downloads the binary, verifies it with SHA-256 and writes to agent settings. The README recommends inspecting it before running it on Windows, and SECURITY.md recommends reviewing the source. No security advisory is listed; that doesn't mean "safe."

How do I uninstall it?

codebase-memory-mcp uninstall removes the agent entries and the binary; indexes are kept by default, and --delete-indexes deletes them.

Related guides

Cline

21st MCP

ai-memory awwwards-animations

Brave Search MCP

Chrome DevTools MCP

Sources

Not clear in the official sources: Background version checks (the README and SECURITY.md contradict each other) · the "120x fewer tokens" claim (the project's own measurement) · Homebrew, Scoop, Winget and Chocolatey commands · Windows arm64 support · whether main-branch features are in the released version · Turkish support. Each one is covered in its section.