Configure Auto-Index and Auto-Watch Settings in codebase-memory-mcp: A Complete Guide

To control automatic knowledge graph maintenance in codebase-memory-mcp, set the runtime boolean flags auto_index (default false) and auto_watch (default true), which govern whether the server indexes new projects on session start and whether it registers a background file watcher for incremental updates.

The codebase-memory-mcp server maintains a live representation of your codebase by automatically indexing files and detecting changes. Understanding how to configure the auto-index and auto-watch settings allows you to balance immediate code intelligence against system resource usage, ensuring the graph updates only when you need it to.

Understanding the Core Settings

Two configuration keys govern the server's automatic behavior:

• Auto-Index (auto_index): When true, the server immediately begins indexing any new project upon opening an MCP session. If a SQLite graph already exists for the project, indexing is skipped and the watcher is registered instead.
• Auto-Watch (auto_watch): When true, the server registers the project with the background file-watcher after indexing (or when opening an already-indexed project). Setting this to false isolates the session from automatic updates.

Both settings persist in the runtime SQLite configuration database at ${CBM_CACHE_DIR}/_config.db and are read via the cbm_config_get_bool() API.

Configuration Key Definitions

In src/cli/cli.h, the configuration subsystem defines these keys as string literals:

#define CBM_CONFIG_AUTO_INDEX "auto_index"
#define CBM_CONFIG_AUTO_WATCH "auto_watch"

Source: src/cli/cli.h lines 306-307

These constants are used throughout the codebase to look up values in the SQLite config store.

Implementation in the MCP Server

The gating logic for both features resides in src/mcp/mcp.c, where the server evaluates these flags before launching background threads.

Auto-Watch Gating Logic

The helper function auto_watch_enabled() retrieves the current setting, defaulting to true when no configuration exists:

static bool auto_watch_enabled(cbm_mcp_server_t *srv) {
    if (!srv->config) {
        return true;  // default on
    }
    return cbm_config_get_bool(srv->config, CBM_CONFIG_AUTO_WATCH, true);
}

Source: src/mcp/mcp.c lines 5687-5695

Before registering the file watcher, the server explicitly checks this flag:

if (!auto_watch_enabled(srv)) {
    cbm_log_info("watcher.register.skipped",
                 "reason", "auto_watch_off",
                 "project", srv->session_project);
    return;
}
cbm_watcher_watch(srv->watcher, srv->session_project, srv->session_root);

Source: src/mcp/mcp.c lines 5703-5708

Auto-Index Execution Flow

The maybe_auto_index() function handles the automatic indexing decision. It checks the auto_index flag (defaulting to false), determines if a database already exists, and either launches the indexing pipeline or skips to watcher registration:

static void maybe_auto_index(cbm_mcp_server_t *srv) {
    // ...
    bool auto_index = cbm_config_get_bool(srv->config,
                                          CBM_CONFIG_AUTO_INDEX, false);
    if (!auto_index) {
        cbm_log_info("autoindex.skipped",
                     "reason", "auto_index_off",
                     "project", srv->session_project);
        return;
    }
    // ...
    register_watcher_if_enabled(srv);
}

When the indexing pipeline completes successfully, the server logs the event and hands off to the watcher registration routine:

if (rc == 0) {
    cbm_log_info("autoindex.done", "project", srv->session_project);
    register_watcher_if_enabled(srv);
}

Source: src/mcp/mcp.c lines 5151-5155

CLI Configuration Examples

Use the config subcommand to modify these settings persistently. According to the documentation in docs/CONFIGURATION.md and README.md, valid operations include:

# Enable auto-index for all future sessions (default is off)

codebase-memory-mcp config set auto_index true

# Limit auto-index to projects with ≤ 50,000 files

codebase-memory-mcp config set auto_index_limit 50000

# Disable the background watcher for isolated sessions

codebase-memory-mcp config set auto_watch false

# Verify current settings

codebase-memory-mcp config list

These commands write to the SQLite config database at ${CBM_CACHE_DIR}/_config.db and take effect on the next MCP session start.

Programmatic Configuration (C API)

When embedding the library, access these settings directly via the configuration API and manually trigger indexing when automatic indexing is disabled:

/* Assume `srv` is a fully-initialized `cbm_mcp_server_t *` */
bool idx = cbm_config_get_bool(srv->config, CBM_CONFIG_AUTO_INDEX, false);
bool wk  = cbm_config_get_bool(srv->config, CBM_CONFIG_AUTO_WATCH, true);

/* Force a manual index when auto-index is disabled */
if (!idx) {
    cbm_mcp_server_start_index(srv, "/path/to/your/repo");
}

Summary

• Auto-index (auto_index, default false) triggers automatic indexing when opening a new project in an MCP session, while skipping existing graphs.
• Auto-watch (auto_watch, default true) registers the background file watcher after indexing; disabling it isolates the session from automatic updates.
• Configuration keys are defined in src/cli/cli.h and evaluated in src/mcp/mcp.c via cbm_config_get_bool().
• Runtime settings persist in ${CBM_CACHE_DIR}/_config.db and can be modified via CLI or the C API.
• Disabling auto_watch while keeping auto_index enabled results in one-time indexing without continuous file monitoring.

Frequently Asked Questions

What happens if I disable auto-watch but enable auto-index?

The server will perform the initial indexing when you open a new project, but will not register the background file watcher. You must manually invoke codebase-memory-mcp cli index_repository to refresh the knowledge graph when files change, as the session remains isolated from automatic updates.

Where are these configuration values stored?

Both settings persist in a SQLite database located at ${CBM_CACHE_DIR}/_config.db. The server reads them at runtime using the generic configuration getter cbm_config_get_bool(), as implemented in the config subsystem referenced throughout src/mcp/mcp.c.

Can I set different auto-index limits per project?

Yes. You can configure a global size limit using codebase-memory-mcp config set auto_index_limit 50000, which prevents automatic indexing on repositories exceeding 50,000 files. This threshold applies to all projects when auto_index is enabled, protecting against excessive resource consumption on large monorepos.

How do I temporarily disable auto-index for a single session without changing the global config?

Since auto_index defaults to false when unset, simply ensure the global config does not explicitly set it to true. Alternatively, you can programmatically override the behavior by calling cbm_mcp_server_start_index() manually only when needed, bypassing the automatic check in maybe_auto_index() as defined in src/mcp/mcp.c.

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