@remnic/core 9.7.14 → 9.7.15

package/src/namespaces/storage.ts

@@ -312,6 +312,8 @@ export class NamespaceStorageRouter {
       this.config.hotMemoriesCacheEnabled,
       this.config.hotMemoriesCacheTtlMs,
     );
+    const { scopedCacheInvalidationEnabled } = this.config;
+    StorageManager.setScopedCacheInvalidationDefault(root, scopedCacheInvalidationEnabled);
     // Propagate the inline-attribution template so that router-created storages
     // (used by extraction and shared-promotion paths) strip citations consistently,
     // matching the behaviour of the primary this.storage instance in the orchestrator.

package/src/orchestration/maintenance.ts

@@ -523,6 +523,13 @@ export class MaintenanceScheduler {
           this.lastQmdEmbedAtMs = now;
         }
       }
+      // Note: a successful QMD update/embed clears the global QMD result caches
+      // itself (QmdClient.runUpdateForCollection / runEmbedForCollection), so
+      // this scheduler does not invalidate them here — every refresh path
+      // (direct update, namespace router, wearable/OpenClaw sync) funnels through
+      // the backend and clears centrally. A no-op pass (throttle/unavailable/
+      // backoff) does not advance lastUpdateRanAtMs, so it leaves caches warm
+      // (#1904, Codex/Cursor).
     } finally {
       this.qmdMaintenanceInFlight = false;
       if (this.qmdMaintenancePending) {

package/src/orchestration/workspace-ops.ts

@@ -646,6 +646,10 @@ export class WorkspaceOpsCoordinator {
           },
         },
         reindexSearch: async () => {
+          // qmd.update() clears the global QMD result caches itself on success
+          // (QmdClient.runUpdateForCollection), so newly-indexed wearable
+          // transcript/fact content is never hidden by a pre-sync cache entry
+          // (#1904, Codex).
           await this.deps.qmd.update();
         },
       });

package/src/orchestrator.ts

@@ -1338,12 +1338,16 @@ export class Orchestrator {
     // — including the ephemeral ones recall sub-stages build over the same dir
     // — honors the operator's setting. Destructured (not `config.<flag>`) so
     // this single access-layer read stays off the scattered-flag ratchet.
-    const { hotMemoriesCacheEnabled } = config;
+    const { hotMemoriesCacheEnabled, scopedCacheInvalidationEnabled } = config;
     StorageManager.setHotMemoriesCacheDefault(
       config.memoryDir,
       hotMemoriesCacheEnabled,
       config.hotMemoriesCacheTtlMs,
     );
+    // Register the #1904 scope-invalidation gate for this dir so every
+    // StorageManager over it (including ephemeral recall sub-stage instances)
+    // honors the operator's rollback lever.
+    StorageManager.setScopedCacheInvalidationDefault(config.memoryDir, scopedCacheInvalidationEnabled);
     this.profiler = new ProfilingCollector({
       enabled: resolvePipelineProcessingCapabilities(this.config).profiling,
       storageDir: config.profilingStorageDir || path.join(config.memoryDir, "profiling"),
@@ -1512,6 +1516,7 @@ export class Orchestrator {
           config.hotMemoriesCacheEnabled,
           config.hotMemoriesCacheTtlMs,
         );
+        StorageManager.setScopedCacheInvalidationDefault(parentDir, scopedCacheInvalidationEnabled);
         return new StorageManager(parentDir, config.entitySchemas, config.hotMemoriesCacheEnabled);
       },
     });

package/src/qmd.test.ts

@@ -357,6 +357,28 @@ test("QmdClient keeps legacy --json for older QMD query subprocess output", asyn
   ]);
 });
 
