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

> Easily set up Codebase-Memory-MCP for AI coding agents. Install, initialize, and ingest your repository with simple commands for persistent semantic search and enhanced AI development.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: getting-started
- Published: 2026-07-09

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`internal/cbm/zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/setup.sh) for CI environment preparation.

### 2. Install the Python Shim

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

```bash
pip install .

# Or directly from PyPI:

pip install codebase-memory-mcp

```

This copies the bootstrapper ([`_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash

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

```bash

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

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

```

Ingest your repository to build the searchable index:

```bash

# Index the current directory

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

```

Perform semantic queries against the indexed codebase:

```bash

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

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) file in the repository root. The [`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh) legacy script and [`scripts/setup.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.