@remnic/core 9.69.101 → 9.69.103

package/src/entity-retrieval.ts

@@ -2,7 +2,7 @@ import { resolveNamespaceCapabilities } from "./capabilities.js";
 import { renderAuthorityBoundContent } from "./recall-context-composition.js";
 import { createHash } from "node:crypto";
 import { sanitizeMemoryContent } from "./sanitize.js";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { collectNativeKnowledgeChunks, type NativeKnowledgeChunk } from "./native-knowledge.js";
 import { compareEntityTimestamps, normalizeEntityName, type StorageManager } from "./storage.js";
@@ -22,6 +22,15 @@ import {
   yieldEntityRecallScan,
   yieldEntityRecallScanEvery,
 } from "./entity-recall-cancellation.js";
+import { applyCarriedMemorySnippets } from "./entity-mention-carry.js";
+import {
+  entityMentionCacheGeneration,
+  entityMentionIdentity,
+  entityMentionPersistedIndexReadable,
+  entityMentionScopeKey,
+  resolveEntityMentionIndex,
+  writePersistedEntityMentionIndex,
+} from "./entity-mention-index-cache.js";
 const ENTITY_INDEX_VERSION = 3;
 const RECENT_TRANSCRIPT_LOOKBACK_HOURS = 24;
 const INSTRUCTION_LIKE_RE = /\b(always|never|must|should|remember to|do not|don't|process|workflow|template|checklist|instruction)\b/i;
@@ -64,6 +73,8 @@ type EntityMentionIndex = {
   updatedAt: string;
   entityStatusVersion?: number;
   entities: EntityMentionIndexEntry[];
+  /** In-memory only. A new canonical id had no snippets to carry. */
+  pendingSnippetReconcile?: boolean;
 };
 type EntityCandidate = {
   entry: EntityMentionIndexEntry;
@@ -356,13 +367,19 @@ async function readCurrentPersistedEntityIndex(
     return null;
   }
   const index = await readEntityIndexState(storage);
-  if (!index || index.entityStatusVersion !== storage.getMemoryStatusVersion()) {
+  if (!entityMentionPersistedIndexReadable(storage.dir) || !index || index.entityStatusVersion !== storage.getMemoryStatusVersion()) {
     return null;
   }
   return index;
 }
-const namespaceEntityIndexCache = new Map<string, EntityMentionIndex>();
-const MAX_NAMESPACE_ENTITY_INDEX_CACHE_ENTRIES = 32;
+type CarriedMemorySnippets = Map<string, { memorySnippets: string[]; memorySnippetOrigins?: (string | undefined)[] }>;
+
+function carriedMemorySnippets(index: EntityMentionIndex): CarriedMemorySnippets {
+  return new Map(index.entities.map((entry) => [entry.canonicalId, {
+    memorySnippets: entry.memorySnippets.slice(),
+    memorySnippetOrigins: entry.memorySnippetOrigins?.slice(),
+  }]));
+}
 
 function nativeEntityIndexRevision(chunks: NativeKnowledgeChunk[]): string {
   const projection = chunks.map((chunk) => [
@@ -376,40 +393,13 @@ function nativeEntityIndexRevision(chunks: NativeKnowledgeChunk[]): string {
   ]);
   return createHash("sha256").update(JSON.stringify(projection)).digest("hex");
 }
-function namespaceEntityIndexCacheKey(
-  storages: StorageManager[],
-  recallNamespaces: string[],
-  nativeRevision: string,
-): string {
-  const namespaceKey = uniqueStrings(recallNamespaces).join("\u001f");
-  const storageKey = storages
-    .map((scopedStorage) => {
-      const aliases = Object.entries(scopedStorage.entityAliases)
-        .sort(([left], [right]) => left.localeCompare(right));
-      return (
-        `${path.resolve(scopedStorage.dir)}@${scopedStorage.getMemoryStatusVersion()}` +
-        `:${scopedStorage.getMemoryCorpusVersion()}:${scopedStorage.getEntityMutationVersion()}` +
-        `:${scopedStorage.hotCacheKeyId()}:${JSON.stringify(aliases)}`
-      );
-    })
-    .join("\u001f");
-  return `${namespaceKey}\u001e${storageKey}\u001e${nativeRevision}`;
-}
-function rememberNamespaceEntityIndex(key: string, index: EntityMentionIndex): void {
-  if (namespaceEntityIndexCache.size >= MAX_NAMESPACE_ENTITY_INDEX_CACHE_ENTRIES) {
-    const oldestKey = namespaceEntityIndexCache.keys().next().value;
-    if (typeof oldestKey === "string") namespaceEntityIndexCache.delete(oldestKey);
-  }
-  namespaceEntityIndexCache.set(key, index);
-}
 
-async function writeEntityIndexState(storage: StorageManager, index: EntityMentionIndex): Promise<void> {
-  const statePath = entityIndexStatePath(storage);
-  await mkdir(path.dirname(statePath), { recursive: true });
-  const nextContent = JSON.stringify(index, null, 2) + "\n";
-  const currentContent = await readFile(statePath, "utf-8").catch(() => "");
-  if (currentContent === nextContent) return;
-  await writeFile(statePath, nextContent, "utf-8");
+async function writeEntityIndexState(
+  storage: StorageManager,
+  index: EntityMentionIndex,
+  persistGeneration: number,
+): Promise<void> {
+  await writePersistedEntityMentionIndex(storage.dir, persistGeneration, JSON.stringify(index, null, 2) + "\n");
 }
 
 function nativePseudoCanonicalId(chunk: NativeKnowledgeChunk): string {
@@ -483,6 +473,7 @@ async function buildEntityMentionIndex(
   nativeChunksOverride?: NativeKnowledgeChunk[],
   resolvedStorages?: StorageManager[],
   abortSignal?: AbortSignal,
+  carrySnippets?: CarriedMemorySnippets,
 ): Promise<EntityMentionIndex> {
   checkEntityRecallAbort(abortSignal);
   const storages = resolvedStorages ?? await resolveEntityIndexStorages(
@@ -493,11 +484,14 @@ async function buildEntityMentionIndex(
   );
   const shouldPersistIndex =
     storages.length === 1 && path.resolve(storages[0]!.dir) === path.resolve(storage.dir);
+  const persistGeneration = entityMentionCacheGeneration(storage.dir);
   const entityStatusVersionBefore = shouldPersistIndex ? storage.getMemoryStatusVersion() : undefined;
   const [previousIndex, entityFileSets, memorySets, nativeChunks] = await Promise.all([
     shouldPersistIndex ? readEntityIndexState(storage) : Promise.resolve(null),
     Promise.all(storages.map((scopedStorage) => scopedStorage.readAllEntityFiles({ abortSignal }))),
-    Promise.all(storages.map((scopedStorage) => scopedStorage.readAllMemories({ abortSignal }))),
+    carrySnippets
+      ? Promise.resolve([])
+      : Promise.all(storages.map((scopedStorage) => scopedStorage.readAllMemories({ abortSignal }))),
     nativeChunksOverride ? Promise.resolve(nativeChunksOverride) : readNativeChunks(config, recallNamespaces),
   ]);
   // The bulk reads now stop at their own scan boundaries (issue #2307); this
@@ -562,15 +556,20 @@ async function buildEntityMentionIndex(
   }
 
   scanned = 0;
-  for (const memory of memories) {
-    scanned += 1;
-    await yieldEntityRecallScanEvery(scanned, abortSignal);
-    const entry = typeof memory.frontmatter.entityRef === "string" ? entities.get(memory.frontmatter.entityRef) : undefined;
-    if (!entry) continue;
-    const snippet = await readMemorySnippet(memory);
-    if (entry.memorySnippets.includes(snippet)) continue;
-    entry.memorySnippets.push(snippet);
-    entry.memorySnippetOrigins = [...(entry.memorySnippetOrigins ?? []), memory.frontmatter.origin];
+  const pendingSnippetReconcile = carrySnippets
+    ? applyCarriedMemorySnippets(entities.values(), carrySnippets)
+    : false;
+  if (!carrySnippets) {
+    for (const memory of memories) {
+      scanned += 1;
+      await yieldEntityRecallScanEvery(scanned, abortSignal);
+      const entry = typeof memory.frontmatter.entityRef === "string" ? entities.get(memory.frontmatter.entityRef) : undefined;
+      if (!entry) continue;
+      const snippet = await readMemorySnippet(memory);
+      if (entry.memorySnippets.includes(snippet)) continue;
+      entry.memorySnippets.push(snippet);
+      entry.memorySnippetOrigins = [...(entry.memorySnippetOrigins ?? []), memory.frontmatter.origin];
+    }
   }
   // Each remaining phase is another synchronous pass over the whole index
   // (alias map, native-chunk merge, sort, two full serializations). Yield between
@@ -604,7 +603,7 @@ async function buildEntityMentionIndex(
   await yieldEntityRecallScan(abortSignal);
   const nextEntities = JSON.stringify(sortedEntities);
   const entityStatusVersionAfter = shouldPersistIndex ? storage.getMemoryStatusVersion() : undefined;
-  const canPersistIndex = shouldPersistIndex && entityStatusVersionBefore === entityStatusVersionAfter;
+  const canPersistIndex = shouldPersistIndex && entityStatusVersionBefore === entityStatusVersionAfter && persistGeneration === entityMentionCacheGeneration(storage.dir);
   const index: EntityMentionIndex = {
     version: ENTITY_INDEX_VERSION,
     updatedAt:
@@ -615,12 +614,10 @@ async function buildEntityMentionIndex(
     entities: sortedEntities,
   };
   if (canPersistIndex) {
-    // A build the caller has abandoned must not leave a persisted index behind:
-    // the write is I/O the timed-out recall no longer needs, and the next recall
-    // is already competing for the same disk.
     checkEntityRecallAbort(abortSignal);
-    await writeEntityIndexState(storage, index);
+    await writeEntityIndexState(storage, index, persistGeneration);
   }
+  if (pendingSnippetReconcile) index.pendingSnippetReconcile = true;
   return index;
 }
 
@@ -1081,30 +1078,34 @@ export async function buildEntityRecallSection(options: BuildEntityRecallSection
       options.namespaceStorage,
     )
     : undefined;
-  const namespaceCacheKey =
-    resolvedStorages && options.recallNamespaces && nativeChunks
-      ? namespaceEntityIndexCacheKey(
-        resolvedStorages,
-        options.recallNamespaces,
-        nativeEntityIndexRevision(nativeChunks),
-      )
-      : undefined;
-  let index: EntityMentionIndex | undefined = namespaceCacheKey
-    ? namespaceEntityIndexCache.get(namespaceCacheKey)
-    : undefined;
-  checkEntityRecallAbort(options.abortSignal);
-  if (!index) {
-    index = await buildEntityMentionIndex(
+  if (!nativeChunks) {
+    nativeChunks = await readNativeChunks(options.config, options.recallNamespaces);
+  }
+  const indexStorages = resolvedStorages ?? [options.storage];
+  const index = await resolveEntityMentionIndex({
+    scopeKey: entityMentionScopeKey(options.recallNamespaces, indexStorages, nativeEntityIndexRevision(nativeChunks)),
+    currentIdentity: () => entityMentionIdentity(indexStorages),
+    abortSignal: options.abortSignal,
+    buildFull: (signal) => buildEntityMentionIndex(
       options.storage,
       options.config,
       options.recallNamespaces,
       options.namespaceStorage,
       nativeChunks,
-      resolvedStorages,
-      options.abortSignal,
-    );
-    if (namespaceCacheKey) rememberNamespaceEntityIndex(namespaceCacheKey, index);
-  }
+      indexStorages,
+      signal,
+    ),
+    rebuildEntities: (previous, signal) => buildEntityMentionIndex(
+      options.storage,
+      options.config,
+      options.recallNamespaces,
+      options.namespaceStorage,
+      nativeChunks,
+      indexStorages,
+      signal,
+      carriedMemorySnippets(previous),
+    ),
+  });
   // Candidate resolution is another synchronous pass over every entity and alias,
   // reached even on a cache hit that did no I/O at all — so yield here too, or a
   // cached corpus could still hold the loop past the section budget (issue #2291).

package/src/maintenance/rebuild-memory-projection.ts

@@ -589,7 +589,7 @@ async function loadAuthoritativeProjectionSnapshot(options: {
   const storage = assertInjectedStorageRooted("rebuildMemoryProjection", options.memoryDir, options.storage) ?? new StorageManager(options.memoryDir);
   // Force a fresh disk read — projection verify/rebuild must see the true
   // on-disk state, not a potentially stale in-process cache.
-  storage.invalidateAllMemoriesCacheForDir();
+  storage.invalidateAllMemoriesCacheForDir({ indexedText: false });
   const selected = selectProjectionMemories([
     await storage.readAllMemories(),
     await storage.readAllColdMemories(),

package/src/memory-corpus-version.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
+import { entityMentionEpoch } from "./entity-mention-epoch.js";
 import { deleteInFlightReadsForDir } from "./in-flight-reads.js";
 import { invalidateDerivedAndGlobalForDir } from "./memory-cache.js";
 
@@ -17,10 +18,16 @@ export const MEMORY_CORPUS_VERSION_SENTINEL = ".memory-corpus-version.log";
  * — review approval, governance restore, migration. Appends one byte to the
  * on-disk sentinel so any process's version-keyed hot-memories cache rescans
  * on its next read (StorageManager.readSharedVersion reads the file size, so
- * the growth is observed immediately). Fail-open: a bump failure must never
- * crash the caller — a stale-cache window self-heals on the next real write.
+ * the growth is observed immediately). The same call moves the entity-mention
+ * epoch, unless the caller passes `{ indexedText: false }` for a metadata
+ * stamp that cannot change snippet text, entityRef, or origin. Fail-open: a
+ * bump failure must never crash the caller — a stale-cache window self-heals
+ * on the next real write.
  */
-export function bumpMemoryCorpusVersionForDir(memoryDir: string): void {
+export function bumpMemoryCorpusVersionForDir(
+  memoryDir: string,
+  options?: { indexedText?: boolean },
+): void {
   try {
     const stateDir = path.join(memoryDir, "state");
     mkdirSync(stateDir, { recursive: true });
@@ -28,6 +35,9 @@ export function bumpMemoryCorpusVersionForDir(memoryDir: string): void {
   } catch {
     /* fail-open: never let a cache-coherence bump crash the primary operation */
   }
+  if (options?.indexedText !== false && !entityMentionEpoch.suppressed()) {
+    entityMentionEpoch.bump(memoryDir);
+  }
   // Drop any in-flight readAllMemories scan for this dir (Cursor Medium, #1902):
   // after the sentinel advances, a concurrent read that missed the version-keyed
   // hot entry must not attach to a scan that began BEFORE this out-of-band write

package/src/preferences/preference-drift.ts

@@ -558,8 +558,10 @@ export async function runPreferenceDriftScan(
     // shared corpus version out of band — otherwise hot recall caches keep
     // serving pre-stamp frontmatter and the damping stage never sees the new
     // `driftState` (§25/§31).
-    bumpMemoryCorpusVersionForDir(storage.dir);
-    if (storage.dir !== deps.memoryDir) bumpMemoryCorpusVersionForDir(deps.memoryDir);
+    bumpMemoryCorpusVersionForDir(storage.dir, { indexedText: false });
+    if (storage.dir !== deps.memoryDir) {
+      bumpMemoryCorpusVersionForDir(deps.memoryDir, { indexedText: false });
+    }
   }
   try {
     await writeJsonFileAtomic(driftMarkerPath(deps.memoryDir), {
@@ -640,7 +642,7 @@ export async function resolvePreferenceDrift(
       { lastCorroborated: nowIso, driftState: undefined, updated: nowIso },
       { at: now, actor: DRIFT_ACTOR, reasonCode: "drift_kept", ruleVersion: DRIFT_RULE_VERSION },
     );
-    bumpMemoryCorpusVersionForDir(storage.dir);
+    bumpMemoryCorpusVersionForDir(storage.dir, { indexedText: false });
     touched();
     return { affectedIds: [preferenceId], message: `Preference ${preferenceId} confirmed still current` };
   }

package/src/procedural/library-maintenance.ts

@@ -526,9 +526,10 @@ export async function runProcedureLibraryMaintenance(options: {
   report.appliedCount = report.applied.length;
 
   if (writes > 0) {
-    // Out-of-band corpus bump + marker so hot caches and the stats surface
-    // observe the pass (§25/§31 — direct writes must not leave stale views).
-    bumpMemoryCorpusVersionForDir(options.memoryDir);
+    // Corpus bump so hot caches observe the pass. Archive already moved the
+    // mention epoch when it removed the live file. Merge-supersede and repair
+    // stamps are metadata-only, so this bump must not move the epoch.
+    bumpMemoryCorpusVersionForDir(options.memoryDir, { indexedText: false });
   }
   try {
     await writeJsonFileAtomic(maintenanceMarkerPath(options.memoryDir), {

package/src/semantic-rule-promotion.ts

@@ -610,7 +610,7 @@ export async function promoteSemanticRuleFromMemory(options: {
   };
 
   return withPromotionLock(options.memoryDir, ruleKey, async (lock) => {
-    storage.invalidateAllMemoriesCacheForDir();
+    storage.invalidateAllMemoriesCacheForDir({ indexedText: false });
     const existingRule = (await storage.readAllMemories()).find(
       (memory) =>
         memory.frontmatter.category === "rule" &&

package/src/storage/entity-mention-frontmatter-hold.ts

@@ -0,0 +1,44 @@
+import { entityMentionEpoch } from "../entity-mention-epoch.js";
+import type { MemoryFile, MemoryFrontmatter } from "../types.js";
+import {
+  buildCapturePathLockIdentity,
+  buildExplicitCaptureDedupKey,
+} from "./tombstone-blocked-capture-mutation.js";
+
+type MentionHoldStorage = {
+  withTombstoneBlockedCaptureWriteLock<T>(
+    task: () => Promise<T>,
+    identity?: readonly string[],
+  ): Promise<T>;
+  readMemoryByPath(pathname: string): Promise<MemoryFile | null>;
+};
+
+/**
+ * Metadata frontmatter writes may suppress the mention epoch only when the
+ * file still has the same body, entityRef, and origin while the path lock is
+ * held. The write runs in that same lock so a concurrent body or entityRef
+ * change cannot be overwritten under suppression.
+ */
+export async function holdMentionNeutralFrontmatter<T>(
+  storage: MentionHoldStorage,
+  memory: MemoryFile,
+  updated: MemoryFrontmatter,
+  write: () => Promise<T>,
+): Promise<T | undefined> {
+  const identities = [
+    buildCapturePathLockIdentity(memory.path),
+    buildExplicitCaptureDedupKey(memory.content, memory.frontmatter.category, memory.frontmatter.sourceConnector),
+    buildExplicitCaptureDedupKey(memory.content, updated.category, updated.sourceConnector),
+  ];
+  return storage.withTombstoneBlockedCaptureWriteLock(async () => {
+    const persisted = await storage.readMemoryByPath(memory.path);
+    if (
+      !persisted ||
+      persisted.content !== memory.content ||
+      !entityMentionEpoch.neutral(persisted.frontmatter, updated)
+    ) {
+      return undefined;
+    }
+    return write();
+  }, identities);
+}

package/src/storage.ts

@@ -87,6 +87,8 @@ import {
   deleteInFlightReadsForDir,
   clearInFlightReads,
 } from "./in-flight-reads.js";
+import { entityMentionEpoch } from "./entity-mention-epoch.js";
+import { holdMentionNeutralFrontmatter } from "./storage/entity-mention-frontmatter-hold.js";
 import * as archive from "./archive-mutation-version.js";
 import { rotateMarkdownFileToArchive } from "./hygiene.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
@@ -2419,11 +2421,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
    * Bump only — NOT invalidateAllForDir (that would drop the very hot
    * entry the write path just patched).
    */
-  protected bumpMemoryCorpusVersion(): void {
+  protected bumpMemoryCorpusVersion(opts?: { indexedText?: boolean }): void {
     this.bumpSharedVersion("memory-corpus", StorageManager.memoryCorpusVersionByDir);
-    // Drop the in-flight readAllMemories slot (#1902): a concurrent read
-    // must not attach to a scan that began BEFORE this mutation. (The patch
-    // path uses bumpMemoryCorpusVersionExclusive and clears the slot itself.)
+    if (opts?.indexedText !== false && !entityMentionEpoch.suppressed()) entityMentionEpoch.bump(this.baseDir);
     deleteInFlightReadsForDir(this.baseDir);
   }
   getArchiveMutationVersion(): number { return archive.getArchiveMutationVersionForDir(this.baseDir); }
@@ -2434,7 +2434,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
    * patchHotMemoriesCache refuse to re-key its locally patched corpus at a
    * version already reflecting a peer's still-unread concurrent append.
    */
-  private bumpMemoryCorpusVersionExclusive(): { produced: number; exclusive: boolean } {
+  private bumpMemoryCorpusVersionExclusive(opts?: { indexedText?: boolean }): { produced: number; exclusive: boolean } {
     const filePath = this.versionFilePath("memory-corpus");
     try {
       mkdirSync(this.stateDir, { recursive: true });
@@ -2447,11 +2447,13 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       appendFileSync(filePath, "x");
       const produced = statSync(filePath).size;
       StorageManager.memoryCorpusVersionByDir.set(this.baseDir, produced);
+      if (opts?.indexedText !== false && !entityMentionEpoch.suppressed()) entityMentionEpoch.bump(this.baseDir);
       // Exclusive iff exactly our single byte landed between the two stats.
       return { produced, exclusive: produced === before + 1 };
     } catch {
       const next = (StorageManager.memoryCorpusVersionByDir.get(this.baseDir) ?? 0) + 1;
       StorageManager.memoryCorpusVersionByDir.set(this.baseDir, next);
+      if (opts?.indexedText !== false && !entityMentionEpoch.suppressed()) entityMentionEpoch.bump(this.baseDir);
       return { produced: next, exclusive: true };
     }
   }
@@ -4417,8 +4419,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   /** Invalidate the readAllMemories() cache after writes that add/remove memories. */
   /** Public cache invalidation for callers that need authoritative disk reads
    *  (e.g. projection verify/rebuild). */
-  invalidateAllMemoriesCacheForDir(): void {
-    this.invalidateAllMemoriesCache();
+  invalidateAllMemoriesCacheForDir(opts?: { indexedText?: boolean }): void {
+    this.invalidateAllMemoriesCache(opts);
   }
 
   /** Invalidate only the cache layers affected by direct tier file deletes. */
@@ -4443,9 +4445,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     }
   }
 
-  /** Clear ALL static caches. Use in tests that write files directly
-   *  (bypassing StorageManager.writeMemory) to avoid stale reads. */
+  /** Clear every static cache. Direct file writes call this so the next read is not stale. */
   static clearAllStaticCaches(): void {
+    entityMentionEpoch.reset();
     clearInFlightReads();
     StorageManager.questionsCache.clear();
     StorageManager.coldMemoriesCache.clear(); // also wipe the cold-scan TTL cache
@@ -4475,12 +4477,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
    *  exclusively by invalidateColdMemoriesCache(), which is called only when
    *  cold content actually changes (hot→cold demotions, writeMemoryFileAtomic
    *  inside cold/, archiveMemory, etc.). */
-  protected invalidateAllMemoriesCache(): void {
+  protected invalidateAllMemoriesCache(opts?: { indexedText?: boolean }): void {
     deleteInFlightReadsForDir(this.baseDir);
     // Bulk/ambiguous mutations drop the hot layer wholesale (below); bump the
     // corpus sentinel too so PEER processes rescan instead of serving a warm
     // pre-mutation corpus entry (issue #1902 cross-process coherence).
-    this.bumpMemoryCorpusVersion();
+    this.bumpMemoryCorpusVersion(opts);
     // 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
@@ -5356,18 +5358,16 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       [buildCapturePathLockIdentity(expected.path), oldIdentity, newIdentity]
     );
   }
-  /**
-   * Update frontmatter fields without changing memory content. Returns false when the memory is not found.
-   */
+  /** Frontmatter patch. A replaced body still moves the mention epoch. */
+  private static readonly frontmatterBody = StorageManager.prototype.writeMemoryFrontmatter;
   async writeMemoryFrontmatter(
     memory: MemoryFile,
     patch: Partial<MemoryFrontmatter>,
-    lifecycle?: MemoryLifecycleEventWriteOptions
+    lifecycle?: MemoryLifecycleEventWriteOptions,
+    mentionReentry?: boolean
   ): Promise<boolean> {
     const beforeStatus = memory.frontmatter.status ?? "active";
-    // Canonicalize the EFFECTIVE merged entityRef (issue #2213) — an
-    // unrelated patch must not rewrite an inherited legacy ref back out.
-    // #2807: `patch.updated` is business time, persisted VERBATIM.
+    // Canonicalize merged entityRef (#2213). patch.updated is business time (#2807).
     const resolveIds = this.currentHistoricalIds();
     const updated: MemoryFrontmatter = entityRefs.canonicalizeEntityRefOption(
       { ...memory.frontmatter, ...patch },
@@ -5375,6 +5375,11 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     );
     const refIds = typeof updated.entityRef === "string" ? resolveIds : null;
     const afterStatus = updated.status ?? "active";
+    if (!mentionReentry && entityMentionEpoch.neutral(memory.frontmatter, updated)) {
+      const held = await holdMentionNeutralFrontmatter(this, memory, updated, () =>
+        entityMentionEpoch.hold(() => StorageManager.frontmatterBody.call(this, memory, patch, lifecycle, true)));
+      if (held !== undefined) return held;
+    }
 
     const fileContent = `${serializeFrontmatter(this.withOkfType(updated))}\n\n${memory.content}\n`;
     await this.writeTombstoneBlockedFrontmatter(memory, fileContent, updated, async () => {
@@ -5390,6 +5395,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         onFailRestore: memory,
       });
     }
+    if (mentionReentry && !entityMentionEpoch.neutral(memory.frontmatter, updated)) entityMentionEpoch.bump(this.baseDir);
     await this.patchHotMemoriesCache({ addedPath: memory.path });
     if (memory.path.includes(`${path.sep}cold${path.sep}`)) {
       this.invalidateColdMemoriesCache();
@@ -5422,9 +5428,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       lifecycle?.ruleVersion
     );
     if (beforeStatus !== afterStatus) {
-      // Status/lifecycle change must bump memory-status so the version-keyed
-      // entity/derived caches and peer processes observe it (issue #1902:
-      // restored — corpus bump alone doesn't cover status-derived views).
+      // Status change bumps memory-status; a corpus bump does not cover it (#1902).
       this.bumpMemoryStatusVersion();
     }
     return true;
@@ -6496,11 +6500,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     const memoryMap = new Map(memories.map((m) => [m.frontmatter.id, m]));
     const memoryPathMap = new Map(memories.map((m) => [path.resolve(m.path), m]));
     let updated = 0;
-    // Capture the corpus version + warmth BEFORE writing so we can patch the hot
-    // entries in place and then re-key them to the version this flush produces
-    // (issue #1902). Access-tracking flush is batched (consolidation / buffer
-    // full), not per-recall, so the single corpus bump below is cheap.
+    // Corpus version and warmth are snapshotted before the writes (#1902).
     const prevVersion = this.getMemoryCorpusVersion();
+    let entityRefMoved = false;
     // Snapshot the secure-store key identity once (Cursor Medium #1902), mirroring
     // readAllMemories/patchHotMemoriesCache: a mid-flush setSecureStoreKey change
     // would otherwise let loop patches or the re-keyed entry be stored under a
@@ -6540,6 +6542,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
               { onFailRestore: current }
             );
           }
+          if (!entityMentionEpoch.neutral(current.frontmatter, newFm)) entityRefMoved = true;
           return { current, newFm };
         });
         if (applied === null) continue;
@@ -6557,14 +6560,11 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     }
 
     if (updated > 0) {
-      // Advance the corpus sentinel so PEER processes rescan and don't overwrite
-      // this process's increments (Codex P2): WorkspaceOpsCoordinator computes
-      // existingCount + update.count from the cached value, so a peer serving a
-      // stale count would undercount. Re-key the locally patched entries to the
-      // produced version so this process stays warm — only when our bump was
-      // exclusive and still the current sentinel; otherwise a peer also wrote
-      // and we must let the next read rescan.
-      const { produced, exclusive } = this.bumpMemoryCorpusVersionExclusive();
+      // Advance the corpus sentinel so peers rescan (#1902). Re-key local patches
+      // only when this bump was exclusive; a peer write must rescan instead.
+      const { produced, exclusive } = this.bumpMemoryCorpusVersionExclusive({
+        indexedText: entityRefMoved ? undefined : false,
+      });
       // Drop the in-flight read slot after the bump (parity with
       // patchHotMemoriesCache, Cursor Medium #1902): a readAllMemories scan that
       // started before the flush would otherwise keep awaiting a pre-flush scan
@@ -6574,6 +6574,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       if (
         warm &&
         exclusive &&
+        !entityRefMoved &&
         produced === prevVersion + 1 &&
         this.getMemoryCorpusVersion() === produced &&
         this.hotCacheKeyId() === keyId
@@ -7010,6 +7011,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       });
       if (!written) return false;
       exactReplay = written === "exact-replay";
+      const mentionBefore = { entityRef: currentBefore.frontmatter.entityRef, origin: currentBefore.frontmatter.origin };
       if (exactReplay && typeof updatedFm.entityRef === "string") {
         await this.entityRefRepair.repair(
           currentBefore.path,
@@ -7020,6 +7022,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           { onFailRestore: currentBefore },
         );
       }
+      const mentionUnchanged = entityMentionEpoch.neutral(mentionBefore, updatedFm);
       const supersededAt = updatedFm.supersededAt ?? initialNow;
       const beforeState = this.summarizeLifecycleState(
         currentBefore.frontmatter,
@@ -7041,8 +7044,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         readMemoryByPath: (filePath) => this.readMemoryByPath(filePath),
         isColdOrArchiveTierPath: (memoryPath) => this.isColdOrArchiveTierPath(memoryPath),
         invalidateColdMemoriesCache: () => this.invalidateColdMemoriesCache(),
-        invalidateAllMemoriesCache: () => this.invalidateAllMemoriesCache(),
-        bumpMemoryCorpusVersion: () => this.bumpMemoryCorpusVersion(),
+        invalidateAllMemoriesCache: () => this.invalidateAllMemoriesCache({ indexedText: mentionUnchanged ? false : undefined }),
+        bumpMemoryCorpusVersion: () => this.bumpMemoryCorpusVersion({ indexedText: mentionUnchanged ? false : undefined }),
         appendLifecycleEvent: async () => {
           let lifecycleEvents: MemoryLifecycleEvent[] = [];
           try {
@@ -7156,9 +7159,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           return true;
         });
         if (!written) continue;
-        // Per-file corpus bump BEFORE the awaited lifecycle append (#1902):
-        // the end-of-loop status bump fires only after the whole batch.
-        this.bumpMemoryCorpusVersion();
+        // Corpus bump before the lifecycle append (#1902). Epoch moves only if repair changed entityRef or origin.
+        this.bumpMemoryCorpusVersion({ indexedText: entityMentionEpoch.neutral(currentBefore.frontmatter, updatedFm) ? false : undefined });
         await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.archiveMemories", {
           memoryId: id,
           eventType: "archived",