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

> Learn how to migrate between different CBM_CACHE_DIR locations. Follow simple steps to transfer your cache, update your environment, and verify the move for seamless Codebase-Memory-MCP operation.

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

---

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

```bash
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:

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

```

As documented in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/config.json), `_config.db`, etc.) when copying. Use `rsync` or `cp -a` to maintain permissions and directory structure:

```bash
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:

```bash
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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_watcher.c) and [`tests/test_ui.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/config.json) and `_config.db`. These files contain your indexes, UI settings, and runtime configuration as described in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.