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

> Explore common use cases for the graph storage feature in Codebase Memory MCP. Discover how this SQLite-based graph database enhances code-base analysis with AST persistence and FTS5 search.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: use-cases
- Published: 2026-07-05

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c), the schema defines discrete tables for these entities:

```sql
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:

```sql
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:

```sql
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:

```sql
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/README.md):

```python
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go) provides direct graph manipulation:

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.