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

> Learn how DeusData codebase-memory-mcp stores codebase information. Discover its SQLite persistence, C API, and in-memory operations for efficient knowledge management.

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

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`internal/cbm/zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_ui.c) (lines 221-269) and [`tests/test_watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.