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

Important keys (config list shows common effective values; use config get <key> for any registry key):

Key	Default	Meaning
auto_index	true	Automatically index new projects at MCP startup or first graph use.
auto_index_limit	50000	Maximum file count allowed for automatic indexing of a new project.
auto_watch	true	Register indexed projects for automatic background Git-change refresh.
tool_mode	streamlined	MCP discovery surface: streamlined or classic.
context_injection	true	Include codebase schema and stats automatically in the first search_graph response.
rank_enabled	true	Compute PageRank, LinkRank, and degree views used by relevance ranking.
auto_index_deps	true	Index installed dependency APIs for cross-package search and tracing.
auto_dep_limit	20	Import-ranked automatic dependency package cap; 0 is unlimited.
similarity_enabled	true	Create MinHash similarity edges in applicable index modes.
semantic_edges_enabled	true	Create semantic-related edges in applicable index modes.
githistory_enabled	true	Create Git co-change coupling edges.
httplinks_enabled	true	Link HTTP clients to discovered routes.
default_response_format	toon	Tool-response encoding when a call omits format: toon (compact tables) or json (full objects). A per-call format argument always wins.

Normal streamlined exploration uses search_graph, trace_path, get_code, and query_graph as needed; automatic indexing and first-response context follow their settings. Classic structural discovery uses search_graph, then trace_path, then get_code_snippet; use query_graph or get_architecture for broader structure. Classic mode advertises advanced tools directly.

Named presets

Presets atomically apply exact capability sets, so a prior manual setting cannot silently leak into a comparison:

codebase-memory-mcp config preset list
codebase-memory-mcp config preset apply streamlined-quality
codebase-memory-mcp config preset apply classic-quality

streamlined-quality is the recommended default surface with all measured quality capabilities enabled. classic-quality changes only the API discovery surface while retaining those capabilities. The rank-disabled, dependency-disabled, optional-graph-disabled, and minimal-indexing presets are explicit ablations; the CLI labels them as quality tradeoffs when applied. Environment variables remain higher priority than stored preset values, and the command returns nonzero with a warning when an active override prevents the requested effective configuration.

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.