Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
10.7 KB
Raw Blame

codebase-memory-mcp — Research Report

Repo: https://github.com/DeusData/codebase-memory-mcp · MIT · pure C, single static binary. Snapshot: 2026-09-03: ~42k stars, ~3.4k forks, created 2026-02, pushed daily. Preprint: "Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP" (arXiv:2603.27277).

Category caveat. codebase-memory-mcp ("cbm") is code-structure memory, so it does not compete with session memory. It answers "what is this code and how does it connect?", while ai-memory answers "what did we do and decide, and why?". An agent can run both: cbm to navigate the code, ai-memory to recall the work. This report reads cbm for ideas to borrow.

1. Purpose & Scope

"The fastest and most efficient code intelligence engine for AI coding agents." It parses a repository into a persistent knowledge graph so an agent can ask structural questions (call chains, routes, impact of a change) with a single graph query instead of dozens of grep/read cycles. The headline claim is ~120× fewer tokens ("5 structural queries: ~3,400 tokens vs ~412,000 via file-by-file search", a 99.2% reduction). It also claims to index the Linux kernel (28M LOC) in ~3 minutes and answer Cypher queries in <1ms.

2. Architecture

  • Indexing: multi-pass tree-sitter AST over 162 languages, plus a "lightweight C implementation of language type-resolution algorithms" ("Hybrid LSP") that resolves imports/generics/inheritance/type inference tree-sitter alone can't. It is structurally compatible with tsserver / pyright / gopls / Roslyn / rust-analyzer but embedded and offline.
  • Pipeline: "RAM-first: LZ4 compression, in-memory SQLite, fused Aho-Corasick pattern matching. Memory released after indexing."
  • Storage: SQLite at ~/.cache/codebase-memory-mcp/ (ai-memory also uses a single SQLite database).
  • Graph model: nodes (Project, Package, File, Function, Class, Route, …) and edges (CALLS, IMPORTS, IMPLEMENTS, HTTP_CALLS, DATA_FLOWS, SIMILAR_TO, SEMANTICALLY_RELATED), with bundled nomic-embed-code embeddings (768d int8) compiled into the binary for semantic_query.
  • Zero runtime, zero network: pure C, vendored grammars + embeddings compiled in, "makes no network request of its own accord": no telemetry and no version check. Everything runs locally.

3. Agent Interface (15 MCP tools)

search_graph, trace_path (BFS call chains, depth 1–5), query_graph (read-only openCypher subset), get_architecture (languages/routes/hotspots/ clusters in one call), detect_changes (git diff → affected symbols with risk classification), semantic_query (vector search over the graph), search_code, get_code_snippet, ingest_traces (runtime-trace validation of HTTP_CALLS), manage_adr (Architecture Decision Records CRUD), plus index_repository / index_status / list_projects / delete_project / get_graph_schema.

