SkillAgentSearch skills...

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-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

81/100

Supported Platforms

Claude Code
Claude Desktop
OpenAI Codex

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.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
4/20
Freshness
15/15

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.

SkillScoreStarsUpdatedFormat
codebase-memory-mcp (this skill)by octacity-org81102d agoMCP Server
taste-skillby Leonxlnx100118.9k11d agoCLAUDE.md
Agent-Reachby Panniantong100113.3k12d agoCLAUDE.md
hyperframesby heygen-com10087.1ktodayCLAUDE.md
rufloby ruvnet10082.1ktodayCLAUDE.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.

codebase-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.

GitHub Release License CI arXiv

[!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

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.

</details>

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

  1. Install, then restart your coding agent.
  2. Open a repository and ask the agent: "Index this project."
  3. 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?"

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.zova in 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 .db files from releases before the shared database are no longer read or migrated. Re-index those repositories with index_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_architecture returns 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_changes maps the git diff to affected symbols and rates the risk.
  • Dead code: functions with no callers, excluding entry points.
  • Compare two indexes: compare_graphs lists 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_query in search_graph): vector search with the bundled nomic-embed-code model compiled into the binary. No API key or model service.
  • Code search (search_code): grep over indexed files only.
  • Cross-repository search: one search_graph request 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

View on GitHub
GitHub Stars10
CategoryDevelopment
Updated2d ago
Forks4

Languages

C

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info