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

> Discover the purpose of the .codebase-memory/graph.db.zst artifact. Learn how this Zstandard compressed SQLite database enables fast incremental analysis of your codebase knowledge graph.

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

---

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

```bash

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

```bash

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

```bash
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`](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 `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.