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

> Discover where codebase-memory-mcp stores its SQLite databases. Learn about the hidden .codebase-memory directory and the graph.db.zst file location.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L203), 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```python
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) and implemented in [`internal/cbm/sqlite_writer.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.