codebase-memory-mcp/docs/CONFIGURATION.md

Configuration Reference

This page documents the configuration files that codebase-memory-mcp reads or writes today.

At a Glance

Purpose	Path	Format	Notes
Global custom extension mapping	$XDG_CONFIG_HOME/codebase-memory-mcp/config.json	JSON	Falls back to ~/.config/codebase-memory-mcp/config.json when XDG_CONFIG_HOME is unset.
Per-project custom extension mapping	{repo_root}/.codebase-memory.json	JSON	Overrides conflicting global extra_extensions entries.
CLI-managed runtime settings	${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/_config.db	SQLite	Written by codebase-memory-mcp config set/reset.
UI settings	${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json	JSON	Stores ui_enabled and ui_port.

1. Custom File Extension Mapping

Two optional JSON files let you map additional file extensions to built-in languages.

Global config

Default path:

$XDG_CONFIG_HOME/codebase-memory-mcp/config.json

Fallback when XDG_CONFIG_HOME is unset:

~/.config/codebase-memory-mcp/config.json

Per-project config

Place this file in the repository root:

.codebase-memory.json

Format

{
  "extra_extensions": {
    ".blade.php": "php",
    ".mjs": "javascript",
    ".twig": "html"
  }
}

Notes:

• Extension keys must include the leading dot.
• Language names are case-insensitive.
• Unknown language names are skipped.
• Missing files are ignored.
• If the same extension appears in both files, the per-project file wins.

2. CLI-Managed Runtime Settings

The config subcommand stores runtime settings in a small SQLite database:

${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/_config.db

Inspect or change values with the CLI:

codebase-memory-mcp config list
codebase-memory-mcp config get auto_index
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000
codebase-memory-mcp config reset auto_index

Current keys:

Key	Default	Meaning
auto_index	false	Automatically index new projects when an MCP session starts.
auto_index_limit	50000	Maximum file count allowed for automatic indexing of a new project.

3. UI Settings

The optional built-in graph UI stores its settings in:

${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json

Current format:

{
  "ui_enabled": false,
  "ui_port": 9749
}

Notes:

• If the UI-enabled binary has embedded assets and no UI config file exists yet, the UI auto-enables on first run.
• CBM_CACHE_DIR changes both the UI config location and the runtime settings database location.

4. Environment Variables

These environment variables affect runtime behavior:

Variable	Default	Description
CBM_ALLOWED_ROOT	(unset)	Restrict index_repository to paths within this directory. When set, a repo_path that resolves (after symlink / .. resolution) outside this root is refused; unset imposes no restriction. Useful when the server may be driven by an untrusted caller (agentic or multi-tenant deployments).
CBM_CACHE_DIR	~/.cache/codebase-memory-mcp	Override the cache directory used for indexes, _config.db, and UI config.json.
CBM_DIAGNOSTICS	false	Enable periodic diagnostics output to /tmp/cbm-diagnostics-<pid>.json.
CBM_DOWNLOAD_URL	GitHub releases	Override the update download URL.
CBM_LOG_LEVEL	info	Set stderr log level to debug, info, warn, error, or none (or 0-4).
CBM_WORKERS	auto-detected	Override the indexing worker count.

5. Agent and Editor Integration Files

The install command can also write MCP entries and owned instruction blocks into detected agent/editor config files. Supported targets include Claude Code, Claude Desktop, Codex, Gemini, Qwen Code, ForgeCode, Antigravity, OpenCode, Zed, VS Code and its profiles, Cursor, Windsurf, KiloCode, OpenClaw, Kiro, and Junie; Aider receives CLI-form instructions because it does not expose MCP.

Those target paths vary by tool and platform, so the easiest way to inspect the exact files for your machine is:

codebase-memory-mcp install --dry-run

That prints the specific config files the installer would modify without writing anything. uninstall --dry-run is also read-only, including when combined with -y; it reports the index action that would occur without prompting or deleting indexes.