How to Migrate Between Different CBM_CACHE_DIR Locations in Codebase-Memory-MCP

To migrate between different CBM_CACHE_DIR locations, terminate all active CBM processes, copy the full cache directory tree to the new location using rsync or cp -a, export the new path in your shell environment, and verify the migration with a lightweight CLI command.

The codebase-memory-mcp tool stores all persistent data—including indexes, logs, UI settings, and the _config.db SQLite database—under a single canonical cache root defined by the CBM_CACHE_DIR environment variable. When unset, the tool falls back to ~/.cache/codebase-memory-mcp. When you need to migrate this data to a different location, follow these strict steps to avoid daemon conflicts or data loss.

Prerequisites: Terminate All Active CBM Processes

You must close every active CBM process before changing the cache location. This includes the background daemon, any indexing workers, and any foreground CLI commands. According to the source code in README.md, a running daemon locks the cache root; attempting to change the root while the daemon is active results in a recorded conflict and command abortion.

Run the following to ensure no processes remain:

pkill -f cbm-daemon

# Or manually close any terminal sessions running codebase-memory-mcp

Step-by-Step Migration Guide

1. Identify the Current Cache Directory

Determine where your data currently resides. Inspect the environment variable or rely on the default path:

echo "${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}"

As documented in docs/CONFIGURATION.md, this variable resolves to a canonical location before any file operations occur.

2. Copy the Cache Tree to the New Location

Preserve the internal layout (logs/, indexes/, config.json, _config.db, etc.) when copying. Use rsync or cp -a to maintain permissions and directory structure:

OLD="${CBM_CACHE_DIR:-$HOME/.cache/codebase-memory-mcp}"
NEW="${HOME}/my-new-cbm-cache"
mkdir -p "$NEW"
rsync -a "$OLD/" "$NEW/"

3. Update the Environment Variable

Point new sessions to the new root by exporting CBM_CACHE_DIR before invoking any CBM command:

export CBM_CACHE_DIR="${HOME}/my-new-cbm-cache"

To make this change permanent, add the export line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

4. Verify the Migration

Run a lightweight command to confirm the daemon recognizes the new cache root and writes logs to the correct location:

codebase-memory-mcp config list
ls "$CBM_CACHE_DIR/logs"

The config list command validates that the tool can read from and write to the new canonical path.

Understanding the Canonical Cache Root and Conflict Prevention

The canonical cache root is a core concept in codebase-memory-mcp implemented in internal/cbm/platform.c (via cbm_safe_getenv and canonical path resolution). Because the cache root is canonical per account, any process that opened the daemon under the old path retains that reference for its lifetime.

If you skip the termination step, new sessions will be rejected and a conflict entry will be written to ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson. The unit tests in tests/test_watcher.c and tests/test_ui.c verify this behavior, demonstrating that environment variable changes require a clean shutdown to avoid state corruption.

Optional: Clean Up the Old Cache

After verifying that the new location works and confirming no processes reference the old path (check with lsof or similar tools), you can safely delete the legacy directory:

rm -rf "${OLD:-$HOME/.cache/codebase-memory-mcp}"

Summary

• Terminate all processes before migration to prevent daemon conflicts recorded in logs/daemon-conflicts.ndjson.
• Copy the full directory tree including logs/, indexes/, config.json, and _config.db to preserve all state.
• Export CBM_CACHE_DIR before running any commands to establish the new canonical root.
• Verify with codebase-memory-mcp config list and check that logs appear in the new location.
• Clean up the old path only after confirming no active references remain.

Frequently Asked Questions

What happens if I change CBM_CACHE_DIR while the daemon is running?

The command will abort and record a conflict in ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson. According to the README.md, all active CBM processes must run with the exact same canonical cache root; mismatches trigger rejection to prevent data corruption.

Which files must I copy during migration?

You must copy the entire directory tree including subdirectories like logs/ and indexes/, plus files such as config.json and _config.db. These files contain your indexes, UI settings, and runtime configuration as described in docs/CONFIGURATION.md.

How do I make the new cache location permanent?

Add the export statement to your shell initialization file (e.g., ~/.bashrc or ~/.zshrc): export CBM_CACHE_DIR="/path/to/new-location". Future terminal sessions will automatically use the new canonical root.

Does the migration affect existing indexed projects?

No, the migration preserves all indexed data because the indexes/ directory and _config.db SQLite database are copied intact. As long as you use rsync -a or cp -a to preserve the directory structure and permissions, the daemon will recognize existing projects in the new location.

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