# How to Back Up and Restore the Codebase-Memory Graph Store

> Secure your codebase-memory-mcp knowledge graph. Learn simple backup and restore procedures for the graph.db.zst SQLite file to prevent data loss.

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

---

**The `codebase-memory-mcp` tool persists its knowledge graph as a zstd-compressed SQLite file at `.codebase-memory/graph.db.zst`, which you can back up by copying the file and restore by placing it back before running the `index_repository` command.**

The `codebase-memory-mcp` repository maintains a persistent knowledge graph to store codebase relationships and semantic connections. Understanding how to back up and restore this graph store ensures you can preserve analysis history across deployments, team members, or system migrations. The entire graph state lives in a single compressed artifact that requires no complex database administration procedures.

## Understanding the Graph Store Architecture

According to the `codebase-memory-mcp` source code, the graph store uses a **single-file architecture** located at `.codebase-memory/graph.db.zst` in the repository root. This file contains a complete snapshot of every node, edge, and property in the knowledge graph, compressed using Zstandard (zstd) to minimize storage footprint.

The compression and decompression logic is implemented in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c), which provides thin wrappers around the Zstandard library. The actual graph data uses SQLite as the underlying storage format, making the `.zst` file essentially a compressed database dump that is portable across different operating systems and architectures.

## Backing Up the Graph Store

Creating a backup of the graph store requires no special export commands or database locks. Because the system operates on a single immutable artifact, you simply copy the file to a safe location.

Use the following approaches to back up your graph:

- **File-level backup**: Copy the `.codebase-memory/graph.db.zst` file directly to your backup destination or version control system.
- **Directory-level backup**: Archive the entire `.codebase-memory/` directory to capture configuration metadata alongside the graph data.

```bash

# Create a timestamped backup of the graph artifact

cp .codebase-memory/graph.db.zst ~/backups/project-graph-$(date +%F).zst

# Or commit it to version control (the tool configures .gitattributes automatically)

git add .codebase-memory/graph.db.zst
git commit -m "Backup graph store snapshot"

```

The README documentation notes that on the first export, the tool automatically creates a `.gitattributes` entry with `merge=ours`, ensuring that concurrent edits to the binary artifact do not cause Git merge conflicts.

## Restoring the Graph Store

To restore a previously saved graph, place the backup file back into the `.codebase-memory/` directory before running any indexing command. When `codebase-memory-mcp` starts the `index_repository` process, it automatically detects the artifact, decompresses it, and imports the nodes and edges as the initial graph state.

If the artifact is missing, the system performs a full re-index instead. If the artifact exists, the tool loads the snapshot and then runs an incremental indexing pass for any new or changed files. This logic is implemented in [`internal/cbm/cbm.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c), which handles the import mechanism and merge operations.

```bash

# Remove any existing artifact (optional)

rm -rf .codebase-memory/graph.db.zst

# Restore from backup

mkdir -p .codebase-memory
cp ~/backups/project-graph-2023-12-01.zst .codebase-memory/graph.db.zst

# Run indexing to load the snapshot and catch up on new changes

codebase-memory-mcp cli index_repository '{"repo_path":"$(pwd)"}'

```

### Programmatic Restore Example

For automated deployment scripts, use this pattern to restore from a known backup location:

```bash
#!/usr/bin/env bash
set -euo pipefail

BACKUP=~/backups/project-graph-latest.zst
TARGET=.codebase-memory/graph.db.zst

mkdir -p "$(dirname "$TARGET")"
cp "$BACKUP" "$TARGET"

# Trigger indexing (the snapshot loads automatically)

codebase-memory-mcp cli index_repository '{"repo_path":"$(pwd)"}'

```

## Configuring Custom Cache Locations

You can override the default `.codebase-memory/` directory location using the `CBM_CACHE_DIR` environment variable. This is documented in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) and referenced in the README at lines 77-80. Setting this variable allows you to store graph backups on network mounts or external storage without modifying the repository structure.

```bash

# Use a custom cache directory on an external drive

export CBM_CACHE_DIR=/mnt/external-storage/codebase-memory
codebase-memory-mcp cli index_repository '{"repo_path":"$(pwd)"}'

```

When using custom paths, ensure the backup and restore procedures reference the same `CBM_CACHE_DIR` value to maintain consistency.

## Summary

- The graph store exists as a single zstd-compressed SQLite file at `.codebase-memory/graph.db.zst`.
- **Back up** by copying the `.zst` file or the entire `.codebase-memory/` directory to version control or external storage.
- **Restore** by placing the saved file back before running `index_repository`, which automatically imports the snapshot and performs incremental updates.
- The tool configures `.gitattributes` with `merge=ours` to prevent merge conflicts on the binary artifact.
- Use `CBM_CACHE_DIR` to customize the storage location if needed.

## Frequently Asked Questions

### Where exactly is the graph store file located?

The graph store resides at `.codebase-memory/graph.db.zst` in the repository root by default. This path can be customized using the `CBM_CACHE_DIR` environment variable to redirect the storage location to alternate drives or network paths.

### Can I move the graph store between different machines?

Yes, the `.zst` file is completely portable. Because it uses zstd-compressed SQLite format, you can copy the file between Linux, macOS, or Windows systems without conversion. Place the file in the target repository's `.codebase-memory/` directory and run `index_repository` to restore the graph state.

### What happens if I restore an outdated backup?

When you run `index_repository` with an older snapshot present, the tool loads the saved state and then performs an incremental indexing pass. This updates the graph with any new or modified files since the backup was created, effectively synchronizing the restored state with the current codebase.

### How does the tool prevent Git conflicts on the graph file?

On the first export, `codebase-memory-mcp` automatically creates a `.gitattributes` entry specifying `merge=ours` for the graph artifact. This configuration tells Git to keep the local version of the file during merge operations, preventing conflicts when multiple team members contribute to the repository.