@remnic/core 9.69.52 → 9.69.53

package/src/directory-sidecars.test.ts

@@ -8,6 +8,8 @@ import { test } from "node:test";
 import {
   DIRECTORY_SIDECAR_BASENAME,
   DIRECTORY_SIDECAR_MARKER,
+  NEIGHBORHOOD_ABSTRACT_LABEL,
+  applyDirectorySidecarDrillDown,
   findDirectorySidecarsForQuery,
   loadDirectorySidecar,
   parseDirectorySidecarsEnabled,
@@ -385,3 +387,114 @@ test("write-path refresh stays inside the changed namespace and skips unrelated
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+function hit(rel: string, snippet: string, score = 1) {
+  return { path: rel, snippet, score };
+}
+
+test("drill-down is a no-op when disabled even if sidecars exist", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Telescope calibration log for the north dome.");
+    await runDirectorySidecarMaintenance(root, true);
+    const incoming = [hit("facts/2026-01-02/fact-1.md", "Telescope calibration log")];
+    const out = await applyDirectorySidecarDrillDown("/does-not-exist", "telescope", incoming, {
+      enabled: false,
+    });
+    assert.deepEqual(out, incoming);
+    assert.equal(out[0].snippet, "Telescope calibration log");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down attaches the neighborhood abstract to hits under a fresh sidecar", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Telescope calibration log for the north dome.");
+    await writeMemory(root, "facts/2026-01-02/fact-2.md", "Mirror alignment drift measured at 3 arcmin.");
+    await writeMemory(root, "entities/crew-1.md", "Catering roster for the base kitchen.");
+    await runDirectorySidecarMaintenance(root, true);
+
+    const incoming = [
+      hit("facts/2026-01-02/fact-1.md", "Telescope calibration log"),
+      hit("entities/crew-1.md", "Catering roster"),
+    ];
+    const out = await applyDirectorySidecarDrillDown(root, "telescope calibration", incoming, {
+      enabled: true,
+    });
+    assert.match(out[0].snippet, new RegExp(`^${NEIGHBORHOOD_ABSTRACT_LABEL} `));
+    assert.match(out[0].snippet, /Telescope/i);
+    assert.match(out[0].snippet, /Telescope calibration log$/m);
+    assert.equal(out[1].snippet, "Catering roster", "unrelated hit keeps its snippet");
+    assert.equal(out[0].path, incoming[0].path);
+    assert.equal(out[1].path, incoming[1].path);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down skips stale sidecars and does not write", async () => {
+  const root = store();
+  try {
+    const dayDir = path.join(root, "facts", "2026-01-02");
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Boiler pressure nominal.");
+    await runDirectorySidecarMaintenance(root, true);
+    await writeMemory(root, "facts/2026-01-02/fact-2.md", "Coolant pump replaced with spare unit.");
+    const stale = await loadDirectorySidecar(dayDir, { refresh: false });
+    assert.equal(stale?.fresh, false);
+
+    const mtimeBefore = (await stat(path.join(dayDir, DIRECTORY_SIDECAR_BASENAME))).mtimeMs;
+    const out = await applyDirectorySidecarDrillDown(
+      root,
+      "boiler",
+      [hit("facts/2026-01-02/fact-1.md", "Boiler pressure nominal.")],
+      { enabled: true },
+    );
+    assert.equal(out[0].snippet, "Boiler pressure nominal.");
+    const mtimeAfter = (await stat(path.join(dayDir, DIRECTORY_SIDECAR_BASENAME))).mtimeMs;
+    assert.equal(mtimeAfter, mtimeBefore, "retrieval must not refresh a stale sidecar");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down namespace scoping never attaches a foreign abstract", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "namespaces/alpha/facts/2026-05-01/a-1.md", "Alpha wing telescope mirror audit.");
+    await writeMemory(root, "namespaces/beta/facts/2026-05-01/b-1.md", "Beta wing telescope mirror audit.");
+    await runDirectorySidecarMaintenance(root, true);
+
+    const betaHits = [hit("namespaces/beta/facts/2026-05-01/b-1.md", "Beta wing telescope mirror audit.")];
+    const out = await applyDirectorySidecarDrillDown(root, "telescope mirror", betaHits, {
+      enabled: true,
+      namespace: "beta",
+    });
+    assert.match(out[0].snippet, new RegExp(`^${NEIGHBORHOOD_ABSTRACT_LABEL} `));
+    assert.match(out[0].snippet, /Beta wing/i);
+    assert.doesNotMatch(out[0].snippet, /Alpha wing/i);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down prefers the most specific matching directory", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Telescope calibration log for the north dome.");
+    await writeMemory(root, "facts/2026-01-03/fact-2.md", "Guide star acquisition failed twice.");
+    await runDirectorySidecarMaintenance(root, true);
+
+    const out = await applyDirectorySidecarDrillDown(
+      root,
+      "telescope calibration",
+      [hit("facts/2026-01-02/fact-1.md", "Telescope calibration log")],
+      { enabled: true },
+    );
+    assert.match(out[0].snippet, /2026-01-02/);
+    assert.doesNotMatch(out[0].snippet, /Guide star/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/directory-sidecars.ts

@@ -27,12 +27,16 @@
  * sidecar path WITHOUT the marker are user content: never overwritten, never
  * removed.
  *
- * Layer 2 (this slice): {@link refreshDirectorySidecarsAfterWrite} refreshes
- * only the changed directory and its category ancestors, so a memory write
- * populates sidecars without walking the rest of the store. `enabled: false`
- * is a proven no-op (no reads, no writes). Config parsing lives here;
- * `parseConfig` wiring, retrieval drill-down, xray, and LLM summarization
- * remain later layers on #2977 (`config.ts` is at its file-size ratchet).
+ * Layer 2: {@link refreshDirectorySidecarsAfterWrite} refreshes only the
+ * changed directory and its category ancestors. `enabled: false` is a
+ * proven no-op (no reads, no writes).
+ *
+ * Layer 3 (this slice): {@link applyDirectorySidecarDrillDown} scores
+ * fresh sidecars and attaches the winning directory's abstract to hits.
+ * `enabled` stays a function argument — not a parseConfig key (`config.ts`
+ * and `types.ts` are at their file-size ratchets). Retrieval never writes.
+ * xray trajectory, storage write-hook, parseConfig wiring, and LLM
+ * summarization remain later layers on #2977.
  */
 
 import { createHash } from "node:crypto";
@@ -47,6 +51,8 @@ import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
 
 export const DIRECTORY_SIDECAR_BASENAME = "overview.md";
 export const DIRECTORY_SIDECAR_MARKER = "<!-- remnic-directory-sidecar -->";
+/** Prefix prepended to a hit snippet when a fresh directory abstract attaches. */
+export const NEIGHBORHOOD_ABSTRACT_LABEL = "Neighborhood:";
 
 const ABSTRACT_MAX_CHARS = 256;
 const OVERVIEW_MAX_CHARS = 4000;
@@ -87,6 +93,13 @@ export interface DirectorySidecarMatch extends DirectorySidecar {
   readonly score: number;
 }
 
+/** Minimal hit shape drill-down mutates. Extra fields pass through. */
+export interface DirectorySidecarHit {
+  path: string;
+  snippet: string;
+  score: number;
+}
+
 export interface DirectorySidecarReport {
   written: string[];
   removed: string[];
@@ -435,7 +448,7 @@ export async function loadDirectorySidecar(
 export async function findDirectorySidecarsForQuery(
   memoryDir: string,
   query: string,
-  options: { namespace?: string; limit?: number } = {},
+  options: { namespace?: string; limit?: number; refresh?: boolean } = {},
 ): Promise<DirectorySidecarMatch[]> {
   const scope = options.namespace ? path.join(memoryDir, "namespaces", options.namespace) : memoryDir;
   if (!isRealDirectory(scope)) return [];
@@ -447,7 +460,7 @@ export async function findDirectorySidecarsForQuery(
   const matches: DirectorySidecarMatch[] = [];
   for (const root of scopeRoots(scope)) {
     for (const dir of collectSidecarDirs(root)) {
-      const sidecar = await loadDirectorySidecar(dir);
+      const sidecar = await loadDirectorySidecar(dir, { refresh: options.refresh });
       if (!sidecar) continue;
       const abstractLower = sidecar.abstract.toLowerCase();
       const overviewLower = sidecar.overview.toLowerCase();
@@ -466,3 +479,52 @@ export async function findDirectorySidecarsForQuery(
     .filter((candidate) => !matches.some((other) => other.dir.startsWith(`${candidate.dir}${path.sep}`)))
     .slice(0, limit);
 }
+
+function attachNeighborhoodAbstract(snippet: string, abstract: string): string {
+  const line = `${NEIGHBORHOOD_ABSTRACT_LABEL} ${abstract}`;
+  if (snippet === line || snippet.startsWith(`${line}\n`)) return snippet;
+  return snippet.length === 0 ? line : `${line}\n${snippet}`;
+}
+
+function mostSpecificSidecarForHit(
+  memoryDir: string,
+  hitPath: string,
+  matches: readonly DirectorySidecarMatch[],
+): DirectorySidecarMatch | null {
+  if (path.basename(hitPath) === DIRECTORY_SIDECAR_BASENAME) return null;
+  const abs = path.isAbsolute(hitPath) ? path.resolve(hitPath) : path.resolve(memoryDir, hitPath);
+  let best: DirectorySidecarMatch | null = null;
+  for (const match of matches) {
+    const rel = path.relative(match.dir, abs);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) continue;
+    if (best === null || match.dir.length > best.dir.length) best = match;
+  }
+  return best;
+}
+
+/**
+ * Retrieval drill-down (layer 3 of #2977): score fresh directory sidecars
+ * and attach the winning neighborhood abstract to hits under that directory.
+ * `enabled: false` (the default) returns hits unchanged with no I/O.
+ * Never writes. Does not reorder. parseConfig is not consulted.
+ */
+export async function applyDirectorySidecarDrillDown<T extends DirectorySidecarHit>(
+  memoryDir: string,
+  query: string,
+  hits: readonly T[],
+  options: { enabled?: boolean; namespace?: string } = {},
+): Promise<T[]> {
+  if (options.enabled !== true) return [...hits];
+  const matches = await findDirectorySidecarsForQuery(memoryDir, query, {
+    namespace: options.namespace,
+    refresh: false,
+  });
+  const fresh = matches.filter((match) => match.fresh && match.abstract.length > 0);
+  if (fresh.length === 0) return [...hits];
+  return hits.map((hit) => {
+    const match = mostSpecificSidecarForHit(memoryDir, hit.path, fresh);
+    if (!match) return hit;
+    const snippet = attachNeighborhoodAbstract(hit.snippet, match.abstract);
+    return snippet === hit.snippet ? hit : { ...hit, snippet };
+  });
+}

package/src/experience/session-experience-mining.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Session-end experience memories as procedure-mining input (issue #2979 layer 3).
+ *
+ * Promoted episodes (experience_* attributes, status active) join the miner
+ * record set when sessionExperience.enabled is on. Gate off: miner input is
+ * byte-identical to the trajectory-only set (no experience records).
+ * pending_review stays out.
+ */
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "../config.js";
+import type { BufferTurn, PluginConfig } from "../types.js";
+import { StorageManager } from "../storage.js";
+import {
+  filterTrajectoriesByLookbackDays,
+  readCausalTrajectoryRecords,
+  recordCausalTrajectory,
+} from "../causal-trajectory.js";
+import { runProcedureMining } from "../procedural/procedure-miner.js";
+import { runSessionExperienceExtraction } from "./session-experience.js";
+import { collectProcedureMiningRecords } from "./session-experience-mining.js";
+
+function turn(role: "user" | "assistant", content: string): BufferTurn {
+  return { role, content, timestamp: "2026-01-15T10:00:00.000Z" };
+}
+
+function successSession(): BufferTurn[] {
+  return [
+    turn("user", "Fix the failing integration test in the payments module. The test times out after 30 seconds."),
+    turn("assistant", "I will inspect the payments test file and reproduce the timeout locally first."),
+    turn("assistant", "The timeout came from an unawaited database call in the test setup. I added the missing await."),
+    turn("assistant", "Verified: the payments integration test passes now and the full suite is green."),
+  ];
+}
+
+function miningConfig(memoryDir: string, experienceEnabled: boolean): PluginConfig {
+  return parseConfig({
+    memoryDir,
+    sessionExperience: { enabled: experienceEnabled },
+    procedural: {
+      enabled: true,
+      minOccurrences: 2,
+      lookbackDays: 30,
+      successFloor: 1,
+      autoPromoteEnabled: false,
+      autoPromoteOccurrences: 10,
+    },
+  });
+}
+
+async function writePromotedExperience(
+  storage: StorageManager,
+  config: PluginConfig,
+  sessionKey: string,
+): Promise<string> {
+  const written = await runSessionExperienceExtraction({
+    turns: successSession(),
+    sessionKey,
+    config,
+    storage,
+  });
+  assert.equal(written.written, true);
+  assert.ok(written.memoryId);
+  const promoted = await storage.updateMemoryFrontmatter(written.memoryId, { status: "active" });
+  assert.equal(promoted, true);
+  return written.memoryId;
+}
+
+test("gate off: miner input is byte-identical to the trajectory-only set", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-mine-off-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    await storage.ensureDirectories();
+    const on = miningConfig(memoryDir, true);
+    await writePromotedExperience(storage, on, "session-mine-off-a");
+    await writePromotedExperience(storage, on, "session-mine-off-b");
+    await recordCausalTrajectory({
+      memoryDir,
+      record: {
+        schemaVersion: 1,
+        trajectoryId: "traj-off-1",
+        recordedAt: new Date().toISOString(),
+        sessionKey: "traj-session",
+        goal: "Ship the demo gateway to staging",
+        actionSummary: "Confirm the requirements and prepare the working plan.",
+        observationSummary: "The run produced a reusable sequence of actions.",
+        outcomeKind: "success",
+        outcomeSummary: "The workflow completed successfully with a reusable result.",
+        entityRefs: ["project-demo"],
+      },
+    });
+
+    const off = miningConfig(memoryDir, false);
+    const { trajectories } = await readCausalTrajectoryRecords({ memoryDir });
+    const nowMs = Date.now();
+    const expected = filterTrajectoriesByLookbackDays(trajectories, off.procedural.lookbackDays, nowMs);
+    const actual = await collectProcedureMiningRecords({
+      trajectories,
+      lookbackDays: off.procedural.lookbackDays,
+      storage: {
+        async readAllMemories() {
+          throw new Error("gate-off miner input must not read memories");
+        },
+      },
+      experienceEnabled: false,
+      nowMs,
+    });
+    assert.equal(JSON.stringify(actual), JSON.stringify(expected));
+    assert.equal(
+      actual.some((r) => r.trajectoryId.startsWith("experience:")),
+      false,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gate on: promoted experience memories feed the miner; pending_review does not", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-mine-on-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    await storage.ensureDirectories();
+    const config = miningConfig(memoryDir, true);
+    await writePromotedExperience(storage, config, "session-mine-on-a");
+    await writePromotedExperience(storage, config, "session-mine-on-b");
+    const pending = await runSessionExperienceExtraction({
+      turns: successSession(),
+      sessionKey: "session-mine-on-pending",
+      config,
+      storage,
+    });
+    assert.equal(pending.written, true);
+
+    const { trajectories } = await readCausalTrajectoryRecords({ memoryDir });
+    const records = await collectProcedureMiningRecords({
+      trajectories,
+      lookbackDays: config.procedural.lookbackDays,
+      storage,
+      experienceEnabled: true,
+    });
+    const experienceIds = records.filter((r) => r.trajectoryId.startsWith("experience:")).map((r) => r.trajectoryId);
+    assert.equal(experienceIds.length, 2, "only the two promoted episodes enter mining");
+    assert.ok(records.every((r) => r.goal.toLowerCase().includes("payments")));
+
+    const result = await runProcedureMining({ memoryDir, storage, config });
+    assert.equal(result.proceduresWritten, 1);
+    assert.ok((result.clustersProcessed ?? 0) >= 1);
+    const memories = await storage.readAllMemories();
+    const mined = memories.find(
+      (m) =>
+        m.frontmatter.category === "procedure" &&
+        typeof m.frontmatter.structuredAttributes?.procedure_cluster_hash === "string" &&
+        (m.frontmatter.structuredAttributes.trajectory_ids ?? "").includes("experience:"),
+    );
+    assert.ok(mined, "mined procedure must cite experience trajectory ids");
+    assert.equal(mined.frontmatter.status, "pending_review");
+    assert.equal(mined.frontmatter.structuredAttributes?.trajectory_count, "2");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gate off: two promoted experiences do not produce a mined procedure", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-mine-off-write-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    await storage.ensureDirectories();
+    const enabled = miningConfig(memoryDir, true);
+    await writePromotedExperience(storage, enabled, "session-mine-off-write-a");
+    await writePromotedExperience(storage, enabled, "session-mine-off-write-b");
+    const off = miningConfig(memoryDir, false);
+    const result = await runProcedureMining({ memoryDir, storage, config: off });
+    assert.equal(result.proceduresWritten, 0);
+    const memories = await storage.readAllMemories();
+    assert.equal(
+      memories.filter((m) => m.frontmatter.structuredAttributes?.procedure_cluster_hash !== undefined).length,
+      0,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/experience/session-experience-mining.ts

@@ -0,0 +1,90 @@
+/**
+ * Session-experience mining helpers (issue #2979 layer 3).
+ *
+ * Promoted experience memories are `category: procedure` with
+ * `experience_*` attributes. When `sessionExperience.enabled` is true they
+ * join the procedure-miner record set as pre-structured trajectories.
+ * Call `collectProcedureMiningRecords` with `experienceEnabled: false` for
+ * the gate-off path — that branch must not read storage and must return
+ * the trajectory lookback set unchanged.
+ */
+import {
+  filterTrajectoriesByLookbackDays,
+  type CausalTrajectoryRecord,
+} from "../causal-trajectory.js";
+import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import type { ObjectiveStateOutcome } from "../objective-state.js";
+import type { MemoryFile } from "../types.js";
+import { isSessionExperienceMemory } from "./session-experience-recall.js";
+
+export interface ExperienceMiningStorage {
+  readAllMemories(): Promise<MemoryFile[]>;
+}
+
+export interface CollectProcedureMiningRecordsOptions {
+  trajectories: CausalTrajectoryRecord[];
+  lookbackDays: number;
+  storage: ExperienceMiningStorage;
+  experienceEnabled: boolean;
+  nowMs?: number;
+}
+
+function mapExperienceOutcome(raw: string | undefined): ObjectiveStateOutcome {
+  if (raw === "success" || raw === "failure" || raw === "partial") return raw;
+  return "unknown";
+}
+
+/** Convert one promoted episode into a mining record, or `null`. */
+export function experienceMemoryToMiningRecord(memory: MemoryFile): CausalTrajectoryRecord | null {
+  if (!isSessionExperienceMemory(memory)) return null;
+  if (!isActiveMemoryStatus(memory.frontmatter.status)) return null;
+  const attrs = memory.frontmatter.structuredAttributes ?? {};
+  const situation = (attrs.experience_situation ?? "").trim();
+  const hash = attrs.experience_session_hash;
+  if (situation.length === 0 || typeof hash !== "string" || hash.length === 0) return null;
+  const recordedAt = memory.frontmatter.created;
+  if (!recordedAt || !Number.isFinite(Date.parse(recordedAt))) return null;
+  const approach = (attrs.experience_approach ?? "").trim();
+  const reflection = (attrs.experience_reflection ?? "").trim();
+  const record: CausalTrajectoryRecord = {
+    schemaVersion: 1,
+    trajectoryId: `experience:${hash}`,
+    recordedAt,
+    sessionKey: hash,
+    goal: situation,
+    actionSummary: approach,
+    observationSummary: reflection,
+    outcomeKind: mapExperienceOutcome(attrs.experience_outcome),
+    outcomeSummary: reflection,
+  };
+  if (typeof memory.frontmatter.entityRef === "string" && memory.frontmatter.entityRef.trim().length > 0) {
+    record.entityRefs = [memory.frontmatter.entityRef.trim()];
+  }
+  return record;
+}
+
+export async function collectExperienceMiningRecords(
+  storage: ExperienceMiningStorage,
+): Promise<CausalTrajectoryRecord[]> {
+  const memories = await storage.readAllMemories();
+  const out: CausalTrajectoryRecord[] = [];
+  for (const memory of memories) {
+    const record = experienceMemoryToMiningRecord(memory);
+    if (record) out.push(record);
+  }
+  return out;
+}
+
+/**
+ * Records the miner will cluster. Gate off returns the lookback-filtered
+ * trajectories only and does not call storage.
+ */
+export async function collectProcedureMiningRecords(
+  options: CollectProcedureMiningRecordsOptions,
+): Promise<CausalTrajectoryRecord[]> {
+  const source =
+    options.experienceEnabled === true
+      ? options.trajectories.concat(await collectExperienceMiningRecords(options.storage))
+      : options.trajectories;
+  return filterTrajectoriesByLookbackDays(source, options.lookbackDays, options.nowMs);
+}

package/src/orchestration/persistence-index.ts

@@ -7,6 +7,7 @@
  *   - content-hash dedup index add/has/remove/save
  *   - temporal-bounds backfill on dedup hits (bitemporal, #1578)
  *   - temporal tag index updates and persisted-memory indexing
+ *   - recognition-index write-path maintenance when recallRecognitionTier is on
  *   - graph edge construction for newly persisted memories
  *   - semantic dedup candidate lookup
  *
@@ -22,7 +23,9 @@ import { GraphIndex, type GraphEdge } from "../graph.js";
 import { ContentHashIndex, StorageManager } from "../index.js";
 import { log } from "../logger.js";
 import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { loadRecognitionIndex } from "../recall-recognition-tier.js";
 import { stripCitationForTemplate } from "../source-attribution.js";
+import { maintainRecognitionIndexAfterWrite, type RecognitionIndexChange } from "./recall-recognition-index.js";
 import { clearIndexesAsync, indexesExistAsync } from "../temporal-index.js";
 import { indexMemoriesBatchAsync } from "../temporal-index-batch.js";
 import { normalizeSupersessionKey } from "../temporal-supersession.js";
@@ -447,6 +450,9 @@ export class PersistenceIndexCoordinator {
     storage: StorageManager,
     persistedIds: string[],
   ): Promise<void> {
+    // Recognition-index write-path (issue #2975): independent of temporal
+    // capability gates. Off-path is zero index I/O and cannot block persist.
+    await this.maintainRecognitionIndex(storage, persistedIds);
     const caps = resolveCapabilities(this.deps.config); // #1566 Cluster C
     // Build temporal/tag indexes whenever either consumer is enabled:
     // - queryAwareIndexingEnabled: uses indexes for query-aware prefiltering in recall
@@ -625,4 +631,48 @@ export class PersistenceIndexCoordinator {
     );
     return enriched;
   }
+  /**
+   * Upsert persisted memories into the namespace recognition index.
+   * `recallRecognitionTier !== true` returns before any index I/O.
+   * A missing index is bootstrapped from the active corpus so the first
+   * post-enable write cannot publish a partial index that recall would
+   * treat as the full working set.
+   */
+  private async maintainRecognitionIndex(
+    storage: StorageManager,
+    persistedIds: string[],
+  ): Promise<void> {
+    try {
+      if (this.deps.config.recallRecognitionTier !== true) return;
+      const indexMissing = (await loadRecognitionIndex(storage.dir)) === null;
+      if (!indexMissing && persistedIds.length === 0) return;
+      const changes: RecognitionIndexChange[] = [];
+      const pushUpsert = (memory: MemoryFile): void => {
+        if (!isActiveMemoryStatus(memory.frontmatter.status)) return;
+        const memoryId = memory.frontmatter.id;
+        if (typeof memoryId !== "string" || memoryId.trim().length === 0) return;
+        changes.push({ action: "upsert", id: memoryId, content: memory.content ?? "" });
+      };
+      if (indexMissing) {
+        const corpus = await storage.readAllMemories().catch(() => []);
+        for (const memory of corpus) pushUpsert(memory);
+      }
+      for (const id of persistedIds) {
+        let memory = await storage.getMemoryById(id);
+        if (!memory) {
+          const cold = await storage.getMemoryByIdIncludingArchived(id).catch(() => null);
+          if (cold && isActiveMemoryStatus(cold.frontmatter.status)) memory = cold;
+        }
+        if (memory) pushUpsert(memory);
+      }
+      await maintainRecognitionIndexAfterWrite({
+        memoryDir: storage.dir,
+        enabled: true,
+        changes,
+      });
+    } catch (err) {
+      log.debug(`recognition-index update error (non-fatal): ${err}`);
+    }
+  }
+
 }