Main Components of codebase-memory-mcp: Architecture of the Knowledge Graph Engine

codebase-memory-mcp is a static-analysis engine that converts entire source repositories into persistent knowledge graphs through three integrated layers: an indexing pipeline with 158 Tree-Sitter grammars, a compressed SQLite graph store, and a comprehensive query toolkit for AI coding agents.

The codebase-memory-mcp repository from DeusData implements a high-performance static analysis system designed specifically for AI-assisted coding workflows. Unlike traditional code search tools, this Model Context Protocol (MCP) server constructs a persistent, queryable knowledge graph that captures deep semantic and structural relationships across 12+ programming languages. Understanding the main components of codebase-memory-mcp reveals how it achieves sub-millisecond query performance while remaining completely local and offline-capable.

The Three Core Layers of codebase-memory-mcp

1. The Indexing Pipeline

The indexing layer transforms raw source code into a structured graph using a RAM-first design that maximizes throughput while minimizing disk I/O.

• Multi-language parsing – The system ships with 158 vendored Tree-Sitter grammars (enumerated in opencode.json) providing robust parsing for diverse language constructs without external dependencies.
• Hybrid LSP resolution – A lightweight Language Server Protocol implementation resolves imports, type information, and cross-service links for 12+ languages including Python, TypeScript/JS/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust, and Perl.
• Compression pipeline – During indexing, data resides in an in-memory SQLite database with LZ4 compression, then serializes to a zstd-compressed snapshot (.codebase-memory/graph.db.zst) handled by internal/cbm/zstd_store.c and internal/cbm/zstd_store.h.
• Entry points – The index_repository CLI command triggers one-shot indexing, while the background watcher (src/watcher/watcher.c) monitors filesystem changes for continuous updates.

2. The Persistent Knowledge Graph

At the heart of the system lies a richly-typed graph database that persists across agent sessions via a coordination daemon.

Node types represent structural entities:

• Project, Package, Folder, File – Container hierarchies
• Module, Class, Function, Method – Code entities
• Interface, Enum, Type – Type system elements
• Route, Resource – Service endpoints

Edge relationships capture semantic connections:

• CALLS, IMPORTS, DEFINES, IMPLEMENTS – Standard code relationships
• HTTP_CALLS, ASYNC_CALLS, EMITS, LISTENS_ON – Service communication patterns
• DATA_FLOWS, SIMILAR_TO, SEMANTICALLY_RELATED – Semantic associations

The graph automatically shares state across all agent sessions through the coordination daemon, with logs written to ${CBM_CACHE_DIR}/logs/ as documented in docs/SECURITY.md.

3. The Query and Analysis Toolkit

The MCP exposes graph operations through specialized tools that reduce token consumption by approximately 99% compared to file-by-file greps.

Structural search tools:

• search_graph – Query nodes by label (e.g., Function, Class) with regex name patterns, degree limits, and pagination
• search_code – Text-based code search within indexed content

Call-graph analysis:

• trace_path – BFS traversal up or down the call stack (inbound/outbound/both) with configurable depth limits
• Dead-code detection and Louvain community detection for architectural clustering

Semantic capabilities:

• Vector search using the bundled nomic-embed-code model (no external API required)
• Impact analysis via detect_changes, which maps git diffs to affected symbols and classifies blast-radius risk

Architecture intelligence:

• get_architecture – Returns languages, packages, entry points, routes, hotspots, and clusters in a single call
• manage_adr – CRUD operations for Architecture Decision Records
• query_graph – Read-only openCypher subset for custom graph traversals

Operational features:

• auto_watch flag enables automatic re-indexing via the background watcher
• Optional 3D interactive UI (--ui=true --port=9749) for visual graph exploration

Key Implementation Files

Understanding the codebase structure requires examining these critical paths:

• src/watcher/watcher.c – Implements the filesystem watcher that triggers incremental re-indexing when source files change.
• internal/cbm/zstd_store.c – Contains the compression and decompression logic for the persisted graph database.
• opencode.json – Manifest of the 158 Tree-Sitter grammars compiled into the binary.
• server.json – Defines the JSON-RPC schema for MCP client communication.
• docs/CONFIGURATION.md – Documents runtime options including auto-index, auto-watch, and environment variables.
• docs/cbmignore.md – Specifies the .cbmignore hierarchy controlling exclusion patterns during indexing.

Practical Usage Examples

Index a repository

codebase-memory-mcp cli index_repository --repo-path /absolute/path/to/my/project

Search for handler functions

codebase-memory-mcp cli search_graph \
  --project my-project \
  --label Function \
  --name-pattern '.*Handler.*' \
  --limit 20

Trace call chains

codebase-memory-mcp cli trace_path \
  --project my-project \
  --function-name Search \
  --direction both \
  --depth 5

Execute Cypher-like queries

codebase-memory-mcp cli query_graph \
  --project my-project \
  --query "MATCH (f:Function) RETURN f.name, size((f)<-[:CALLS]-()) AS callers ORDER BY callers DESC LIMIT 5"

Detect impact of changes

git diff HEAD | codebase-memory-mcp cli detect_changes --project my-project

Launch the visualizer

codebase-memory-mcp --ui=true --port=9749

Summary

• Three-layer architecture – Indexing pipeline, persistent knowledge graph, and query toolkit work in concert to provide sub-millisecond structural queries.
• Language-agnostic parsing – 158 Tree-Sitter grammars and Hybrid LSP support for 12+ languages enable deep cross-language analysis.
• Efficient storage – RAM-first processing with LZ4 and zstd compression via internal/cbm/zstd_store.c minimizes disk footprint while maximizing reload speed.
• Local-first operation – Bundled embedding models and SQLite persistence require no external APIs, cloud keys, or Docker containers.
• AI-optimized interface – MCP tools like trace_path, detect_changes, and query_graph dramatically reduce token usage for coding agents.

Frequently Asked Questions

What languages does codebase-memory-mcp support?

The system supports Python, TypeScript/JavaScript/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust, and Perl through its Hybrid LSP implementation. Parsing relies on 158 vendored Tree-Sitter grammars defined in opencode.json, enabling robust static analysis without external language servers.

How does the graph storage work?

codebase-memory-mcp uses a RAM-first design where the knowledge graph resides in an in-memory SQLite database with LZ4 compression during the indexing phase. Upon completion, the system writes a zstd-compressed snapshot to .codebase-memory/graph.db.zst using the compression utilities in internal/cbm/zstd_store.c. This compressed SQLite file persists across sessions and loads rapidly when agents reconnect.

What is the difference between structural and semantic search?

Structural search (via search_graph) queries the explicit graph topology—finding nodes by type (Function, Class) and traversing defined edges (CALLS, IMPORTS). Semantic search uses the bundled nomic-embed-code model to compute vector embeddings of code snippets, enabling similarity searches based on meaning rather than syntax, all processed locally without API calls.

Can the system automatically update when code changes?

Yes. When enabled via the auto_watch flag, the background watcher implemented in src/watcher/watcher.c monitors the repository for filesystem events and triggers incremental re-indexing. This ensures the knowledge graph remains synchronized with the working directory without manual intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}