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

> Configure auto_index and auto_watch for background indexing in codebase-memory-mcp efficiently. Enable automatic indexing and incremental updates via CLI commands for seamless project management and enhanced performance.

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

---

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

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) near line 6245, the `maybe_auto_index` routine checks the configuration value and spawns the background thread:

```c
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) at lines 6171-6188, the helper `auto_watch_enabled` determines whether to attach the watcher:

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

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

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

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