How DeusData codebase-memory-mcp Stores Codebase Information: SQLite Persistence Explained

DeusData codebase-memory-mcp persists extracted repository knowledge in a SQLite database located at ~/.cache/codebase-memory-mcp/, accessed through a lightweight C API that supports both in-memory operations and zstd-compressed snapshots.

DeusData codebase-memory-mcp is a Model Context Protocol (MCP) server that indexes codebases into a queryable graph structure. Understanding how it stores codebase information reveals a lightweight, self-contained persistence layer built on SQLite with custom compression capabilities, requiring no external database servers.

Storage Location and Configuration

The default storage location follows the XDG Base Directory specification, placing SQLite files under the user's cache directory.

Default Cache Directory

By default, all database files reside in ~/.cache/codebase-memory-mcp/ as documented in the repository README. This directory contains the main graph database and any incremental snapshots created during the indexing process.

Environment Variable Overrides

Users can override the default location by setting the CBM_CACHE_DIR environment variable. This allows teams to share cache directories on network mounts or relocate storage to disks with more available space.

Database Schema: Nodes and Edges

The storage layer implements a property graph model stored in relational tables, exposing entities and their relationships through the get_graph_schema tool.

Graph Data Model

The schema distinguishes between nodes and edges. Nodes represent code entities such as Project, Package, File, Class, and Function. Edges represent relationships including CALLS, IMPORTS, and DEFINES. Each node stores properties like file paths and line numbers, while edges maintain confidence scores and metadata.

Table Structure

According to the README's "Graph Data Model" section, the SQLite database creates normalized tables for each node label and relationship type. This structure enables efficient traversal queries while maintaining referential integrity between source files and their constituent symbols.

The C Store API

The core persistence logic resides in internal/cbm/zstd_store.c and internal/cbm/zstd_store.h, exposing a thin C API used throughout the test suite.

Core Store Functions

The public interface includes several key functions:

• cbm_store_open_memory() – Creates an in-memory SQLite instance useful for testing or temporary analysis
• cbm_store_upsert_project(store, name, path) – Registers a project node with its root filesystem path
• cbm_store_upsert_node(store, &node) – Inserts or updates generic nodes like functions or classes
• cbm_store_insert_edge(store, &edge) – Creates typed relationships between existing nodes

These functions are exercised in tests/test_ui.c (lines 221-269) and tests/test_watcher.c (lines 82-84), demonstrating the full CRUD lifecycle.

In-Memory vs File-Backed Storage

The API supports both ephemeral and persistent modes. Tests typically use cbm_store_open_memory() for speed, while production indexing operations open file-backed databases that flush to ~/.cache/codebase-memory-mcp/ on close.

Persistence and Compression Workflow

When index_repository completes its analysis, the system executes a multi-step persistence pipeline to ensure data durability and compact storage.

Graph Dump Process

After indexing finishes, the in-memory graph representation is dumped into the SQLite file in the cache directory. The implementation compares the number of persisted nodes against the in-memory count using the CBM_DUMP_VERIFY_MIN_RATIO threshold to detect incomplete writes.

zstd Snapshots

For fast incremental updates and peer-to-peer sharing, the store can write zstd-compressed snapshots (.codebase-memory/graph.db.zst) alongside the source tree. These snapshots are created by running VACUUM on the SQLite database followed by zstd compression, producing a compacted bootstrap file that other team members can decompress to initialize their local stores.

Verification and Integrity

The persistence layer includes built-in verification that ensures the dumped SQLite database contains the expected ratio of nodes before finalizing the write, preventing corruption from interrupted indexing operations.

Thread Safety and ACID Guarantees

The SQLite database is opened in WAL (Write-Ahead Logging) mode, providing crash-recoverable writes while allowing concurrent read access from the MCP server. This architecture ensures ACID compliance without blocking read operations during indexing updates, making the storage layer safe for multi-threaded environments.

Summary

• DeusData codebase-memory-mcp stores codebase information in a SQLite database at ~/.cache/codebase-memory-mcp/
• The C Store API in internal/cbm/zstd_store.c provides functions like cbm_store_upsert_node() and cbm_store_insert_edge() for graph manipulation
• The schema uses nodes (Project, File, Function) and edges (CALLS, IMPORTS) to model code relationships
• zstd compression creates portable snapshots (.codebase-memory/graph.db.zst) for fast team onboarding
• WAL mode ensures thread-safe, ACID-compliant operations suitable for production MCP servers

Frequently Asked Questions

Where does codebase-memory-mcp store its database files by default?

By default, the database files are stored in ~/.cache/codebase-memory-mcp/ under the user's home directory. You can verify this location by checking the environment variables section of the README, which documents this path as the standard cache location for the SQLite persistence layer.

What database engine does DeusData codebase-memory-mcp use?

The project uses SQLite as its sole database engine, opened in WAL mode for concurrent read access. This choice enables a self-contained binary with no external dependencies, allowing the MCP server to run anywhere without requiring PostgreSQL or MySQL installations.

How does the store handle large codebases efficiently?

For large repositories, the system utilizes zstd-compressed snapshots stored as .codebase-memory/graph.db.zst files alongside the source code. These compressed snapshots are created by vacuuming the SQLite database and applying zstd compression, significantly reducing transfer times when sharing indexed codebases across teams.

Can I configure where codebase-memory-mcp stores its data?

Yes, you can override the default storage location by setting the CBM_CACHE_DIR environment variable before starting the server. This allows you to relocate the SQLite database to alternative storage volumes, network mounts, or ephemeral disks with larger capacity than the default user cache directory.

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