4. Freshness & Team Sharing

  • Auto-sync watcher re-indexes on file change (auto_watch default true), much like ai-memory's wiki watcher keeps its index live.
  • Committed, compressed derived index: ".codebase-memory/graph.db.zst is a zstd-compressed snapshot of the knowledge graph" checked into the repo; new clones decompress and run incremental indexing instead of a full reindex. Two-tier compression (zstd -9 + VACUUM INTO on explicit index, zstd -3 for the watcher's low-latency updates).
  • Session-coordination daemon: one per-account daemon shared across ~45 agent surfaces. The first session starts it, each session registers its work, and the last one shuts it down.

5. Distinctive Ideas Worth Noting

  • Committing a compressed derived index for team sharing (graph.db.zst in-repo). ai-memory keeps its DB derived/rebuildable and shares through the server instead; cbm's git-artifact model is the offline, server-less alternative. The trade-off is worth keeping in mind (see the ECC and landscape notes on git-shared vs server-mediated).
  • Multi-tier agent profiles: auto-generated Scout (fast discovery) / Verify (task-directed evidence) / Auditor (exhaustive) profiles, each with an "exact per-tier graph-tool list" to prevent over-permissioning. This is the idea that transfers best: expose different subsets of tools to different task phases.
  • detect_changes → risk classification: maps a git diff to affected symbols and a risk score. It resembles ai-memory's typed-edge/contradiction lint, applied to code instead of knowledge.
  • Token-efficiency as the headline metric, benchmarked and published. ai-memory publishes LongMemEval numbers the same way; cbm's main metric is "queries vs grep tokens".

6. What Good / What's Missing — Honest Take

A complement, not a competitor. cbm indexes the codebase; ai-memory indexes the work. cbm knows the code as it is right now; ai-memory knows the decisions, gotchas, sessions, and handoffs, which is the reasoning and history no AST carries. An agent that needs both "where is this function called" and "why did we build it this way" needs both tools.

Ideas ai-memory could borrow:

  1. Tiered tool exposure (Scout/Verify/Auditor). ai-memory ships ~18 MCP tools to every client at every phase; a task-phase-scoped subset (e.g. a read-only "recall" tier vs a full "curate" tier) would cut prompt surface and over-permissioning. Worth considering alongside the rules-promotion work (docs/design-rules-promotion.md).
  2. The token-efficiency framing as a first-class, published metric for the retrieval side (ai-memory already benchmarks recall; "tokens to answer" is the complementary axis).
  3. A committed, compressed derived-index option for server-less small teams, the same idea flagged in research-ecc.md's git-shared team scope.

Where ai-memory is simply doing a different (harder-for-its-domain) job:

  • Automatic, sanitized session capture and cross-agent handoff; LLM consolidation into human-readable knowledge; temporal as_of; a server for multi-user/multi-machine use. cbm does none of that because it watches files, never sessions.

Bottom line. codebase-memory-mcp is a strong, narrowly scoped code-intelligence engine that pairs well with ai-memory. The lessons for us are operational rather than architectural: tiered tool profiles, a published token-efficiency metric, and (optionally) a git-committed compressed index for teams that won't run a server.

7. 2.1 Feasibility — grounded in ai-memory's code

Each borrowable idea was checked against the current tree so the release call rests on real choke points. Verdicts: one 2.1 feature, one land-now dev metric, one deferred design.

7.1 Tiered tool profiles — recommend for 2.1

Where it plugs in. The MCP server exposes 23 tools through the rmcp #[tool_router] macro (crates/ai-memory-mcp/src/server.rs:1239), and list_tools (server.rs:3966) is the single choke point. It returns tool_router.list_all() unfiltered, with only a per-dialect schema reshape (restricted_schema_tool_list, server.rs:4021) that never drops a tool. A read/write partition already exists: tool_call_is_write (server.rs:757) classifies 8 tools as read-only (query, read_page, read_session_observations, recent, briefing, explore, status, install_self_routing). Today it is used only for rate-limit accounting, not visibility.

Why 2.1. 23 tools is a heavy MCP prompt surface pushed to every client every turn. A read-only "recall" tier (the 8 already-classified tools) versus the full "curate" tier cuts prompt surface and over-permissioning for the common case (an agent that only recalls never needs delete_page/forget_sweep). The change is small and self-contained, and it pairs directly with the rules-promotion work (docs/design-rules-promotion.md): both give the agent less, better-scoped authority by default.

Shape. Add a --tool-profile recall|full flag to ServeArgs (crates/ai-memory-cli/src/cli.rs:2119), or a per-request ?profile= marker mirroring the existing ?flavor= mechanism (server.rs:3980); filter list_all() by tool_call_is_write before returning. No new classification logic is needed because the partition already exists.

7.2 Token-efficiency metric — land on main now (dev tooling, not a gated feature)

Where it plugs in. The evals/ crate measures hit@k / recall@k only (evals/src/retrieval/score.rs). The full memory_query JSON payload is already materialized in exactly one place before parsing, evals/src/retrieval/query.rs:114 (text holds the complete content string), so text.len() / a tokenizer pass yields a per-question "tokens to answer" number with zero server changes, threaded into report.rs.

Why not gated to 2.1. It changes no runtime behavior and ships nothing user-facing. It is an eval/benchmark improvement that complements LongMemEval recall: recall says we find the answer, tokens-to-answer says we deliver it cheaply. It can go to main at any time, independent of the 2.1 train.

7.3 Committed compressed derived-index — defer (design-only until a server-less use-case exists)

Where it plugs in. The DB is contractually derived and rebuildable: markdown-in-git is the source of truth, SQLite db/ is the index (crates/ai-memory-wiki/src/lib.rs:3, docs/companion-crates.md:14), with a working rebuild (ai-memory reindex, crates/ai-memory-cli/src/commands/reindex.rs) and an online-backup tarball producer (POST /admin/backup, crates/ai-memory-mcp/src/admin.rs:746). So a committed graph.db.zst-style artifact fits the model mechanically.

Why defer. It is a different distribution model and too large to count as a small feature. ai-memory's multi-user/multi-machine story is server-mediated by design (attributed writes, per-user scope, live handoff); a git-committed binary index is the server-less counterpart, and it brings in snapshot-consistency, staleness, regeneration cadence, and binary-blob merge conflicts. Building it before there is a concrete server-less small-team customer would be speculative. It belongs in the same "consider a git-shared team scope" bucket as research-ecc.md §8.4, to be designed only if that path is chosen.

Recommendation summary

Insight Verdict Effort Where
Tiered tool profiles 2.1 feature small (choke point + existing partition) release/2.1
Token-efficiency metric land now low (additive, one choke point) main, any time
Committed compressed index defer large (distribution model) design-only, needs use-case

Sources