Codebase-Memory: Graph Code Representation

• Codebase-Memory is a graph-centric system that represents entire code repositories as richly annotated knowledge graphs to support efficient structural queries.
• It employs Tree-Sitter for AST extraction across 66 languages and utilizes SQL and in-memory graph algorithms for sub-millisecond call tracing and impact analysis.
• Key benefits include significant token savings, deep structural insights, and LLM integration via MCP, enhancing accurate codebase reasoning.

Codebase-Memory is a graph-centric system for codebase-scale knowledge representation, search, and reasoning—architected for LLM-enabled software agents—built on Tree-Sitter–derived property graphs and exposed via Model Context Protocol (MCP). Rather than organizing source code as raw files, Codebase-Memory persists the entire repository as a richly annotated knowledge graph, permitting token-efficient and structurally precise queries over definitions, call graphs, types, imports, and higher-order code relationships. Its design supports parsing across 66 programming languages and provides a suite of sub-millisecond, graph-native tools for call tracing, change impact analysis, and macro-architectural community discovery, all accessible through MCP-compliant interfaces (Vogel et al., 28 Mar 2026).

1. Conceptual Foundation

Codebase-Memory departs from traditional LLM agent code search, which relies on repeated file reading and grep-style pattern extraction, instead rendering the repository as a persistent, queryable knowledge graph. The system’s goals are threefold: achieve order-of-magnitude savings in token consumption, furnish agents with direct structural insight beyond what file-level context provides, and enable deployment as a zero-external-dependency static binary with SQLite backing. The system aligns with recent architectural trends emphasizing the separation of structural code knowledge from raw source text to improve LLM reasoning efficiency and reliability (Vogel et al., 28 Mar 2026).

2. Pipeline Architecture: Parse, Build, Serve

Codebase-Memory’s pipeline comprises three primary stages:

1. Parse: Language-agnostic AST extraction using Tree-Sitter grammars (currently 66 supported languages). The parser incrementally generates ASTs for every source file, feeding custom extractors for definition and relation detection.
2. Build: A multi-phase, in-memory staged pipeline executes six graph construction phases within a single SQLite transaction:
   • Directory/package/file/containment node and edge instantiation.
   • Parallel function/class/interface/method extraction and signature tagging.
   • Resolution of CALLS, IMPORTS, USES_TYPE, IMPLEMENTS, INHERITS, and DECORATES edges using import maps, local lookups, and fuzzy heuristics.
   • Graph enrichment with test file links, HTTP routes, config relationships, and Git co-change data.
   • Bulk flushing of buffered nodes/edges, with deferred index creation.
   • Community detection (via Louvain modularity) and content fingerprinting.
3. Serve: The built graph is exposed via a local MCP JSON-RPC server, offering 14 typed query tools (e.g., search_graph, trace_call_path, detect_changes). All graph operations are implemented either in SQL (using recursive CTEs for traversal) or via in-memory graph algorithms executed by parallel worker pools. Latency for core queries (BFS depth=5, 200k edges) is typically 0.3 ms (Vogel et al., 28 Mar 2026).

3. Graph Schema and Algorithmic Subsystems

The knowledge graph’s schema includes nodes for Projects, Packages, Folders, Files, Functions, Methods, Classes, Types, Interfaces, Enums, Decorators, Test Files, Configuration, and Community assignments. Edges represent a rich set of semantic relationships: CONTAINS, CALLS, IMPORTS, USES_TYPE, IMPLEMENTS, INHERITS, DECORATES, COCHANGES, and MEMBER_OF (for community structure).

Key algorithmic subsystems comprise:

• BFS Call Tracing: For questions such as “which functions call X,” the system executes an adjacency-list BFS over the CALLS subgraph, bounded by a user-supplied depth $d_{\max}$:

$\textbf{CallBFS}(G, S, d_{\max}): \ldots$

Time complexity is $O(|V|+|E|)$ per traversal.

• Impact Analysis: Upon git diffs, impact propagation computes for each node $v$ an impact score via

$$I(v)\;=\;\sum_{u\in C}\alpha^{\,\mathrm{dist}(u,v)},\;0<\alpha<1$$

