# What Graph Data Model Does Codebase-Memory-MCP Use?

> Discover the property-graph data model of Codebase-Memory-MCP. Learn how it represents software repositories as a network of typed nodes and semantic edges for efficient querying.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-04

---

**Codebase-Memory-MCP employs a property-graph data model that represents software repositories as a network of typed nodes and semantic edges, persistently stored in SQLite and queryable via Cypher-like syntax.**

The DeusData/codebase-memory-mcp project transforms raw source code into a navigable knowledge graph. Its **graph data model** treats projects, packages, files, classes, functions, and even external service routes as distinct entities, linking them with explicit relationships that capture containment, invocation, inheritance, and cross-service communication.

## Core Property-Graph Architecture

The model follows a classic property-graph pattern where every entity is a **node** carrying a label and properties, and every relationship is a directed **edge** with a type and optional attributes. This structure is detailed in the repository’s [README.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#graph-data-model).

### Node Taxonomy

Nodes are classified by labels that reflect the logical and physical structure of a codebase:

- **Project** – The root repository node.
- **Package** – Language-specific packages (npm, pip, Cargo, etc.).
- **Folder** / **File** – Physical directory hierarchy.
- **Module** – Logical modules within files (e.g., Python modules).
- **Class** / **Interface** / **Enum** / **Struct** / **Type** – Type definitions.
- **Function** / **Method** – Callable symbols.
- **Route** / **Resource** – HTTP endpoints, gRPC methods, GraphQL operations, and other service resources.

Each node is uniquely identified by a **qualified name** following the pattern `<project>.<path>.<symbol>`, which allows the system to retrieve exact source snippets and disambiguate homonyms across different packages.

### Edge Semantics

Edges define the relationships between nodes. The model includes a rich vocabulary of edge types:

- **Structural containment**: `CONTAINS_PACKAGE`, `CONTAINS_FOLDER`, `CONTAINS_FILE`.
- **Definition**: `DEFINES`, `DEFINES_METHOD`.
- **Dependency**: `IMPORTS`.
- **Call graph**: `CALLS`, `HTTP_CALLS`, `ASYNC_CALLS` (including cross-service invocations).
- **Inheritance**: `IMPLEMENTS`, `INHERITS`, `HANDLES`.
- **Type usage**: `USAGE`, `USES_TYPE`, `MEMBER_OF`.
- **Configuration & side effects**: `CONFIGURES`, `WRITES`, `FILE_CHANGES_WITH`.
- **Testing**: `TESTS`.

These typed edges enable precise traversal patterns, such as discovering all functions that transitively call a specific service or identifying which classes implement a given interface.

### Qualified Names

Every node is addressable via a **qualified name** that encodes its project, file path, and symbol identity. This convention is used throughout the storage layer and CLI tools to fetch source code and metadata without ambiguity.

## SQLite Persistence Layer

The graph is materialized as an SQLite database located at `~/.cache/codebase-memory-mcp/graph.db`. The storage layer maps the abstract property-graph onto two primary tables—`node` and `edge`—with indexes optimized for fast traversal and Cypher-like pattern matching.

The underlying schema and query executor are implemented in C:

- **[`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h)** – Defines the SQLite schema for nodes and edges, including column mappings for labels, properties, and edge types.
- **[`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c)** – Implements the storage engine, handling insertions, updates, and the execution of graph queries.

The TypeScript frontend consumes this data through definitions found in **[`graph-ui/src/lib/types.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts)**, which mirrors the node and edge labels for UI rendering.

## Querying the Graph via MCP Tools

The CLI exposes the graph model through several commands that operate directly on the node and edge types defined above.

```bash

# Search for function nodes matching a regex pattern

codebase-memory-mcp cli search_graph '{"label":"Function","name_pattern":".*Handler.*"}'

# Trace inbound and outbound call paths for a specific function

codebase-memory-mcp cli trace_path '{"function_name":"processOrder","direction":"both"}'

# Execute a Cypher-like query to find HTTP routes that call a specific function

codebase-memory-mcp cli query_graph '{
  "query":"MATCH (r:Route)-[:CALLS*]->(f:Function) \
           WHERE f.name = \"fetchUser\" RETURN r.path, r.method"
}'

# Retrieve source code using a qualified name

codebase-memory-mcp cli get_code_snippet '{"qualified_name":"myproj.src.orders.processOrder"}'

```

These commands demonstrate how the property-graph model translates into practical API usage, allowing developers to navigate code structure as a network rather than flat text.

## Key Source Files

| File | Purpose | Link |
|------|---------|------|
| [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) | C header defining the SQLite schema and node/edge structures | [store.h](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) |
| [`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c) | Implementation of the storage layer, including the Cypher-like query executor | [store.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c) |
| [`graph-ui/src/lib/types.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts) | TypeScript type definitions for the UI’s graph representation | [types.ts](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts) |
| [`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) | Human-readable specification of the graph data model and qualified-name conventions | [README – Graph Data Model](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#graph-data-model) |

## Summary

- Codebase-Memory-MCP uses a **property-graph** model with labeled nodes and typed edges.
- Nodes represent entities from high-level projects down to individual functions and HTTP routes.
- Edges capture semantic relationships including containment, definition, invocation, inheritance, and configuration.
- The graph is persisted in **SQLite** (`~/.cache/codebase-memory-mcp/graph.db`) and exposed through Cypher-like queries.
- Core storage logic resides in [`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c) and [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h), while [`graph-ui/src/lib/types.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts) provides the TypeScript interface definitions.

## Frequently Asked Questions

### What is the difference between a Folder node and a Package node?

A **Folder** node represents a physical directory in the file system, whereas a **Package** node represents a language-specific distribution unit (such as an npm package, Python module, or Rust crate). A single folder may contain multiple packages, or a package may span several folders, depending on the project structure.

### How does Codebase-Memory-MCP handle cross-language or cross-service relationships?

The model includes generic edge types like `CALLS`, `HTTP_CALLS`, and `ASYNC_CALLS` that link function nodes to external service resources (e.g., `Route` nodes). This allows the graph to represent microservice architectures where Function A in a Python service calls Route B in a Node.js service, enabling cross-repository analysis.

### Can I extend the graph data model with custom node labels or edge types?

Currently, the node labels and edge types are defined in the core storage schema ([`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h)) and the TypeScript types ([`graph-ui/src/lib/types.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts)). Adding custom labels requires updating these definitions and rebuilding the project. The SQLite schema uses a closed enumeration for edge types to optimize storage and query performance.

### Where is the graph physically stored on disk?

The graph database is stored as a single SQLite file at `~/.cache/codebase-memory-mcp/graph.db`. This location is created automatically when the project is first indexed and can be regenerated by re-running the analysis tools against the source repository.