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	false	Automatically index installed dependency source for cross-package search and tracing.
auto_dep_limit	20	Import-ranked automatic dependency package cap; 0 is unlimited.
dep_max_files	1000	Maximum source files per automatically indexed dependency package; larger packages are skipped atomically, and 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-automatic-dependency-source-indexing-disabled
codebase-memory-mcp config preset apply streamlined-automatic-dependency-source-indexing-enabled
codebase-memory-mcp config preset apply classic-automatic-dependency-source-indexing-disabled
codebase-memory-mcp config preset apply classic-automatic-dependency-source-indexing-enabled

The four product presets pair the streamlined or classic tool surface with an explicit automatic dependency-source indexing state. All four enable the same rank, similarity, semantic-edge, Git-history, and HTTP-link capabilities. The disabled variants bound default indexing latency, CPU, memory, and stored graph size; the enabled variants add installed dependency-source coverage up to auto_dep_limit; dep_max_files skips oversized packages rather than publishing partial API coverage. index_dependencies remains available for explicit packages. Disabling automation stops future automatic dependency indexing but does not delete dependency projects already indexed. rank-disabled and minimal-indexing are benchmark ablations, and the CLI labels them accordingly. The minimal-indexing preset disables optional graph passes and dependency-source automation; the post-edit reindex strategy is unchanged. Environment variables remain higher priority than stored preset values, and preset application returns nonzero 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.