You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f8b2f36
Browse filesBrowse the repository at this point in the historyBrowse files
`auto_index` is off by default. When enabled, new projects are indexed automatically on first connection. The configurable file limit is `config set auto_index_limit 50000`. Previously indexed projects can be watched independently through `auto_watch` (on by default), subject to the session rules below.
256
+
`auto_index` is off by default. When enabled, new projects are indexed automatically on first connection. The configurable file limit is `config set auto_index_limit 50000`. Previously indexed projects can be watched through `auto_watch` (on by default), subject to its global setting and session ownership.
257
257
258
-
The watcher follows MCP sessions: it watches the project each open MCP session is rooted in (the client's working directory) and stops when the last session for that project closes. A repository indexed with `cli index_repository`, or indexed from a session rooted somewhere else, is not watched; re-run `index_repository` after changing it. `index_status` reports this in its `watch` object: `watched`, and either the poll cadence and last scan time or the `reason` it is not watched.
258
+
Each initialized, long-lived MCP session can register its root project when it connects and any target from a successful `index_repository` call, including custom project names and roots in another worktree. While `auto_watch`is enabled, these watches belong to the registering sessions and remain while at least one owning session is connected; closing the last owner removes the watch. An async index registers its target only after success and while its requesting session remains connected. CLI indexing and failed MCP indexes do not register watches. Global `auto_watch` controls registration and removes all watches on the next refresh or registration request when set to `false`. `index_status` reports this in its `watch` object: `watched`, and either the poll cadence and last scan time or the `reason` it is not watched.
259
259
260
-
Watcher registration is controlled separately by `auto_watch` (default `true`). Set `config set auto_watch false` to keep a session from registering its project with the background watcher; useful when working across many projects and you want each session contained to explicit indexing.
260
+
Watcher registration is controlled globally by `auto_watch` (default `true`). On the next refresh or registration request, `true` allows MCP sessions to register their root on connect and their successful `index_repository` targets; `false` removes all watches. CLI indexing and failed MCP indexes do not add watches.
261
261
262
-
To turn the watcher off entirely, set `config set watcher_enabled false` (default `true`): the background poll thread never starts and no project is registered, while `auto_index` and manual `index_repository` keep working. Unlike `auto_watch`, which is consulted per session, `watcher_enabled` is read once when the background daemon starts, so run `codebase-memory-mcp daemon stop` after changing it; reconnecting your MCP client alone will not restart the daemon. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#2-cli-managed-runtime-settings).
262
+
To turn the watcher off entirely, set `config set watcher_enabled false` (default `true`): the background poll thread never starts and no project is registered, while `auto_index` and manual `index_repository` keep working. Unlike `auto_watch`, which takes effect on the next refresh or registration request, `watcher_enabled` is read once when the background daemon starts, so run `codebase-memory-mcp daemon stop` after changing it; reconnecting your MCP client alone will not restart the daemon. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#2-cli-managed-runtime-settings).
263
263
264
264
The watcher follows **git** projects only by default: a project indexed from a directory that is not a git repository is not watched and stays at its last index until you run `index_repository` again. To have such roots polled too, set `config set watch_non_git true` (default `false`, read when the daemon starts): they are then checked on the same cadence with a file-tree scan that uses the indexer's own ignore rules.
265
265
@@ -402,7 +402,7 @@ In this repository, test narrowing is wired to the Linux x86_64 test leg when `T
402
402
403
403
### Distribution & operation
404
404
-**Native runtime set, zero infrastructure services**: SQLite-backed, persists to `~/.cache/codebase-memory-mcp/`
405
-
-**Auto-sync**: Background watcher detects file changes in the project an MCP session is working in and re-indexes it automatically (other indexed repos: re-run `index_repository`)
405
+
-**Auto-sync**: Background watcher detects file changes in projects registered by active MCP sessions, including successful explicit `index_repository` targets, and re-indexes them automatically.
406
406
-**Route nodes**: REST endpoints are first-class graph entities
@@ -873,7 +873,7 @@ Tools requiring arguments accept JSON piped on stdin. Tools with only optional a
873
873
874
874
| Tool | Description |
875
875
|------|-------------|
876
-
|`index_repository`| Index a repository into the graph. Auto-sync keeps it fresh only while it is the project of an open MCP session; repos indexed from the CLI or from another project's session need a re-run (`index_status` shows `watch`). Waits for the whole index by default; pass `async: true` to start it in the daemon and return at once, then poll with `status: true` (see below). |
876
+
|`index_repository`| Index a repository into the graph. A successful call from an active MCP session registers the target for auto-sync while that session remains connected, subject to the global `auto_watch` setting; CLI calls do not register watches. Waits for the whole index by default; pass `async: true` to start it in the daemon and return at once, then poll with `status: true` (see below). |
877
877
|`list_projects`| List indexed projects with paging; use `detail: "stats"` for node/edge counts and database sizes. |
878
878
|`delete_project`| Remove a project and all its graph data. |
879
879
|`index_status`| Check indexing status of a project. |
@@ -967,7 +967,7 @@ See [docs/cbmignore.md](docs/cbmignore.md) for the full `.cbmignore` how-to: syn
967
967
codebase-memory-mcp config list # show all settings
968
968
codebase-memory-mcp config set auto_index true# auto-index on session start
969
969
codebase-memory-mcp config set auto_index_limit 50000 # max files for auto-index
codebase-memory-mcp config set auto_watch false#remove/disable all background watches (default: true)
971
971
codebase-memory-mcp config set doc_candidates false# skip doc<->code candidate scoring on huge repos (default: auto = on for full, off for moderate/fast)
972
972
codebase-memory-mcp config set watcher_enabled false# stop the watcher thread entirely (default: true)
973
973
codebase-memory-mcp config set watch_non_git true# also poll non-git project roots (default: false)
Copy file name to clipboardExpand all lines: docs/CONFIGURATION.md
+14-6Lines changed: 14 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -87,9 +87,9 @@ Current keys:
87
87
|---|---|---|
88
88
|`auto_index`|`false`| Automatically index new projects when an MCP session starts. |
89
89
|`auto_index_limit`|`50000`| Maximum file count allowed for automatic indexing of a new project. |
90
-
|`auto_watch`|`true`|Register the session's project with the background git watcher on connect. Set `false`to keep a session from registering its project (the watcher still runs for other projects). |
90
+
|`auto_watch`|`true`|Global switch for MCP session watch registration. On the next refresh or registration request, `true` allows session roots and successful `index_repository` targets to be watched; `false` removes all watches. The background watcher can still run with no registered projects. |
91
91
|`doc_candidates`|`auto`| Score documentation sections against code to store doc↔code candidates (the possible targets of a section, and the sections that may describe a function or file, each with a judged probability). Unset (`auto`), the index mode decides: on for `full` indexes (the default mode), off for `moderate` and `fast`. Set `true` or `false` to choose for every mode; `config reset doc_candidates` returns to `auto`. The scoring grows with sections × functions: under a second up to ~100k functions, ~15 s at ~400k, ~3 minutes on the Linux kernel. Off stores no candidates and leaves the rest of the graph unchanged; on in `fast` mode stores candidates without adding `fast`'s skipped `SIMILAR_TO` / `SEMANTICALLY_RELATED` edges. `index_repository` also takes `doc_candidates` for a single index, which wins over this setting. Applies from the next index. |
92
-
|`watcher_enabled`|`true`| Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. Only an open MCP session's own project is ever watched; `index_status` reports the current state in its `watch` object. |
92
+
|`watcher_enabled`|`true`| Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. Active MCP sessions can register their root project and successful explicit index targets; `index_status` reports the current state in its `watch` object. |
93
93
|`watch_non_git`|`false`| Also poll project roots that are **not git repositories**. By default the watcher only follows git projects, so a project indexed from a plain directory is never refreshed after its first index — reindex it manually with `index_repository`. Set `true` to poll such roots on the same adaptive cadence with a file-tree scan: the indexer's own discovery walk (same skip lists, `.gitignore` and `.cbmignore` rules) hashed over each file's path, size and mtime. Any change reindexes once; paths the indexer skips (including cbm's own `.codebase-memory/` output) never trigger. The first poll after the daemon starts reindexes each such project once, since nothing records which tree state the index holds. The scan walks the whole tree every poll, so it costs more than git polling on very large trees. Read once when the daemon starts, like `watcher_enabled`. |
94
94
|`index_max_files`|`off`| Optional maximum number of accepted source files in one discovery run. |
95
95
|`index_max_source_mb`|`off`| Optional maximum accepted source size in MiB in one discovery run. |
@@ -102,15 +102,23 @@ has not run yet).
102
102
103
103
> **`watcher_enabled` vs `auto_watch`.**`watcher_enabled` controls whether the
104
104
> watcher *subsystem* starts at all (the background poll thread). `auto_watch` is
105
-
> narrower: it only controls whether a connecting session registers *its own*
106
-
> project with an already-running watcher. When `watcher_enabled=false`,
105
+
> narrower: it globally controls MCP session watch registration. On the next
106
+
> refresh or registration request, `false` removes all watches; `true` allows
107
+
> session roots and successful explicit `index_repository` targets to register.
108
+
> Watcher refreshes retain `mode`, `persistence`, and the resolved
109
+
> `doc_candidates` boolean from the latest successful explicit index registered
110
+
> for that target. This boolean can come from the request or its global setting.
111
+
> When neither supplied a boolean, refresh uses the current setting or mode default.
112
+
> A watcher callback also observes `auto_watch=false`: it removes all watches
113
+
> before admitting any new refresh work.
114
+
> When `watcher_enabled=false`,
107
115
> `auto_watch` has no effect — there is no watcher to register with.
108
116
>
109
117
> They also differ in **when they are read**, which matters because the watcher
110
118
> lives in the background daemon, not in your MCP client:
111
119
>
112
-
> -`auto_watch`is consulted each time a session would register its project, so
113
-
> a change applies to sessions that connect afterwards.
120
+
> -`auto_watch`takes effect on the next refresh or registration request and
121
+
> applies globally to session roots and successful `index_repository` targets.
114
122
> -`watcher_enabled` is read **once, when the daemon starts**, because it decides
115
123
> whether the watcher is built at all. The daemon is long-lived and outlives
116
124
> individual MCP sessions, so **reconnecting your client is not enough** — retire
0 commit comments