Where Does codebase-memory-mcp Store Its SQLite Databases? File Paths Explained

codebase-memory-mcp stores its SQLite database in a hidden .codebase-memory directory at your project root, keeping the primary data in a Zstandard-compressed file named graph.db.zst.

When you index a repository with codebase-memory-mcp, the tool creates a persistent knowledge-graph database alongside your source files. Understanding the exact file paths and storage mechanism is essential for backup strategies, debugging, and direct database access.

Default Database Location and File Structure

The tool adheres to a strict convention: every project indexed by codebase-memory-mcp receives a hidden storage directory immediately adjacent to the source code.

The .codebase-memory Directory

The canonical storage location is:

<project-root>/.codebase-memory/graph.db.zst

This path is hardcoded relative to the repository root. According to the README.md at line 203, the .codebase-memory/graph.db.zst artifact is a zstd-compressed snapshot of the knowledge graph that lives next to your source. When you run the indexer, the CLI writes or refreshes this compressed file, which is subsequently decompressed and incrementally updated.

The directory contains three potential file types:

• graph.db.zst – The persistent compressed snapshot
• graph.db-wal – Write-ahead log for ongoing transactions
• graph.db-shm – Shared-memory file for WAL mode

Compressed vs. Decompressed Files

During first run, codebase-memory-mcp decompresses graph.db.zst into a working SQLite file (graph.db) in the same directory. This temporary file is then maintained incrementally, while the compressed snapshot serves as the durable backup. The decompression logic is implemented in internal/cbm/sqlite_writer.c, which handles construction of the .db file from in-memory data structures.

How the Database Files Work Together

When the SQLite connection is active, you will observe auxiliary files alongside the main database:

• .db-wal – Contains recent changes not yet flushed to the main database
• .db-shm – Facilitates multi-process access to the WAL

These files ensure atomicity and durability during the indexing process. The tests/test_watcher.c file demonstrates this behavior during test runs, where temporary databases like stale-project.db, stale-project.db-wal, and stale-project.db-shm are created in test-generated cache directories. However, production usage always targets the .codebase-memory folder in your project root.

Accessing the Database Programmatically

You can interact directly with the decompressed SQLite database using Python. The following example shows how to locate the compressed file, decompress it if necessary, and open a connection:

import sqlite3
import pathlib
import zstandard
import os

# Navigate to project root

proj_root = pathlib.Path(__file__).parent.parent
zst_path = proj_root / ".codebase-memory" / "graph.db.zst"
db_path = proj_root / ".codebase-memory" / "graph.db"

# Decompress on first run (the CLI does this automatically)

if not db_path.exists():
    with open(zst_path, "rb") as src, open(db_path, "wb") as dst:
        dctx = zstandard.ZstdDecompressor()
        dctx.copy_stream(src, dst)

# Connect to the knowledge graph

conn = sqlite3.connect(str(db_path))
cursor = conn.cursor()

# Query the graph structure...

This approach mirrors the internal logic found in pkg/pypi/src/codebase_memory_mcp/_cli.py, which serves as the CLI entry point that triggers indexing and database updates.

CLI Operations and Database Updates

When you trigger re-indexing via the command line, the tool updates the compressed snapshot:

# Refresh the database (re-indexes the project)

codebase-memory-mcp index --project /path/to/repo

# The CLI rewrites .codebase-memory/graph.db.zst

You can verify the database files exist with:

# Locate the database for a cloned repo

ls .codebase-memory/

# Output: graph.db.zst  graph.db-wal  graph.db-shm

The CLI manages the lifecycle of these files, ensuring that graph.db.zst remains synchronized with your codebase state while the temporary working files handle runtime mutations.

Summary

• codebase-memory-mcp stores its SQLite database in <project-root>/.codebase-memory/
• The primary storage is graph.db.zst, a Zstandard-compressed snapshot
• Working files graph.db-wal and graph.db-shm support SQLite's WAL mode during indexing
• The storage location is documented in README.md and implemented in internal/cbm/sqlite_writer.c
• Temporary test databases may appear in cache directories, but production data always lives in the hidden .codebase-memory folder

Frequently Asked Questions

Where is the codebase-memory-mcp database stored relative to my project?

The database is stored in a hidden directory named .codebase-memory located at your project root. The primary file path is .codebase-memory/graph.db.zst, with auxiliary WAL and SHM files appearing in the same directory when the database is active.

Why is the database compressed with Zstandard?

The Zstandard compression reduces disk footprint for the persistent snapshot while maintaining fast decompression speeds. According to the source code, the compressed graph.db.zst serves as the durable artifact that is decompressed to graph.db on first access, then maintained incrementally via WAL mode.

Can I move the .codebase-memory directory to a different location?

The tool expects the .codebase-memory directory to exist at the project root relative to the source files being indexed. Moving this directory would break the CLI's automatic detection and indexing capabilities, as the path is hardcoded in the implementation logic found in pkg/pypi/src/codebase_memory_mcp/_cli.py.

What are the .db-wal and .db-shm files?

These are SQLite auxiliary files created when the database operates in Write-Ahead Logging (WAL) mode. The .db-wal file contains transactions not yet committed to the main database, while the .db-shm file facilitates shared memory access for concurrent readers. They are automatically managed and can be safely ignored, though they should be included in backups to preserve uncommitted changes.

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