How to Set Up the Codebase-Memory-MCP (CBM) for AI Coding Agents: Complete Installation Guide

Install the Python shim with pip install codebase-memory-mcp, initialize a store with codebase-memory-mcp init, and ingest your repository with codebase-memory-mcp ingest . to enable persistent semantic search across your codebase.

Codebase-Memory-MCP (CBM) is a self-contained tool that provides AI coding agents with a persistent, searchable snapshot of repository state. According to the DeusData/codebase-memory-mcp source code, the architecture combines a lightweight Python bootstrapper with a high-performance C binary that manages ZSTD-compressed vector embeddings. This guide walks through the complete setup process from installation to first query, covering the binary shim layer, security mechanisms, and optional Vue-based UI.

Architecture Overview

CBM operates through three distinct layers that work together to provide zero-configuration semantic search:

• Python Binary Shim – Located in pkg/pypi/src/codebase_memory_mcp/_cli.py, this wrapper handles lazy downloading of platform-specific binaries and manages the execution environment. It checks the per-user cache directory for existing binaries before initiating any network requests.

• Native C Binary – The core engine implemented in internal/cbm/zstd_store.c and internal/cbm/zstd_store.h. This component stores vectors, tokens, and file metadata in a memory-mapped ZSTD-compressed file format (*.cbm).

• Optional Vue UI – A graph visualizer available in the graph-ui package directory. Enable this variant by setting the environment variable CBM_VARIANT=ui before the first run.

Step-by-Step Installation Guide

1. Clone and Prepare the Environment

Clone the repository to access the source and install scripts:

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp

Alternatively, skip cloning if you only need the PyPI distribution, though cloning provides access to scripts/setup.sh for CI environment preparation.

2. Install the Python Shim

Install the package to register the codebase-memory-mcp console entry point:

pip install .

# Or directly from PyPI:

pip install codebase-memory-mcp

This copies the bootstrapper (_cli.py) into your environment and creates a console script that points to the shim. The shim determines the correct cache location based on your operating system: $XDG_CACHE_HOME/codebase-memory-mcp on Linux, %LOCALAPPDATA% on Windows, or ~/Library/Caches on macOS.

3. First-Run Binary Download

Upon first execution, the shim automatically downloads the native binary for your OS/CPU architecture. The process follows this security-hardened sequence:

1. URL Construction – The shim builds a download URL pointing to https://github.com/DeusData/codebase-memory-mcp/releases/download/v<version>/codebase-memory-mcp-<os>-<arch>{-portable}.tar.gz (or .zip on Windows).

2. Scheme Validation – The _validate_url_scheme function rejects any non-HTTPS URLs before network requests occur.

3. Integrity Verification – The _verify_checksum function compares SHA-256 hashes against the official checksums.txt bundled with each release, aborting immediately on mismatch.

4. Safe Extraction – The _safe_extract_tar and _safe_extract_zip functions implement path-traversal checks to prevent "zip-slip" attacks during extraction.

4. Optional UI Setup

To enable the graphical explorer, set the environment variable before your first run:

# Linux/macOS:

export CBM_VARIANT=ui

# Windows PowerShell:

$env:CBM_VARIANT="ui"

# Windows CMD:

setx CBM_VARIANT ui

When CBM_VARIANT=ui is set, the shim downloads the ui- variant binary containing bundled Vue UI assets. The interface becomes accessible via the ui subcommand.

Security-First Design

The _cli.py shim implements multiple defense layers against supply-chain attacks:

• HTTPS-Only Fetching – The _validate_url_scheme function enforces TLS for all remote operations, rejecting plain HTTP endpoints.
• Checksum Verification – Every downloaded archive validates against SHA-256 hashes stored in the release's checksums.txt file through the _verify_checksum implementation.
• Path Traversal Protection – Extraction routines _safe_extract_tar and _safe_extract_zip sanitize archive entries to prevent directory traversal vulnerabilities.
• Shell-Free Execution – The shim builds pure argument lists using execv (Unix) or subprocess.run (Windows), eliminating command injection risks.

Initializing and Using CBM

After the binary caches locally, the shim forwards all CLI arguments directly to the native engine. Initialize your first memory store:

# Create a new CBM store (default path: ./cbm)

codebase-memory-mcp init --db ./myproject.cbm

Ingest your repository to build the searchable index:

# Index the current directory

codebase-memory-mcp ingest . --db ./myproject.cbm

Perform semantic queries against the indexed codebase:

# Search with vector similarity

codebase-memory-mcp query "how does authentication middleware work?" \
    --db ./myproject.cbm \
    --top 5

Launch the optional web interface (requires CBM_VARIANT=ui):

codebase-memory-mcp ui --db ./myproject.cbm

# Opens browser at http://localhost:5173

Configuration Reference

Runtime behavior is controlled through a JSON configuration file. Key tunable parameters include embedding model selection, vector dimensions, and chunk size strategies. For the complete configuration schema and environment variable overrides, see the docs/CONFIGURATION.md file in the repository root. The install.sh legacy script and scripts/setup.sh helper can automate cache directory creation and environment setup for CI/CD pipelines.

Summary

• Install via PyPI: pip install codebase-memory-mcp provides the _cli.py shim that bootstraps the native engine.
• Automatic Binary Management: The shim downloads platform-specific builds to OS-appropriate cache directories, verifying SHA-256 checksums via _verify_checksum.
• Security by Design: HTTPS-only fetching, path-traversal prevention in _safe_extract_tar, and shell-free execution protect against supply-chain attacks.
• Core Commands: Use init to create ZSTD-compressed stores, ingest to index repositories, and query for semantic search.
• UI Option: Set CBM_VARIANT=ui before first run to enable the Vue-based graph visualizer on port 5173.

Frequently Asked Questions

What is the codebase-memory-mcp Python shim responsible for?

The Python shim in pkg/pypi/src/codebase_memory_mcp/_cli.py acts as a lazy bootloader. It manages the per-user cache directory, downloads the correct platform-specific native binary on first run, verifies SHA-256 checksums via _verify_checksum, and forwards CLI arguments to the C engine using safe execution methods.

How does CBM prevent malicious binary downloads?

The shim enforces HTTPS-only connections through _validate_url_scheme and validates every downloaded archive against cryptographic hashes stored in checksums.txt. Additionally, extraction functions _safe_extract_tar and _safe_extract_zip prevent path traversal attacks by sanitizing archive entries before writing to the cache directory.

Can I use CBM without the graphical interface?

Yes. The UI variant is optional. By default, the shim downloads the standard binary without Vue assets. Omit the CBM_VARIANT=ui environment variable to run purely in CLI mode, using only the init, ingest, and query commands against the ZSTD-compressed store files.

Where does CBM store the compressed codebase memory?

The native binary stores data in ZSTD-compressed, memory-mapped files (*.cbm) located at the path specified by the --db flag. The default location is ./cbm in your current working directory, though you can specify any path such as ./myproject.cbm for project-specific isolation.

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