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

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.

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 – Defines the SQLite schema for nodes and edges, including column mappings for labels, properties, and edge types.
• 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, 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.

# 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	C header defining the SQLite schema and node/edge structures	store.h
src/store/store.c	Implementation of the storage layer, including the Cypher-like query executor	store.c
graph-ui/src/lib/types.ts	TypeScript type definitions for the UI’s graph representation	types.ts
README.md	Human-readable specification of the graph data model and qualified-name conventions	README – 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 and src/store/store.h, while 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) and the TypeScript types (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.

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