codebase-memory-mcp

codebase-memory-mcp is a high-performance code intelligence engine designed for AI coding agents. It uses tree-sitter AST analysis and Hybrid LSP semantic type resolution to build a persistent knowledge graph of functions, classes, call chains, and more.

Key features include:

• Extreme Speed: Indexes massive repositories (e.g., the Linux kernel) in minutes using a RAM-first pipeline with LZ4 compression and in-memory SQLite.
• Zero Dependencies: Ships as a native executable for macOS, Linux, and Windows. It requires no Docker, language runtimes, or API keys.
• Language Support: Supports 158 languages via vendored tree-sitter grammars.
• Token Efficiency: Reduces token usage by up to 120x compared to file-by-file exploration by replacing multiple grep/read cycles with single structural graph queries.
• Local Processing: All indexing and processing happen 100% locally; code never leaves your machine.
• Visualization: Includes a built-in 3D interactive graph visualization UI accessible at localhost:9749.

Hybrid LSP is a lightweight C implementation of language type-resolution algorithms embedded directly into the codebase-memory-mcp native executable. It works alongside tree-sitter to provide semantic type resolution beyond simple syntactic AST parsing.

How it works:

1. Tree-sitter pass: A fast, syntactic pass that extracts definitions, calls, and imports for 158 languages.
2. Hybrid LSP pass: A type-aware pass that runs above the tree-sitter pass for supported languages. It uses an import graph and a per-file or cross-file definition registry to refine call edges (CALLS / RESOLVED_CALLS) and callable-value resolution (CALL_REFERENCE).

This allows the knowledge graph to resolve complex relationships like imports, generics, inheritance, and standard library types (e.g., resolving user.profile.display_name() to its actual declaration) without requiring a separate language server process (like tsserver or pyright) to be running.

To ensure comparability across 159 languages, every bespoke question is mapped to one of five universal dimensions (D1–D5). This mapping allows for aggregation across languages and groups.

Note on D5: For Group E (config/markup/schema), D5 is interpreted structurally (e.g., duplication or config↔code links) and is not aggregated across groups to avoid noise. For languages where a dimension is not applicable (e.g., call graphs on csv), the dimension is marked N/A.

When evaluating the codebase memory, the following tool patterns (D1-D5) are used to interact with the graph and code:

• D1 (Definition/API): Use search_graph with a name_pattern and label to find specific symbols.
• D2 (Relationship): Use trace_call_path with a qualified_name and direction (e.g., "both") to reconstruct call graphs.
• D3 (Retrieval): Use get_code_snippet with a qualified_name to extract specific function bodies.
• D4 (Architecture): Use get_architecture with a scope to describe structural organization.
• D5 (Semantic/Cross-cutting): Use search_code or semantic_query to find patterns, clusters, or semantic similarities that plain text search might miss.

// Example D1: Search for functions matching a pattern
D1->search_graph(name_pattern=".*FunctionEmitContext.*|^Optimize$", label="Class/Function");

// Example D2: Trace bidirectional call paths
D2->trace_call_path(qualified_name="Module::CompileFile", direction="both");

// Example D3: Get a specific code snippet
D3->get_code_snippet(qualified_name="Module::CompileFile");

// Example D4: Get architecture for a scope
D4->get_architecture(scope="src/");

// Example D5: Semantic query
D5->search_code/semantic_query("emit masked store / gather / varying value for SPMD type");

The evaluation plan uses five bespoke question dimensions (D1-D5) to test the capabilities of the codebase memory system across different languages. These dimensions are:

• D1: Definition/API: Testing the ability to list top-level definitions or keywords (e.g., finding module declarations or specific node definitions).
• D2: Relationship: Testing the ability to map cross-file reference structures, such as import chains, include dependencies, or call paths.
• D3: Retrieval: Testing the ability to retrieve a full, specific code snippet or subtree based on a qualified name or anchor.
• D4: Architecture: Testing the ability to describe the file/directory organization and the structural decomposition of the project.
• D5: Cross-cutting/Semantic: Testing the ability to find naming patterns, duplication clusters, or semantic links (e.g., linking configuration strings to code implementations) that standard text search cannot resolve structurally.

The CBM indexer generates a graph representation of a codebase. To evaluate the quality of the index, the system tracks specific node and edge statistics.

Key Metrics:

• Index time: The time taken for a clone + cold index (the primary performance metric).
• Node-type histogram: Counts of specific entities like Function, Method, Class, Struct, Interface, Trait, Enum, File, Folder, Type, Field, Variable, Route, Module, Section, and Macro.
• Edge-type histogram: Counts of relationships between nodes. There are 32 edge types, including structural relationships (DEFINES, IMPLEMENTS, INHERITS, IMPORTS), call relationships (CALLS, ASYNC_CALLS, HTTP_CALLS, GRPC_CALLS, GRAPHQL_CALLS, TRPC_CALLS), and semantic/utility relationships (DEPENDS_ON, USAGE, DATA_FLOWS, SEMANTICALLY_RELATED, SIMILAR_TO, TESTS, TESTS_FILE, INFRA_MAPS, FILE_CHANGES_WITH, CONTAINS_FILE, CONTAINS_FOLDER, DECORATES, HANDLES, CONFIGURES).

Critical Signal in Zeros: Reporting a count of 0 for an edge type is a critical diagnostic signal:

