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

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, 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.

# 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, which handles the import mechanism and merge operations.

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

#!/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 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.

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

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