+test("QmdClient clears the global QMD result caches on a successful refresh (#1904)", async () => {
+  // The centralized invalidation lives in QmdClient.runUpdateForCollection /
+  // runEmbedForCollection so every refresh path (direct update, namespace
+  // router, wearable/OpenClaw sync) invalidates the cached pre-refresh bundles
+  // without each caller having to remember. Defend that contract.
+  const { QmdClient } = await import("./qmd.js");
+  const { setCachedQmdSearch, getCachedQmdSearch } = await import("./memory-cache.js");
+  const client = new QmdClient("test", 5) as any;
+  client.available = true;
+  client.runQmdCommand = async () => ({ stdout: "", stderr: "" });
+  setCachedQmdSearch("stale-bundle", [{ path: "facts/old.md" }]);
+  assert.notEqual(getCachedQmdSearch("stale-bundle"), null, "cache populated before refresh");
+  // updateCollectionStrict uses force=true, bypassing throttle/backoff gates so
+  // the refresh deterministically reaches the success point that clears caches.
+  await client.updateCollectionStrict("test");
+  assert.equal(
+    getCachedQmdSearch("stale-bundle"),
+    null,
+    "a successful refresh must clear the cached pre-refresh QMD bundle",
+  );
+});
+
 test("parseQmdExplain preserves qmd 2.5 nested RRF trace fields", () => {
   assert.deepEqual(
     parseQmdExplain({

package/src/qmd.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { log } from "./logger.js";
-import { getCachedQmdSearch, setCachedQmdSearch } from "./memory-cache.js";
+import { clearQmdResultCaches, getCachedQmdSearch, setCachedQmdSearch } from "./memory-cache.js";
 import {
   abortError,
   isAbortError,
@@ -2739,6 +2739,13 @@ export class QmdClient implements SearchBackend {
         this.lastUpdateRunAtMs = at;
         globalState.lastGlobalUpdateRunAtMs = at;
       }
+      // A successful index refresh makes newly-persisted facts searchable, so
+      // any cached pre-refresh QMD search/recall bundle is now stale. Clear the
+      // global QMD result caches here, at the single success point EVERY update
+      // path funnels through (direct calls, wearable/OpenClaw sync reindex, and
+      // the namespace router's per-backend update), so no caller can forget and
+      // serve a stale bundle past the refresh (#1904, Codex/Cursor).
+      clearQmdResultCaches();
       log.debug(`QMD update completed for collection=${name}`);
     } catch (err) {
       const at = Date.now();
@@ -2853,6 +2860,9 @@ export class QmdClient implements SearchBackend {
         globalState.lastEmbedByCollectionMs[name] = at;
       }
       globalState.lastGlobalEmbedRunAtMs = at;
+      // A successful embed changes vector searchability, so cached pre-embed
+      // bundles may now be stale. Clear at this single success point (#1904).
+      clearQmdResultCaches();
       log.debug(`QMD embed completed for collection=${name}`);
     } catch (err) {
       let failure: unknown = err;
@@ -2869,6 +2879,8 @@ export class QmdClient implements SearchBackend {
           }
           globalState.lastGlobalEmbedRunAtMs = recoveredAt;
           globalState.lastGlobalEmbedFailAtMs = null;
+          // Recovery also changed vector searchability — clear cached bundles.
+          clearQmdResultCaches();
           log.warn(`QMD embed for collection ${name} recovered by forcing a full vector rebuild`);
           return;
         } catch (retryErr) {

package/src/search/port.ts

@@ -119,6 +119,17 @@ export interface SearchBackend {
 
   // ── Maintenance ──
   update(execution?: SearchExecutionOptions): Promise<void>;
+  /**
+   * Wall-clock ms of the most recent SUCCESSFUL index refresh, or null when the
+   * backend has never run one. Ordinary update() is fail-open: it returns
+   * silently (without throwing or advancing this timestamp) when the backend is
+   * unavailable or the call is suppressed by a min-interval / failure backoff.
+   * Callers that must know whether update() actually indexed — so they can
+   * invalidate dependent caches only on a real refresh — snapshot this before
+   * the call and treat the backend as refreshed iff the value advanced. Optional
+   * because not every backend tracks it; absent means "assume refreshed".
+   */
+  readonly lastUpdateRanAtMs?: number | null;
   /**
    * Optional strict refresh used by callers that must know whether the backend
    * was actually refreshed before writing success markers. Ordinary update

package/src/storage.ts

@@ -33,6 +33,8 @@ import {
   getCachedMemories,
   invalidateAllForDir,
   invalidateDerivedAndGlobalForDir,
+  invalidateForScope,
+  invalidateForScopeExceptHot,
   setCachedEntities,
   setCachedMemories,
   updateCacheOnDelete,
@@ -2385,6 +2387,17 @@ export class StorageManager {
    */
   private static hotMemoriesCacheProcessDefaultSeeded = false;
 
+  /**
+   * Per-memory-directory gate for scope-aware cache invalidation (issue #1904).
+   * Registered from config by the orchestrator via
+   * setScopedCacheInvalidationDefault() so every StorageManager built over a
+   * memory dir — including ephemeral recall sub-stage instances — honors the
+   * operator's setting. Unregistered dirs default to `true` (scoped on). Set
+   * `false` to restore the pre-#1904 full-clear-per-write behavior (rollback
+   * lever). Read once per write via isScopedCacheInvalidationEnabled().
+   */
+  private static readonly scopedCacheInvalidationByDir = new Map<string, boolean>();
+
   // Module-level maps for readAllMemories() keyed by base directory, shared
   // across all StorageManager instances (static) so concurrent callers over
   // the same dir cooperate.
@@ -2752,6 +2765,15 @@ export class StorageManager {
     }
   }
 
+  /** Register the operator's scope-aware cache invalidation gate for a memory
+   *  dir (issue #1904). The orchestrator/access layer calls this with
+   *  the operator's scopedCacheInvalidationEnabled flag so the setting reaches every
+   *  StorageManager built over the dir, including ephemeral recall-sub-stage
+   *  instances. Only an explicit `false` disables; `undefined` leaves it on. */
+  static setScopedCacheInvalidationDefault(memoryDir: string, enabled: boolean | undefined): void {
+    StorageManager.scopedCacheInvalidationByDir.set(memoryDir, enabled !== false);
+  }
+
   /**
    * The LIVE class object of this instance (issue #1809 review of the
    * storage decomposition): extracted store modules must read/write the
@@ -4110,7 +4132,7 @@ export class StorageManager {
 
     await this.snapshotBeforeWrite(filePath, "write");
     await this.writeStorageSecureFile(filePath, fileContent);
-    await this.patchHotMemoriesCache({ addedPath: filePath });
+    await this.patchHotMemoriesCache({ addedPath: filePath }, "memory-create");
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeMemory", {
       memoryId: id,
       eventType: "created",
@@ -4559,6 +4581,10 @@ export class StorageManager {
     StorageManager.hotMemoriesCacheDefault = true;
     StorageManager.hotMemoriesCacheTtlMs = 60_000;
     StorageManager.hotMemoriesCacheProcessDefaultSeeded = false;
+    // Reset the #1904 scope-invalidation gate so a legacy-mode (=false) test
+    // dir cannot leak its setting into a later test constructing over a reused
+    // temp path.
+    StorageManager.scopedCacheInvalidationByDir.clear();
   }
 
   /** Cancel any in-flight concurrent read so the next readAllMemories()
@@ -4579,13 +4605,21 @@ export class StorageManager {
     // corpus sentinel too so PEER processes rescan instead of serving a warm
     // pre-mutation corpus entry (issue #1902 cross-process coherence).
     this.bumpMemoryCorpusVersion();
-    // Invalidation chokepoint (issue #1535): eagerly evict EVERY process-level
-    // cache layer that can serve memory-derived content for this dir — hot,
-    // archive, entity, derived episode/rule views, and both QMD result caches
-    // (qmdSearchCache and qmdRecallCache). Before this call was added, the QMD
-    // recall cache was never invalidated on mutations, so recall served
-    // pre-edit bundles for the remainder of its fresh/stale TTL window.
-    invalidateAllForDir(this.baseDir);
+    // Invalidation chokepoint (issue #1535 / #1904): evict the layers a
+    // memory-mutate can affect — hot, archive, derived episode/rule views, and
+    // both QMD result caches (qmdSearchCache and qmdRecallCache). Before the QMD
+    // caches were invalidated on mutations, recall served pre-edit bundles for
+    // the remainder of its fresh/stale TTL window. The `entities` layer is NOT
+    // in memory-mutate scope: these funnel callers (update/frontmatter/move/
+    // archive/invalidate/bulk/offline-sync) never rewrite entity files, and the
+    // ones that touch entity-derived state additionally bump the status version
+    // (which does the full clear). scopedCacheInvalidationEnabled=false restores
+    // the pre-#1904 full clear of every layer (rollback lever).
+    if (StorageManager.scopedCacheInvalidationByDir.get(this.baseDir) ?? true) {
+      invalidateForScope(this.baseDir, "memory-mutate");
+    } else {
+      invalidateAllForDir(this.baseDir);
+    }
     // Issue #1579 — tombstone store is a cache layer too (rule 25: clear ALL
     // cache layers). A tombstone append from another path (supersession /
     // correction) must be visible to the next writeMemory lookup on this
@@ -4614,7 +4648,10 @@ export class StorageManager {
    * coherence is preserved. Bulk/ambiguous mutations keep the wholesale
    * invalidateAllMemoriesCache() drop instead (issue #1902 Step 5).
    */
-  private async patchHotMemoriesCache(opts: { addedPath?: string; removedPath?: string }): Promise<void> {
+  private async patchHotMemoriesCache(
+    opts: { addedPath?: string; removedPath?: string },
+    scope: "memory-create" | "memory-mutate" = "memory-mutate",
+  ): Promise<void> {
     const prevVersion = this.getMemoryCorpusVersion();
     // Snapshot the key identity once (issue #1902, Codex Medium): a mid-await
     // setSecureStoreKey change would otherwise let the post-await patch/re-key
@@ -4684,9 +4721,19 @@ export class StorageManager {
       const patched = getCachedMemories(this.baseDir, prevVersion, keyId);
       if (patched) setCachedMemories(this.baseDir, patched, produced, keyId, this.hotCacheTtlMs());
     }
-    // Evict every OTHER layer; the hot layer is patched (or intentionally left
-    // to be version-rejected) above, not dropped here.
-    invalidateDerivedAndGlobalForDir(this.baseDir);
+    // Evict the non-hot layers; the hot layer is patched (or intentionally left
+    // to be version-rejected) above, not dropped here. Scope-aware (issue #1904):
+    // a `memory-create` evicts ONLY the derived episode/rule views, keeping the
+    // global QMD result caches and the version-keyed entity cache warm (a create
+    // adds a doc that is not yet in the QMD index and changes no existing doc's
+    // recall visibility). A `memory-mutate` (or scoped-off rollback) still evicts
+    // the derived + global QMD views so a superseded/edited memory cannot resurface
+    // from a stale recall bundle (issue #1535 correctness contract).
+    if (scope === "memory-create" && (StorageManager.scopedCacheInvalidationByDir.get(this.baseDir) ?? true)) {
+      invalidateForScopeExceptHot(this.baseDir, "memory-create");
+    } else {
+      invalidateDerivedAndGlobalForDir(this.baseDir);
+    }
     if (this.tombstoneStore) {
       this.tombstoneStore.invalidate();
       this.tombstoneStore = null;
@@ -6648,7 +6695,7 @@ export class StorageManager {
     await this.writeStorageSecureFile(filePath, fileContent);
     // Keep the version-keyed hot-memories cache coherent with the new chunk
     // file (issue #1902) — same single-file patch path writeMemory uses.
-    await this.patchHotMemoriesCache({ addedPath: filePath });
+    await this.patchHotMemoriesCache({ addedPath: filePath }, "memory-create");
     log.debug(`wrote chunk ${id} (${chunkIndex + 1}/${chunkTotal}) to ${filePath}`);
     return id;
   }

package/src/types.ts

@@ -1054,6 +1054,15 @@ export interface PluginConfig {
    * pure-daemon deployments with no external edits).
    */
   hotMemoriesCacheTtlMs: number;
+  /**
+   * Scope-aware cache invalidation (issue #1904). When true (default), a memory
+   * write evicts only the cache layers it can actually affect — a plain fact
+   * `create` no longer nukes the global QMD result caches or the version-keyed
+   * entity cache, so continuous extraction stops keeping every cache
+   * permanently cold. Set false to restore the pre-#1904 behavior of clearing
+   * every layer on every write (rollback lever; no featureset change).
+   */
+  scopedCacheInvalidationEnabled: boolean;
   // Unified TrustScore recall stage (issue #1577). Combines memory-worth,
   // provenance, faithfulness, corroboration, contradiction, feedback, recency,
   // and optional domain calibration into one [0,1] trust score applied as a
@@ -1993,6 +2002,12 @@ export interface PluginConfig {
   tagRecallMaxMatches: number;
   // v8.2 multi-graph memory (PR 18)
   multiGraphMemoryEnabled: boolean;
+  // Incremental GraphIndex edge cache (issue #1904). When true (default), a
+  // single-writer edge append is pushed into the warm edge cache in place
+  // (revalidated by file size for cross-process coherence) instead of nulling
+  // the 6 MB / 30k-edge cache and re-reading + re-parsing it (2-4 s). Set false
+  // to restore the pre-#1904 behavior of nulling the edge cache on every write.
+  graphEdgeCacheIncrementalEnabled: boolean;
   // v8.2 PR 19A: graph recall planner gating
   graphRecallEnabled: boolean;
   graphRecallMaxExpansions: number;