Foreword¶

In July 2026, the AI-related repositories on GitHub Trending were almost entirely dominated by Agent infrastructure: penetration testing Agents, trading Agents, coding Agents, and various MCP servers powering them. Among them, codebase-memory-mcp developed by DeusData became a hot project in the MCP ecosystem with approximately 32,000 stars (as of the time of writing, the star count is still growing on GitHub).

If you have used AI coding tools like Claude Code, Cursor, or Codex CLI, you have probably encountered this scenario: to answer a structural question such as “Who calls this function?” or “What HTTP routes are in this project?”, the Agent will repeatedly run grep and read files one by one, leading to rapid Token consumption and the context window being filled with irrelevant code. codebase-memory-mcp addresses this pain point: it uses the Model Context Protocol (MCP) to index the codebase into a persistent knowledge graph, allowing Agents to replace blind file browsing with structured queries. According to official benchmarks, Token consumption for structural questions can be reduced by approximately 120x (5 typical queries total ~3,400 Tokens, compared to ~412,000 Tokens for file-by-file exploration).

This article cross-verifies information from the official GitHub repository, project documentation, and the July 2026 Analytics Vidhya Trending report, introducing the design philosophy, core capabilities, and onboarding process of codebase-memory-mcp.

What is codebase-memory-mcp¶

codebase-memory-mcp is an open-source MCP server maintained by DeusData and released under the MIT license. It is not positioned as a chatbot, but rather a code structure analysis backend — it does not embed an LLM internally, nor does it require an API Key. The MCP client you are using (Claude Code, Cursor, etc.) is responsible for “understanding the question”, while codebase-memory-mcp is responsible for “building and providing the knowledge graph”.

The workflow can be summarized in three steps:
1. Indexing: Use tree-sitter to parse source code, combine with Hybrid LSP for type inference, and write functions, classes, call chains, HTTP routes, cross-service links, etc., into a SQLite knowledge graph;
2. Persistence: The graph is saved locally (default path: ~/.cache/codebase-memory-mcp/), and team-shared compressed snapshots (.codebase-memory/graph.db.zst) are supported;
3. Querying: The Agent uses 15 MCP tools to ask the graph questions, returning results in milliseconds instead of reading files one by one.

The project is distributed as a single static C binary that runs on macOS, Linux, and Windows, with zero runtime dependencies. According to official statements, full indexing of a regular repository is completed in milliseconds, and the Linux kernel (approximately 28 million lines of code, 75,000 files) can be indexed in about 3 minutes.

Why Agents need “codebase memory”¶

MCP (Model Context Protocol) is an open protocol promoted by Anthropic that allows LLM applications to connect external tools and data sources in a unified way. In coding scenarios, MCP servers can expose capabilities such as “search code”, “read files”, and “run tests”; but most implementations are stateless — the Agent must re-explore the codebase for every conversation.

For large codebases, this exploration model has three costs:
1. Token cost: According to the project benchmark, five structural questions require approximately 412,000 Tokens if searched file by file; using a knowledge graph only requires ~3,400 Tokens. At common API pricing (in the order of dollars per million Tokens), exploration costs will accumulate rapidly.
2. Latency: Official claims state that graph queries are sub-millisecond; reading files one by one often takes several seconds or longer.
3. Accuracy: The context is filled with a large number of irrelevant fragments, which easily leads to “lost in the middle” — the model misses key information.

codebase-memory-mcp transforms “codebase understanding” from a one-time exploration during a conversation into a reusable persistent index. After file changes, the background watcher can perform incremental re-indexing; Git diff can also be mapped to affected symbols for change impact analysis.

Core Capabilities: Knowledge Graph and Hybrid LSP¶

tree-sitter: Syntax parsing for 158 languages¶

The project includes vendored tree-sitter grammars covering 158 languages including Python, Go, Rust, Java, TypeScript, and C/C++, as well as infrastructure formats such as Dockerfile, Kubernetes manifests, and HCL. The syntax parsing layer is responsible for extracting syntactic structures like functions, classes, imports, and call sites.

Hybrid LSP: Semantic enhancement for 10 languages¶

AST alone cannot answer questions like “Which class and method does user.profile.display_name() actually resolve to?” — this requires tracking imports, generics, and inheritance chains. codebase-memory-mcp embeds a lightweight type inference implementation in the binary (structurally referencing tsserver, pyright, gopls, rust-analyzer, etc.), providing Hybrid LSP enhancement for the following languages:
- Python, TypeScript / JavaScript / JSX / TSX
- PHP, C#, Go, C / C++
- Java, Kotlin, Rust, Perl

