Codebase Memory

Overview

Codebase Memory is the project's code-intelligence layer for AI agents. It is powered by codebase-memory-mcp — a fast code intelligence engine for AI coding agents, distributed as a single static binary MCP server.

It builds a persistent knowledge graph of the repository and exposes it through graph-aware queries. Instead of grepping every file, agents and developers can search by natural language, trace call dependencies, and get architecture overviews — all backed by an indexed graph of functions, classes, routes, and their relationships.

The graph is stored per project under a project name (e.g. sutomo). It is not tied to a branch; it is a snapshot of the working tree at index time. Re-index after significant changes so the graph reflects the latest code.

GitHub: github.com/DeusData/codebase-memory-mcp

---

Features

• Graph indexing — builds a knowledge graph of functions, classes, interfaces, methods, enums, routes, channels, and their relationships (CALLS, USAGE, IMPORTS, WRITES, INHERITS, THROWS, ...).
• Graph-aware code search — finds matches, deduplicates them into containing functions, and ranks by structural importance.
• Natural-language search — BM25 ranking with structural boosting, camelCase splitting, and semantic-vector bridging.
• Dependency tracing — follow callers/callees, data flow, and cross-service HTTP/async calls.
• Architecture overviews — clusters (Leiden community detection), layers, boundaries, hotspots, and routes.
• Hotspot analysis — Cypher queries over complexity and loop-depth properties to find N+1 loops, recursion, and allocations in loops.
• Cross-project intelligence — match routes/channels across projects (CROSS_HTTP_CALLS, CROSS_ASYNC_CALLS).
• Persistence — optional compressed artifact (.codebase-memory/graph.db.zst) for team bootstrap.

---

Indexing the Repository

To index (or re-index) the current working tree into the project, run the index_repository tool with the path to this repository:

index_repository
  repo_path: <absolute-path-to-this-repo>
  name: sutomo
  persistence: true

• name is the project identifier used for all subsequent queries. Keep it stable (e.g. sutomo) so the same graph is reused.
• persistence: true writes a compressed artifact (.codebase-memory/graph.db.zst) so teammates can bootstrap from it instead of re-indexing.
• mode: full extracts files, similarity, and semantic edges (slowest but richest). fast skips similarity for speed.

The project is a single graph across branches; the Branch node records the last checked-out branch for provenance only.

---

Querying the Graph

All queries take the same project (e.g. sutomo).

Search code

search_code
  pattern: "Article::search"
  project: sutomo

Finds matches, deduplicates them into containing functions, and ranks by structural importance (definitions first). Use mode: full for source or mode: files for just file paths.

Natural-language search

search_graph
  query: "publish an article"
  project: sutomo

Ranks by BM25 with structural boosting (functions, methods, routes). Supports camelCase splitting, and semantic_query bridges vocabulary (e.g. finds publish when you search send).

Trace dependencies

trace_path
  function_name: "roundup"
  project: sutomo
  direction: both
  depth: 3

Follows CALLS edges to show callers/callees. mode: data_flow adds value propagation; mode: cross_service follows HTTP/async routes into other services.

Architecture overview

get_architecture
  project: sutomo
  aspects: ["overview"]

Returns clusters (de-facto modules via community detection), layers, boundaries, hotspots, and routes — useful for understanding seams before large changes.

Custom graph queries (Cypher)

query_graph
  query: "MATCH (f:Function) WHERE f.transitive_loop_depth >= 3 RETURN f.qualified_name"
  project: sutomo

Useful for hotspot analysis (N+1 loops, recursion, allocations in loops).

---

Refreshing the Index

Because the graph is a snapshot, refresh it after meaningful changes:

1. Make sure the working tree is in the state you want to index.
2. Run index_repository again with the same name and repo_path.
3. Confirm the newest files are present by searching for them.

The Branch node may lag behind the actual checked-out branch; it is only metadata and does not affect query correctness.

---

Key Files

File	Purpose
.codebase-memory/graph.db.zst	Persisted compressed graph artifact (when persistence: true)
graphify-out/	Optional graph export output