codebase-memory-mcp
Persistent code intelligence for MCP with native graph, vector, full-text, and cross-repository search.
Install / Use
claude mcp add octacity-org -- npx -y github:octacity-org/codebase-memory-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of codebase-memory-mcp
codebase-memory-mcp scores 81/100 on our quality scale, 3485th of 4,716 Development & Engineering skills we index.
Its MCP Server is 30 KB long, well organised into 34 sections with 17 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 2 days ago, so codebase-memory-mcp is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
codebase-memory-mcp compared with similar skills
All 4 of these similar skills score higher than codebase-memory-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| codebase-memory-mcp (this skill)by octacity-org | 81 | 10 | 2d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 118.9k | 11d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 113.3k | 12d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 87.1k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install codebase-memory-mcp?
- Run
claude mcp add octacity-org -- npx -y github:octacity-org/codebase-memory-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does codebase-memory-mcp work with?
- It is written for Claude Code, Claude Desktop and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is codebase-memory-mcp safe to use?
- It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is codebase-memory-mcp still maintained?
- The repository was last updated 2 days ago, so codebase-memory-mcp is actively maintained.
Skill content
View source on GitHubcodebase-memory-mcp
A local MCP server that indexes a codebase into a knowledge graph your coding agent can query.
codebase-memory-mcp parses your repositories with tree-sitter and type-aware resolvers, stores
functions, classes, calls, routes, and cross-service links in one local database, and exposes them
through 15 MCP tools. Your agent asks "what calls ProcessOrder?" and gets the answer from the graph
instead of grepping file by file.
[!IMPORTANT] This is a fork of DeusData/codebase-memory-mcp. It adopts upstream fixes and features selectively. It does not mirror upstream releases, and its storage is different: every repository lives in one shared Zova database instead of a SQLite file per project.
Contents
- Install
- Quick start
- Upgrading to 2.0
- How it works
- What it can do
- MCP tools
- Graph data model
- Agents
- CLI
- Configuration
- Storage and Zova operations
- Build from source
- Diagnostics and troubleshooting
- Current boundaries
- Security
- License
Install
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/octacity-org/codebase-memory-mcp/main/install.sh | bash
Windows (PowerShell):
Invoke-WebRequest -Uri https://raw.githubusercontent.com/octacity-org/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
.\install.ps1
If PowerShell refuses to run the script, use PowerShell -ExecutionPolicy Bypass -File .\install.ps1.
The installer downloads the release archive for your platform, verifies it against the release
checksums.txt, installs the binary to ~/.local/bin, and configures every coding agent it detects.
It does not overwrite an existing different binary or MCP entry unless you ask it to.
| Option | Effect |
|--------|--------|
| --dir=<path> | Install somewhere other than ~/.local/bin |
| --skip-config | Install the binary only; leave agent configuration alone |
| --replace | Replace a different existing binary |
| --replace-config | Replace a different existing MCP configuration entry |
Pass options through the pipe with bash -s --, for example
curl -fsSL .../install.sh | bash -s -- --skip-config.
Release archives
Every release ships these
archives plus checksums.txt (SHA-256):
| Platform | Archive |
|----------|---------|
| macOS, Apple Silicon | codebase-memory-mcp-darwin-arm64.tar.gz |
| macOS, Intel | codebase-memory-mcp-darwin-amd64.tar.gz |
| Linux x86_64, portable (installer default) | codebase-memory-mcp-linux-amd64-portable.tar.gz |
| Linux ARM64, portable (installer default) | codebase-memory-mcp-linux-arm64-portable.tar.gz |
| Linux x86_64, glibc | codebase-memory-mcp-linux-amd64.tar.gz |
| Linux ARM64, glibc | codebase-memory-mcp-linux-arm64.tar.gz |
| Windows x86_64 | codebase-memory-mcp-windows-amd64.zip |
| Windows ARM64 | codebase-memory-mcp-windows-arm64.zip |
The portable Linux binaries are statically linked. The glibc builds need a glibc at least as new as the release runner's. All binaries target the baseline CPU of their architecture, so they also run on older processors.
<details> <summary>Manual install from an archive</summary>Each archive contains the binary and the matching installer.
tar xzf codebase-memory-mcp-*.tar.gz
./install.sh
Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
Unblock-File .\install.ps1
.\install.ps1
On macOS the install command removes the quarantine attribute and ad-hoc signs the binary. On
Windows, SmartScreen may warn about unsigned software; check the archive against checksums.txt
before choosing More info → Run anyway.
Update and uninstall
codebase-memory-mcp update
codebase-memory-mcp uninstall
The server also checks for a newer release on startup and mentions it on the first tool call.
uninstall removes the binary, agent configuration, skills, hooks, and instructions. It keeps the
shared cbm.zova database.
Quick start
- Install, then restart your coding agent.
- Open a repository and ask the agent: "Index this project."
- Ask structural questions:
- "What calls
handleCheckout, two levels up?" - "Show me the HTTP routes and which services call them."
- "Which functions have no callers?"
- "What does my uncommitted change affect?"
- "What calls
To index new projects automatically when a session starts:
codebase-memory-mcp config set auto_index true
Indexed projects stay fresh on their own: a background watcher detects git changes and re-indexes only what changed.
Upgrading to 2.0
2.0 changes the stored data and removes several tools. What happens when you upgrade from 1.x:
- Database format. A
cbm.zovain an older Zova storage format (9–11) is converted once when the new binary starts. The conversion writes a verified new file and then swaps it in. If it fails, the log names the fix:codebase-memory-mcp zova-ops migrate-format --json. - Index format. Each project takes one full re-index the next time it is indexed, instead of an
incremental one. That run reports
"format_migration": true. Incremental indexing resumes after it. - Per-project
.dbfiles from releases before the shared database are no longer read or migrated. Re-index those repositories withindex_repository.
Breaking changes:
| Change | What to do |
|--------|------------|
| manage_adr and ingest_traces tools removed | Drop them from prompts and scripts |
| Graph UI, website, and artifact export/import removed | Use zova-ops backups and workspace archives |
| CALL_REFERENCE edges split from CALLS | CALLS now means invocation only; see Graph data model |
| File nodes keep their extension in the qualified name | node.h and node.c are now two File nodes; re-query stored QNs |
New in 2.0: Zig type-aware call resolution, compare_graphs, get_file_outline, generation-bound
search_graph cursors, project-wide check_index_coverage, compact output, file_path to choose
between same-named trace_path and get_code_snippet targets, Cypher property-to-property
comparison, and memory-budgeted indexing that spills to disk.
How it works
codebase-memory-mcp is a structural backend. It does not include an LLM; the agent you already use turns your question into tool calls.
You: "what calls ProcessOrder?"
Agent: trace_path(function_name="ProcessOrder", direction="inbound")
Server: walks the call graph, returns structured rows
Agent: explains the call chain
flowchart LR
Repo["Repository files"]
Parse["tree-sitter parse<br/>(158 languages)"]
LSP["Hybrid LSP<br/>type resolution"]
Pipe["Pipeline<br/>calls · routes · links"]
DB["cbm.zova<br/>one workspace per repo"]
MCP["MCP tools"]
Agent["Coding agent"]
Repo --> Parse --> LSP --> Pipe --> DB
Agent <--> MCP <--> DB
Indexing runs in passes: structure, definitions, calls, HTTP and channel links, configuration, and tests. Results publish atomically into the shared database. Incremental runs commit only the affected graph, metadata, full-text, and vector rows; unchanged files are not rewritten.
Indexing keeps results in memory up to a budget (a fraction of system RAM, or CBM_MEM_BUDGET_MB)
and spills extraction results to disk beyond it, so a large repository does not have to fit in RAM.
When CBM_MEM_BUDGET_MB is set explicitly, the same limit also covers the post-extraction phases:
if the resident graph still exceeds it, indexing stops before publication and the previously
indexed generation keeps serving. The detected RAM fraction stays advisory after extraction, so a
run that would finish today with a soft overshoot is not turned into an error.
Research. The design and benchmarks are described in the preprint Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP. Across 31 real repositories it reports 83% answer quality with 10× fewer tokens and 2.1× fewer tool calls than file-by-file exploration.
What it can do
Understand structure
- Architecture overview:
get_architecturereturns languages, packages, entry points, routes, hotspots, boundaries, layers, and Louvain clusters in one call. - Call graph: calls resolve across files and packages, using imports and inferred types.
- Impact of a change:
detect_changesmaps the git diff to affected symbols and rates the risk. - Dead code: functions with no callers, excluding entry points.
- Compare two indexes:
compare_graphslists the nodes and edges added and removed between two indexed projects, for example two branches checked out side by side.
Search
- Structural search (
search_graph): regex names, labels, file patterns, degree filters. - Full-text search: BM25 over names and signatures, aware of camelCase and snake_case.
- Semantic search (
semantic_queryinsearch_graph): vector search with the bundlednomic-embed-codemodel compiled into the binary. No API key or model service. - Code search (
search_code): grep over indexed files only. - Cross-repository search: one
search_graphrequest can search several indexed repositories; see Cross-repository search.
Link services
- HTTP routes matched to call sites, with confidence scores.
- gRPC, GraphQL, and tRPC service detection, including protobuf routes.
- Event channels (
EMITS/LISTENS_ON) for Socket.IO, EventEmitter, and generic pub-sub. - Infrastructure as code: Dockerfiles, Kubernetes manifests, and Kustomize overlays become graph nodes.
Resolve types with Hybrid LSP
Tree-sitter alone sees syntax. It cannot tell that user.profile.display_name() means
Profile.display_name three modules away. Hybrid LSP is a small C implementation of each language's
type-resolution rules, built into the binary. It runs on every parse and refines CALLS and USAGE
edges with types. No language server process, no per-project setup.
| Language | What it resolves |
|----------|------------------|
| Python | imports and submodules, dataclasses, generics, @property, match, narrowing, Pydantic, SQLAlchemy Mapped[T], common stdlib |
| TypeScript / JavaScript / JSX / TSX | generics, JSX components, JSDoc in plain JS, .d.ts, re-exports, method chains |
| PHP | namespaces, traits, late static binding, PHPDoc |
| C# | global usings, records, LINQ method syntax, Task<T> unwrap, var inference |
| Go | cross-file package registry, generics, embedded structs, interface satisfaction |
| C / C++ | macros, typedef chains, header-source linking, templates, namespaces, auto |
| Java | imports, class hierarchy, overloads, lambdas and method references |
| Kotlin | extension functions, companion objects, scope functions, nullable unwrapping |
| Rust | use paths, impl
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
118.9kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
113.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
87.1kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.1k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
