What Is the .codebase-memory/graph.db.zst Artifact in Codebase-Memory-MCP?

The .codebase-memory/graph.db.zst file is a Zstandard-compressed SQLite database that persists the entire knowledge graph of your codebase, enabling fast incremental analysis and eliminating the need to re-parse source files on every query.

When codebase-memory-mcp indexes a repository, it constructs a rich graph describing files, symbols, imports, AST nodes, and their relationships. To make this graph available across tool runs while keeping disk usage minimal, the project serializes the data into a SQLite database and compresses it with Zstandard, producing the graph.db.zst artifact.

What Is the graph.db.zst File?

The .codebase-memory/graph.db.zst artifact serves as the persistent storage layer for the Codebase-Memory knowledge graph. It stores the complete indexed representation of your source code, including:

• Nodes representing files, functions, classes, and symbols
• Edges defining relationships like imports, function calls, and containment hierarchies
• Properties attached to graph elements (line numbers, types, documentation)

By default, this file resides in a hidden .codebase-memory directory, typically located at ~/.cache/codebase-memory-mcp/ on Linux and macOS systems.

How the Graph Is Built and Compressed

The creation process follows a two-stage pipeline that balances query speed with storage efficiency:

1. Serialization: The in-memory graph constructed from AST parsing is written to a standard SQLite database named graph.db.
2. Compression: The SQLite file is compressed using Zstandard (zstd) to create graph.db.zst, typically reducing file size by 60–80% while maintaining fast decompression speeds.

Implementation in the Zstandard Store Module

According to the DeusData/codebase-memory-mcp source code, the compression logic is implemented in the internal storage layer:

• internal/cbm/zstd_store.c: Contains the low-level implementation of zstd_compress() and zstd_decompress() for handling binary blobs, plus the logic to read and write compressed streams to disk.
• internal/cbm/zstd_store.h: Declares the public API consumed by the indexing engine, including cbm_zstd_store_write() and cbm_zstd_store_read().

The core graph engine (implemented in files such as src/graph.c) calls these APIs to persist the database whenever indexing completes and to decompress it when serving queries via the LSP server or CLI commands.

Working with the graph.db.zst Artifact

Manual Decompression and Inspection

You can manually decompress the artifact to inspect the raw SQLite database and run custom SQL queries:

# Decompress using the zstd utility

zstd -d ~/.cache/codebase-memory-mcp/graph.db.zst -o graph.db

# Query the node count directly

sqlite3 graph.db "SELECT COUNT(*) FROM node;"

Exporting Graph Data via CLI

The tool provides built-in commands that interact with the stored graph without requiring manual decompression:

# Export the entire graph as JSON

codebase-memory-mcp dump --output json

# Execute Cypher queries against the stored graph

codebase-memory-mcp cypher "MATCH (f:Function)-[:CALLS]->(c:Symbol {name:'my_func'}) RETURN f.path"

Forcing a Fresh Re-index

To rebuild the graph from scratch—useful after significant code changes or cache corruption—remove the cached artifact and re-run the indexer:

rm ~/.cache/codebase-memory-mcp/graph.db.zst
codebase-memory-mcp index /path/to/your/repo

Why the Artifact Matters

The graph.db.zst file is fundamental to codebase-memory-mcp's performance characteristics:

• Persistence: The graph survives between process restarts, so subsequent analyses (LSP queries, Cypher lookups, incremental indexing) reuse existing data.
• Speed: Loading a pre-built SQLite index is orders of magnitude faster than reconstructing the graph from source files.
• Space Efficiency: The Zstandard compression keeps cache sizes manageable even for large monorepos.

Summary

• The .codebase-memory/graph.db.zst file is a Zstandard-compressed SQLite database containing the complete knowledge graph of indexed code.
• It provides persistence between runs, eliminating redundant source file parsing.
• The artifact achieves 60–80% size reduction over uncompressed SQLite while maintaining fast decompression.
• Core implementation resides in internal/cbm/zstd_store.c and internal/cbm/zstd_store.h, exposing cbm_zstd_store_write() and cbm_zstd_store_read() APIs.
• Cached by default at ~/.cache/codebase-memory-mcp/graph.db.zst on Linux and macOS systems.

Frequently Asked Questions

Can I move the graph.db.zst file to a different machine?

Yes, the artifact is portable across systems with matching architectures. However, because it stores absolute file paths from the original indexing environment, you may need to re-index if the source code location differs on the target machine.

How large does the graph.db.zst file typically get?

Size depends on codebase complexity, but Zstandard compression typically yields a file 60–80% smaller than the raw SQLite database. Even large codebases usually produce artifacts under a few hundred megabytes.

Is it safe to delete the graph.db.zst file?

Absolutely. The file is purely a cache artifact; deleting it forces codebase-memory-mcp to rebuild the graph from source on the next run. The only consequence is the initial indexing time penalty.

Which SQLite schema does the graph use?

The database uses a custom schema optimized for property graph storage, with tables for nodes, edges, and property indices. You can inspect the full schema by decompressing the file and running .schema within the sqlite3 CLI.

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