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

> Master codebase-memory-mcp auto-index and auto-watch settings. Learn to control knowledge graph updates and file watching for efficient project indexing. Essential guide.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-06

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.h), the configuration subsystem defines these keys as string literals:

```c
#define CBM_CONFIG_AUTO_INDEX "auto_index"
#define CBM_CONFIG_AUTO_WATCH "auto_watch"

```

Source: [src/cli/cli.h lines 306-307](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.h#L306-L307)

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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```c
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](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c#L5687-L5695)

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

```c
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](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c#L5703-L5708)

### 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:

```c
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:

```c
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](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c#L5151-L5155)

## CLI Configuration Examples

Use the `config` subcommand to modify these settings persistently. According to the documentation in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) and [`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md), valid operations include:

```bash

# 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:

```c
/* 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.h) and evaluated in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c).