Common Use Cases for the Graph Storage Feature in Codebase Memory MCP

The graph storage feature in codebase-memory-mcp is a lightweight SQLite-based graph database designed for code-base analysis, supporting AST persistence, fast traversal with FTS5 search, Louvain community detection, and incremental updates via WAL mode.

The codebase-memory-mcp repository by DeusData provides a lightweight SQLite-based graph store that persists code relationships as traversable nodes and edges. This article explores the common use cases for the graph storage feature, demonstrating how it enables everything from abstract syntax tree indexing to interactive visualization through its embeddable, language-agnostic architecture.

Common Use Cases for the Graph Storage Feature

Code-Base Indexing and AST Persistence

The primary use case involves persisting abstract syntax trees (ASTs) as queryable graphs. The store maps repository entities—files, symbols, definitions—to nodes and relationships—imports, calls, inheritance—to edges.

According to the implementation in internal/cbm/cbm.c, the schema defines discrete tables for these entities:

CREATE TABLE nodes (
    id      INTEGER PRIMARY KEY,
    label   TEXT    NOT NULL,
    kind    TEXT,
    community INTEGER
);

CREATE TABLE edges (
    src   INTEGER NOT NULL REFERENCES nodes(id),
    dst   INTEGER NOT NULL REFERENCES nodes(id),
    kind  TEXT,
    weight REAL DEFAULT 1
);

This structure allows you to query callers of a specific function using foreign key relationships:

SELECT src FROM edges WHERE dst = ? AND kind = 'calls';

Fast Traversal and Full-Text Search

Graph storage delivers sub-millisecond lookups by leveraging SQLite's native indexes and FTS5 full-text search extensions. The virtual table node_fts indexes node labels for fast text retrieval.

As configured in the schema, the store supports pattern matching on node identifiers:

CREATE VIRTUAL TABLE node_fts USING fts5(label, content='nodes', content_rowid='id');

-- Query example
SELECT id FROM nodes WHERE label MATCH 'http*';

Edges are optimized for bidirectional traversal via composite indexes:

CREATE INDEX idx_edges_src ON edges(src);
CREATE INDEX idx_edges_dst ON edges(dst);

This enables efficient graph walking from any starting node without full table scans.

Community Detection with Louvain Clustering

The store includes a built-in Louvain algorithm implementation for detecting communities within the code graph. This clusters related nodes into modules, revealing architectural domains and natural boundaries in the codebase.

After populating the graph, the run_louvain() routine (implemented in internal/cbm/cbm.c) calculates community assignments and persists them to the community column in the nodes table. This metadata drives color-coded visualizations in the front-end interface.

Incremental Updates for CI Integration

The storage layer uses SQLite WAL mode (Write-Ahead Logging), allowing concurrent reads while new nodes and edges are appended. This supports living documentation that updates as code changes.

In a typical CI workflow, the pipeline parses modified files and executes INSERT OR REPLACE operations to update affected nodes and edges without blocking the read-heavy UI. As noted in CONTRIBUTING.md, this architecture ensures the graph stays synchronized with the repository state without requiring downtime or exclusive locks.

Cross-Language Analysis Support

Because the store is language-agnostic, any parser emitting standardized entity and relationship tuples can populate the same SQLite schema. Whether using a Python, Go, or Rust front-end, all emit rows conforming to the node_id, label, type and src_id, dst_id, kind contract.

This decoupling allows codebase-memory-mcp to serve as a universal backend for polyglot codebases, with the store/ directory handling persistence while language-specific parsers handle syntax analysis.

Interactive Visualization

The graph-ui front-end reads the SQLite file directly via a WASM wrapper, rendering interactive diagrams without a separate server. The UI queries the nodes and edges tables to build the visual graph, using pre-calculated community IDs to color-code clusters.

The configuration in graph-ui/vite.config.ts supports this architecture, enabling the browser to load and query the database file directly for real-time exploration of code relationships.

Working with the Graph Storage API

The repository provides client libraries and CLI tools for interacting with the store.

Python Client Example

Using the bundled PyPI package as documented in pkg/pypi/README.md:

from codebase_memory_mcp import GraphStore

# Open or create the SQLite database

store = GraphStore("mycodegraph.db")

# Add a function node

node_id = store.add_node(label="my_module.my_func", kind="function")

# Create a relationship edge

store.add_edge(
    src=node_id,
    dst=store.get_node_id("my_module.helper"),
    kind="calls"
)

# Query all callers

callers = store.query("SELECT src FROM edges WHERE dst = ?", node_id)
print("Callers:", callers)

# Detect communities

store.run_louvain()

Go CLI Example

The command-line interface implemented in pkg/go/cmd/codebase-memory-mcp/main.go provides direct graph manipulation:

# Initialize a new graph database

codebase-memory-mcp init mygraph.db

# Add nodes and edges

codebase-memory-mcp node add --id 1 --label "pkg.Foo" --kind "type"
codebase-memory-mcp edge add --src 1 --dst 2 --kind "implements"

# Traverse from a specific node

codebase-memory-mcp edge list --src 1

Summary

• The graph storage feature provides a persistent, embeddable graph database built on SQLite for code analysis.
• It supports AST indexing via nodes and edges tables with foreign key constraints.
• FTS5 integration enables full-text search across code symbols with sub-millisecond latency.
• The built-in Louvain algorithm clusters code into communities for architectural visualization.
• WAL mode allows concurrent reads and writes, supporting live CI updates without downtime.
• The architecture is language-agnostic, accepting data from any parser that emits the standard schema.
• The graph-ui front-end renders the SQLite graph directly in the browser using WASM.

Frequently Asked Questions

What database engine does the graph storage feature use?

The graph storage uses SQLite with WAL mode enabled, leveraging FTS5 extensions for full-text search and standard B-tree indexes for edge traversal. This provides ACID compliance without requiring a separate database server.

Can the graph storage handle real-time updates during CI/CD pipelines?

Yes. The WAL mode implementation allows the database to accept writes from CI processes while simultaneously serving read queries to the visualization UI. This enables incremental updates where changed files trigger INSERT OR REPLACE operations without blocking readers.

How does the Louvain community detection work?

The run_louvain() function implemented in internal/cbm/cbm.c applies the Louvain algorithm to detect densely connected subgraphs within the code relationships. It writes community IDs back to the community column in the nodes table, which the graph-ui uses to color-code related modules in the visualization.

Is the graph storage limited to specific programming languages?

No. The storage layer is language-agnostic; any parser that can output entity tuples (node_id, label, kind) and relationship tuples (src_id, dst_id, kind) can populate the database. The repository includes Python and Go examples, but the SQLite schema accepts data from any language front-end.

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