How to Configure auto_index and auto_watch for Background Indexing in codebase-memory-mcp

Set auto_index to true to automatically index new projects when an MCP session connects, and set auto_watch to true to register projects with the global git-watcher for incremental updates using the CLI commands codebase-memory-mcp config set auto_index true and codebase-memory-mcp config set auto_watch true.

The codebase-memory-mcp repository provides configurable background indexing through two key settings that control automatic project ingestion and file system monitoring. By configuring auto_index and auto_watch, you can determine whether projects are indexed immediately upon connection and whether they remain synchronized with the global git-watcher for incremental updates.

Understanding auto_index and auto_watch Settings

These two boolean flags in the runtime configuration (cbm_config_t) govern distinct behaviors in the MCP server implementation:

auto_index (default: false) When enabled, the server automatically triggers a full index of any newly connected project. This work is performed by a dedicated background thread named autoindex_thread, allowing the MCP session to remain responsive while indexing proceeds.

auto_watch (default: true) When enabled, the MCP session registers the project with the global git-watcher. This enables incremental indexing of subsequent file changes. Setting this to false suppresses watcher registration, which is useful when running multiple isolated sessions to prevent resource contention.

Configuration Storage and Constants

Settings are persisted in the user's configuration store at ~/.config/codebase-memory-mcp/config.json. The configuration keys are defined as constants in src/cli/cli.h at lines 306-307:

• CBM_CONFIG_AUTO_INDEX maps to "auto_index"
• CBM_CONFIG_AUTO_WATCH maps to "auto_watch"

CLI Configuration Commands

Use the built-in CLI to query, modify, or reset these settings:

# Display current values

codebase-memory-mcp config get auto_index
codebase-memory-mcp config get auto_watch

# Enable automatic indexing of new projects

codebase-memory-mcp config set auto_index true

# Limit the number of files that may be indexed automatically

codebase-memory-mcp config set auto_index_limit 50000

# Disable background watcher registration for isolated sessions

codebase-memory-mcp config set auto_watch false

# Reset flags to defaults

codebase-memory-mcp config reset auto_index
codebase-memory-mcp config reset auto_watch

Source Code Implementation

According to the DeusData/codebase-memory-mcp source code, the server checks these flags at specific points in the connection lifecycle.

Auto-Index Thread Creation

In src/mcp/mcp.c near line 6245, the maybe_auto_index routine checks the configuration value and spawns the background thread:

bool auto_index = cbm_config_get_bool(srv->config, CBM_CONFIG_AUTO_INDEX, false);
if (auto_index) {
    // launch background thread that builds the index
    cbm_thread_create(&srv->autoindex_tid, 0, autoindex_thread, srv);
    srv->autoindex_active = true;
}

Watcher Registration Gate

In src/mcp/mcp.c at lines 6171-6188, the helper auto_watch_enabled determines whether to attach the watcher:

static bool auto_watch_enabled(cbm_mcp_server_t *srv) {
    return cbm_config_get_bool(srv->config, CBM_CONFIG_AUTO_WATCH, true);
}

// Later in the connection flow:
if (auto_watch_enabled(srv)) {
    register_watcher_if_enabled(srv);
}

Practical Configuration Examples

Scenario: Fast Initial Connection Without Background Indexing

Use this configuration when you want manual control over when indexing occurs:

codebase-memory-mcp config set auto_index false
codebase-memory-mcp config set auto_watch true
codebase-memory-mcp connect /path/to/project

Scenario: Immediate Indexing Without Watcher Registration

Use this for isolated sessions where you want immediate searchability but don't need live updates:

codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_watch false
codebase-memory-mcp connect /path/to/project

Scenario: Limiting Auto-Index Scope

Prevent excessive resource usage by limiting the number of files processed during automatic indexing:

codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000

Summary

• auto_index controls whether new projects are automatically indexed when an MCP session connects; it defaults to false and runs in a dedicated background thread.
• auto_watch controls registration with the global git-watcher for incremental updates; it defaults to true.
• Both settings are stored in ~/.config/codebase-memory-mcp/config.json and managed via the CLI using config get, config set, and config reset.
• The implementation checks these flags in src/mcp/mcp.c through the maybe_auto_index and auto_watch_enabled functions.
• Use auto_index_limit to cap the number of files processed during automatic indexing sessions.

Frequently Asked Questions

What is the difference between auto_index and auto_watch?

auto_index triggers a full background indexing of the project when the MCP session first connects, while auto_watch registers the project with a global git-watcher that monitors for file changes after the initial connection. You can have automatic indexing without the watcher (for one-time imports) or watching without auto-indexing (for manual control over when the initial scan occurs).

Where does codebase-memory-mcp store its configuration?

Configuration settings are persisted in ~/.config/codebase-memory-mcp/config.json by default. This JSON file stores all runtime parameters including auto_index, auto_watch, and auto_index_limit.

How do I limit the number of files indexed automatically?

Set the auto_index_limit configuration value to cap how many files the autoindex_thread will process during automatic indexing. For example, run codebase-memory-mcp config set auto_index_limit 50000 to restrict automatic indexing to 50,000 files.

Can I use auto_index without registering the global watcher?

Yes. Set auto_index to true and auto_watch to false. This configuration triggers immediate background indexing when connecting to a project but prevents registration with the global git-watcher, keeping the session isolated from subsequent file change notifications.

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