• CALLS=0: Indicates broken call-extraction.
• IMPLEMENTS/INHERITS/OVERRIDE=0: Indicates a lack of Object-Oriented relation edges.
• SIMILAR_TO/SEMANTICALLY_RELATED=0 (in LSP languages): Indicates a semantic-index gap.
• CROSS_* rows being 0: Expected for non-LSP languages; for the 9 LSP cross-repo pairs, these should carry real counts.

### Node Labels
| Function | Method | Class | Struct | Interface | Trait | Enum | File | Folder | Type | Field | Variable | Route | Module | Section | Macro |

### Edge Types
| CALLS | ASYNC_CALLS | HTTP_CALLS | GRPC_CALLS | GRAPHQL_CALLS | TRPC_CALLS | DEFINES | DEFINES_METHOD | IMPLEMENTS | INHERITS | OVERRIDE | DECORATES | IMPORTS | HANDLES | CONFIGURES | DEPENDS_ON | USAGE | DATA_FLOWS | SEMANTICALLY_RELATED | SIMILAR_TO | TESTS | TESTS_FILE | INFRA_MAPS | FILE_CHANGES_WITH | CONTAINS_FILE | CONTAINS_FOLDER | CROSS_HTTP_CALLS | CROSS_ASYNC_CALLS | CROSS_GRPC_CALLS | CROSS_GRAPHQL_CALLS | CROSS_TRPC_CALLS | CROSS_CHANNEL |

The project is organized into several core functional modules:

• main.c: Entry point for the MCP stdio server, CLI, and installation/config.
• daemon/: Handles per-account session coordination, IPC, and lifecycle management.
• mcp/: The MCP server implementation providing 15 tools via JSON-RPC 2.0.
• cli/: Provides 43 client surfaces for installation, uninstallation, updates, and configuration.
• store/: SQLite-based graph storage for nodes, edges, traversal, and search.
• pipeline/: Manages the multi-pass indexing process.
• cypher/: Lexer, parser, planner, and executor for Cypher queries.
• discover/: Handles file discovery, including .gitignore and .cbmignore support.
• watcher/: Background auto-sync via git polling and adaptive intervals.
• ui/: Local HTTP server and 3D-UI asset pack.
• internal/cbm/: Vendored tree-sitter grammars and the AST extraction engine.

The evaluation plan uses five universal dimensions to test codebase intelligence across different languages. These dimensions are designed to measure specific capabilities of the graph and semantic search engines:

• D1: Definition/API: Locating public API surfaces, class definitions, and type aliases using name patterns.
• D2: Relationship: Mapping inbound and outbound call graphs (e.g., tracing which functions a method calls and which methods call it).
• D3: Retrieval: Extracting exact source code snippets for specific named symbols or classes.
• D4: Architecture: Describing the repository structure, layer dependencies, and the location of canonical sources vs. build artifacts.
• D5: Cross-cutting/Semantic: Using semantic queries to find conceptually related code (e.g., finding all 'delete' operations even if the literal token is 'remove') that spans multiple files or is obscured by macros.

The codebase-memory-mcp evaluation process tracks specific graph metrics to assess indexing quality. Two primary histograms are captured at index time: Node-type histogram and Edge-type histogram.

Key Metric: Index time (clone + cold index) is the primary performance metric.

Critical Signal (Zero Values): A count of 0 for certain edge types is a critical diagnostic signal:

• CALLS=0: Indicates broken call-extraction (CALLS_MISSING).
• IMPLEMENTS/INHERITS/OVERRIDE=0: Indicates a lack of Object-Oriented (OO) relation edges.
• SIMILAR_TO/SEMANTICALLY_RELATED=0 (on full-mode LSP languages): Indicates a semantic-index gap.
• CROSS_* rows: These should be 0 for non-LSP languages and only carry real counts for the 9 specific LSP cross-repo pairs.

### Node-type histogram
| Node label | Count |
|---|---|
| Function | _ |
| Method | _ |
| Class | _ |
| Struct | _ |
| Interface | _ |
| Trait | _ |
| Enum | _ |
| File | _ |
| Folder | _ |
| **Total nodes** | _ |

### Edge-type histogram
| Edge type | Count |
|---|---|
| CALLS | _ |
| ASYNC_CALLS | _ |
| HTTP_CALLS | _ |
| GRPC_CALLS | _ |
| GRAPHQL_CALLS | _ |
| TRPC_CALLS | _ |
| DEFINES | _ |
| DEFINES_METHOD | _ |
| IMPLEMENTS | _ |
| INHERITS | _ |
| OVERRIDE | _ |
| DECORATES | _ |
| IMPORTS | _ |
| HANDLES | _ |
| CONFIGURES | _ |
| DEPENDS_ON | _ |
| USAGE | _ |
| DATA_FLOWS | _ |
| SEMANTICALLY_RELATED | _ |
| SIMILAR_TO | _ |
| TESTS | _ |
| TESTS_FILE | _ |
| INFRA_MAPS | _ |
| FILE_CHANGES_WITH | _ |
| CONTAINS_FILE | _ |
| CONTAINS_FOLDER | _ |
| CROSS_HTTP_CALLS *(LSP pass)* | _ |
| CROSS_ASYNC_CALLS *(LSP pass)* | _ |
| CROSS_GRPC_CALLS *(LSP pass)* | _ |
| CROSS_GRAPHQL_CALLS *(LSP pass)* | _ |
| CROSS_TRPC_CALLS *(LSP pass)* | _ |
| CROSS_CHANNEL *(LSP pass)* | _ |
| **Total edges** | _ |