After the two-layer pipeline is combined, edges like CALLS, USAGE, and RESOLVED_CALLS in the graph are as accurate as the “jump to definition” function in an IDE. For other languages, it falls back to text-level parsing, which is still usable but has lower cross-file type inference accuracy.

Semantic Retrieval: Local Embedding, No External Network Required¶

In addition to structured search, search_graph supports the semantic_query parameter, which uses the nomic-embed-code vector model (768-dimensional, int8 quantized) compiled into the binary for semantic search — searching for send may hit publish or emit. Embedding runs locally, and code never leaves the machine. The indexer also writes SEMANTICALLY_RELATED (conceptually similar) and SIMILAR_TO (near-duplicate/clone) edges.

What can the 15 MCP tools do¶

Agents call the following typical tools via MCP (see the official documentation for the full list):

There are also cross-repository queries, HTTP route discovery, BM25 full-text search, etc. REST/gRPC/GraphQL/tRPC routes are treated as first-class nodes in the graph, matching cross-service HTTP call points.

An optional 3D graph visualization UI (install with --ui) provides interactive browsing at localhost:9749.

Token and Performance: What Do the Official Data Say¶

The project documentation and arXiv preprint Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277) provide the following reference figures:

Token comparison for five structural questions (project benchmark):

The preprint’s evaluation on 31 real-world repositories also reported that compared to file-by-file exploration, answer quality is ~83%, Tokens are reduced by ~10x, and tool call count is reduced by ~2.1x. Please note: the specific savings vary by repository size, question type, and Agent strategy; the above figures are from official test scenarios and should not be treated as guaranteed values for all projects.

Indexing and Query Performance (measured on Apple M3 Pro):

Quick Start¶

Installation¶

One-line script for macOS/Linux:

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

Add --ui if you need the 3D visualization UI:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

For Windows, you can download and run install.ps1. You can also install via npm, PyPI, Homebrew, Scoop, Winget, and other channels.

The install command will automatically detect locally installed coding Agents and write MCP configurations. The official documentation lists 43 automatically/conditionally supported client surfaces, including Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, Aider, OpenCode, Windsurf, etc.; some clients (such as Continue, Visual Studio) require explicit configuration.

Indexing and Usage¶

After installation, restart the coding Agent and tell the Agent “Index this project” to trigger indexing. Afterwards, the Agent will call MCP tools when structural information is needed, for example:

# CLI mode example (does not start the coordination daemon, suitable for scripts)
codebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function
codebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both

Cypher query example:

MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

The indexing artifacts are stored in ~/.cache/codebase-memory-mcp/ by default. Teams can commit .codebase-memory/graph.db.zst to the repository, allowing new members to skip full re-indexing.

Applicable Scenarios and Usage Notes¶

Good for:
- Monolithic or microservice large codebases where Agents frequently perform structural exploration;
- Teams with standardized MCP toolchains (Claude Code, Cursor, etc.);
- Scenarios requiring local offline processing where code never leaves the environment;
- Engineering needs such as call chain analysis, dead code detection, and change impact assessment.

Points to note:
1. Security: The tool will read the codebase and modify the Agent’s MCP configuration files, which is designed behavior. It is recommended to obtain signed binaries from the official GitHub repository or compile and audit the source code yourself.
2. Initial indexing cost: Ultra-large repositories (like kernel-level projects) still take several minutes; semantic edges are skipped in fast indexing mode, and full semantic capabilities require full / moderate mode.
3. Not a universal replacement: It solves structural intelligence and cannot replace running tests, reading business documents, or understanding product requirements. For languages not covered by Hybrid LSP, cross-file type inference accuracy is limited.
4. Complementary to RAG document tools: Tools like LangChain’s OpenWiki focus on “AI-readable documents”; codebase-memory-mcp focuses on “code structure graphs”. The two can coexist.

Summary¶

codebase-memory-mcp combines the MCP protocol, tree-sitter syntax parsing, Hybrid LSP semantic inference, and SQLite knowledge graphs to provide AI coding Agents with persistent, queryable codebase memory. Behind the official benchmark and Trending popularity, it points to a clear direction: infrastructure in the Agent era is shifting from “re-grepping for every conversation” to “one-time indexing, repeated queries” — balancing Token cost, response speed, and structural accuracy.

If you are using large model Agents to maintain medium to large projects, it is worth spending 10 minutes installing and trying it out. After indexing, ask the Agent a few structural questions (call chains, route tables, architecture layers) and compare the Token consumption and answer quality with and without the MCP graph, then decide whether to include it in your team’s standard toolchain.

References:
- DeusData/codebase-memory-mcp (GitHub)
- Official Project Documentation
- Analytics Vidhya: July 2026 GitHub AI Trending Top 10
- arXiv:2603.27277 Preprint