where $C$ is the changed definition set, and $\mathrm{dist}(u,v)$ is shortest-path in CALLS+IMPORTS.

• Community Detection: Louvain optimization for maximizing modularity $Q$, mapping nodes to communities:

$$Q = \frac{1}{2m} \sum_{i,j} [A_{ij} - \frac{k_i\,k_j}{2m}]\delta(c_i,c_j)$$

Assignments are stored via MEMBER_OF edges, enabling downstream macro-architecture queries.

4. MCP Interface and LLM Integration

All query operations are exposed as Model Context Protocol tools, using JSON-RPC 2.0. For example, agents can invoke trace_call_path to trace inbound or outbound connectivity for a symbol up to a specified depth, or apply detect_changes to localize impact regions after a refactor. These methods surface structured JSON blocks, integrating easily with contemporary LLM agent tool-call semantics. The design philosophy matches that of Codified Context knowledge bases (Vasilopoulos, 24 Feb 2026), but Codebase-Memory distinguishes itself by providing sub-token-level graph traversal operations and a strictly graph-first abstraction (Vogel et al., 28 Mar 2026).

5. Quantitative Evaluation and Empirical Results

The system has been benchmarked on 31 real-world repositories spanning 78–49,398 nodes and 66 programming languages (Vogel et al., 28 Mar 2026). Head-to-head against a file-explorer agent, Codebase-Memory using MCP tools achieves:

Metric	MCP Agent	Explorer Agent	Ratio
Answer quality ($\bar Q$)	0.83	0.92	90%
Calls/question ($\textbf{CallBFS}(G, S, d_{\max}): \ldots$0)	2.3	4.8	×1/2.1
Tokens/question ($\textbf{CallBFS}(G, S, d_{\max}): \ldots$1)	∼1,000	∼10,000	×1/10
Latency ($\textbf{CallBFS}(G, S, d_{\max}): \ldots$2)	<1ms	10–30s	×100

For graph-native tasks such as hub detection and caller ranking (using HITS/PageRank metrics), the MCP agent matched or outperformed direct file exploration in 19 of 31 languages. F1 quality is computed as $\textbf{CallBFS}(G, S, d_{\max}): \ldots$3, averaged across questions (Vogel et al., 28 Mar 2026).

6. Advantages, Limitations, and Future Directions

Advantages:

• Token-efficiency: Empirically, $\textbf{CallBFS}(G, S, d_{\max}): \ldots$4, allowing deeper semantic queries within LLM context limits.
• Latency: All primary queries execute in sub-millisecond time.
• Structural fidelity: Call, import, and type hierarchies are natively represented and traversable.
• Cross-language support: Full parsing and graph construction for 66 languages.

Limitations:

• Omits line-level content and thus cannot serve exhaustive source pattern queries or deep macro expansion (e.g., via libclang).
• For tasks requiring verbatim code context or non-structural content matching, hybrid file+graph approaches are required.

Future work:

• Integrate macro expansion support and ingest dynamic analysis traces.
• Add high-performance backends (e.g., Neo4j, PGQL, in-memory graph stores) for further latency improvement at scale.
• Explore hybrid context modeling (graph-augmented LLM attention).
• Develop schema evolution from CI/review metadata (Vogel et al., 28 Mar 2026).

7. Position in the Codebase Memory Systems Landscape

Codebase-Memory represents one axis of the broader codebase-memory design space, contrasting with hot/cold tiered context systems (such as Codified Context (Vasilopoulos, 24 Feb 2026)) and meta-evolutionary agent memory architectures (MemEvolve/EvolveLab (Zhang et al., 21 Dec 2025)). Where those systems focus on hybrid retrieval or meta-adaptive memory evolution, Codebase-Memory is distinguished by its exclusive use of graph-theoretic representations and its end-to-end integration with LLM agent tool APIs via MCP. It is especially optimized for tasks that are fundamentally structural—call tracing, impact analysis, modular decomposition—on codebases ranging from small DSLs up to tens of millions of lines (Vogel et al., 28 Mar 2026).