docs(memory): clarify watcher default wording

RomneyDa · RomneyDa · commit beac3c9ccf64 · 2026-06-01T13:17:03.000-07:00
diff --git a/docs/concepts/memory-builtin.md b/docs/concepts/memory-builtin.md
@@ -85,10 +85,10 @@ OpenClaw indexes `MEMORY.md` and `memory/*.md` into chunks (~400 tokens with
 - **Storage maintenance:** SQLite WAL sidecars are bounded with periodic and
   shutdown checkpoints.
 - **File watching:** changes to memory files trigger a debounced reindex (1.5s).
-  It stays enabled by default, including in gateway mode, so small and typical
-  workspaces keep near-real-time freshness. Large memory trees, `extraPaths`, or
-  QMD collections can create file-descriptor pressure in long-lived gateways;
-  set `sync.watch: false` if that happens.
+  File watching is enabled by default, including for gateways, so memory edits
+  become searchable without a manual reindex. Large memory trees, `extraPaths`,
+  or QMD collections can use many file descriptors in long-lived gateways; set
+  `sync.watch: false` for affected agents if that becomes a problem.
 - **Auto-reindex:** when the embedding provider, model, or chunking config
   changes, the entire index is rebuilt automatically.
 - **Reindex on demand:** `openclaw memory index --force`
@@ -129,8 +129,8 @@ openclaw memory index --force --agent main
 Both standalone CLI commands and the Gateway use the same `local` provider id.
 Set `memorySearch.provider: "local"` when you want local embeddings.
 
-**Stale results?** Run `openclaw memory index --force` to rebuild. The watcher
-may be disabled explicitly or miss changes in rare edge cases.
+**Stale results?** Run `openclaw memory index --force` to rebuild. Use this when
+file watching is disabled or misses a change.
 
 **sqlite-vec not loading?** OpenClaw falls back to in-process cosine similarity
 automatically. `openclaw memory status --deep` reports the local vector store
diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md
@@ -527,7 +527,9 @@ QMD model overrides stay on the QMD side, not OpenClaw config. If you need to ov
   </Accordion>
 </AccordionGroup>
 
-QMD boot refreshes use a one-shot subprocess path during gateway startup. The long-lived QMD manager owns the regular file watcher and interval timers when memory search is opened for interactive use. Gateway configs that leave `memorySearch.sync.watch` enabled can warn when memory/QMD surfaces look prone to file-descriptor pressure; set `sync.watch: false` for affected agents if FD usage grows.
+QMD boot refreshes use a one-shot subprocess path during gateway startup. The long-lived QMD manager owns the regular file watcher and interval timers when memory search is opened for interactive use.
+
+Gateway configs can warn when `memorySearch.sync.watch` is enabled for memory or QMD surfaces that may use many file descriptors. If watcher FD usage grows, set `sync.watch: false` for the affected agents and use manual indexing or `sync.intervalMinutes` for freshness.
 
 ### Full QMD example
 
diff --git a/extensions/memory-core/src/memory/qmd-manager.ts b/extensions/memory-core/src/memory/qmd-manager.ts
@@ -1617,8 +1617,6 @@ export class QmdMemoryManager implements MemorySearchManager {
     this.watcher.on("change", markDirty);
     this.watcher.on("unlink", markDirty);
     this.watcher.on("error", (err) => {
-      // File watcher errors (for example ENOSPC/EMFILE) should not crash the
-      // gateway. Search still works; automatic watch freshness may be degraded.
       const message = err instanceof Error ? err.message : String(err);
       log.warn(`qmd watcher error: ${message}`);
     });
diff --git a/src/agents/memory-search.ts b/src/agents/memory-search.ts
@@ -113,10 +113,7 @@ export type ResolvedMemorySearchConfig = {
 export type ResolvedMemorySearchSyncConfig = ResolvedMemorySearchConfig["sync"];
 export type MemorySearchResolvePurpose = "default" | "status" | "cli";
 export type MemorySearchResolveOptions = {
-  /**
-   * @deprecated Accepted for SDK compatibility. Memory watch defaults no longer
-   * vary by resolver purpose.
-   */
+  /** @deprecated No-op; kept for resolver call-site compatibility. */
   purpose?: MemorySearchResolvePurpose;
 };
 
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
@@ -1331,7 +1331,7 @@ export const FIELD_HELP: Record<string, string> = {
   "agents.defaults.memorySearch.sync.onSearch":
     "Uses lazy sync by scheduling reindex on search after content changes are detected. Keep enabled for lower idle overhead, or disable if you require pre-synced indexes before any query.",
   "agents.defaults.memorySearch.sync.watch":
-    "Watches memory files and schedules index updates from file-change events (default: true). Disable on large memory trees, extraPaths, QMD collections, or multi-agent gateways if watcher file-descriptor pressure appears.",
+    "Watches memory files and schedules index updates from file-change events. Default: true. Disable for large memory trees, extraPaths, QMD collections, or multi-agent gateways if watcher file-descriptor usage becomes a problem.",
   "agents.defaults.memorySearch.sync.watchDebounceMs":
     "Debounce window in milliseconds for coalescing rapid file-watch events before reindex runs. Increase to reduce churn on frequently-written files, or lower for faster freshness.",
   "agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds":
diff --git a/src/config/types.tools.ts b/src/config/types.tools.ts
@@ -523,7 +523,7 @@ export type MemorySearchConfig = {
   sync?: {
     onSessionStart?: boolean;
     onSearch?: boolean;
-    /** Watch memory files for near-real-time reindexing. Default: true. */
+    /** Watch memory files for reindexing (default: true). */
     watch?: boolean;
     watchDebounceMs?: number;
     intervalMinutes?: number;
