How to Change the Cache Directory with CBMCACHEDIR in Codebase‑Memory‑MCP

Set the CBMCACHEDIR environment variable to an absolute path before invoking the binary to override the default ./.cbmcache location and redirect all cache storage to your preferred directory.

The codebase-memory-mcp tool maintains zstd‑compressed indexes and temporary analysis files in a local cache to accelerate subsequent operations. By default, it writes to a hidden .cbmcache folder in the current working directory, but production deployments often require relocating this data to faster storage or persistent volumes. The CBMCACHEDIR environment variable provides this control, read once during initialization in pkg/go/cmd/codebase-memory-mcp/main.go.

How CBMCACHEDIR is Resolved at Startup

The binary determines the cache root path during initialization by checking os.Getenv("CBMCACHEDIR") in the Go entry point. According to the source code in pkg/go/cmd/codebase-memory-mcp/main.go, the resolution follows this priority:

1. Environment variable check: If CBMCACHEDIR is set and points to a valid, writable path, that location becomes the cache root.
2. Fallback to default: If the variable is unset, empty, or points to an invalid location, the tool defaults to ./.cbmcache under the execution directory.
3. Directory creation: When the specified path does not exist, the tool automatically creates the directory structure before writing any cache files.

This initialization occurs exactly once at startup, meaning you must export the variable before invoking any subcommands like analyze or serve.

Configuring CBMCACHEDIR in Different Environments

Shell Sessions and Scripts

For interactive use or shell scripts, export the variable for the duration of the session:

export CBMCACHEDIR=/mnt/fast-ssd/cbm_cache
codebase-memory-mcp analyze /path/to/repo

For one-off commands without persisting the variable in your environment:

CBMCACHEDIR=/tmp/cbm_cache codebase-memory-mcp serve

Docker and Containerized Workloads

In containerized environments, set the variable in your Dockerfile or docker-compose configuration to ensure persistent storage across restarts:

ENV CBMCACHEDIR=/var/lib/cbm/cache
RUN mkdir -p "$CBMCACHEDIR"

Mounting a host directory or named volume to this path allows you to preserve caches between container restarts while keeping the storage on high-performance drives.

CI/CD Pipelines

In continuous integration pipelines, configure the variable at the job level to cache dependencies between runs:

variables:
  CBMCACHEDIR: $CI_PROJECT_DIR/.cbm-cache
cache:
  paths:
    - $CI_PROJECT_DIR/.cbm-cache

Low-Level Cache Storage Implementation

Once the path is established, the actual cache operations are handled by the zstd compression layer in internal/cbm/zstd_store.c and internal/cbm/zstd_store.h. These components use the resolved path to locate and store compressed index data.

The C implementation receives the path determined by the Go entry point and handles file I/O operations, ensuring that zstd‑compressed indexes are written to the correct location. If CBMCACHEDIR points to a network‑mounted drive or fast SSD, these underlying C functions benefit from the improved I/O performance without requiring code changes.

Verification and Troubleshooting

To confirm the active cache location, check that the directory exists and contains files after running an analysis:

ls -la $CBMCACHEDIR

If the directory remains empty or the tool reports permission errors, verify that:

• The path is absolute (relative paths may resolve unexpectedly depending on the working directory)
• The process has write permissions to the target directory
• The variable was exported in the same shell session that invokes the binary

Summary

• Set CBMCACHEDIR before running the binary to override the default ./.cbmcache location.
• Initialization happens once at startup in pkg/go/cmd/codebase-memory-mcp/main.go via os.Getenv.
• Automatic directory creation occurs if the specified path does not exist.
• Underlying storage uses zstd compression via internal/cbm/zstd_store.c and internal/cbm/zstd_store.h.
• Use absolute paths for reliable operation in Docker, CI, and production environments.

Frequently Asked Questions

What happens if CBMCACHEDIR points to an invalid path?

If the environment variable is set but points to a non-existent or read-only location, the tool falls back to the default ./.cbmcache directory in the current working directory. The binary validates the path after reading os.Getenv("CBMCACHEDIR") during initialization.

Can I use a relative path with CBMCACHEDIR?

While relative paths are technically accepted, they resolve based on the working directory at execution time, which can lead to inconsistent behavior in Docker containers or CI environments. The source code recommends using absolute paths for predictable cache locations.

Does the cache directory persist between runs?

Yes, the cache persists on disk indefinitely unless you manually delete it. Setting CBMCACHEDIR to a persistent volume or network share allows you to maintain indexes across multiple invocations and system restarts, significantly speeding up subsequent analyses.

Is CBMCACHEDIR the same as CBM_CACHE_DIR?

No, the implementation specifically checks for CBMCACHEDIR (without underscores). Setting CBM_CACHE_DIR will not affect the cache location; the variable must be named exactly CBMCACHEDIR as implemented in the main.go entry point.

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