@remnic/core 9.69.51 → 9.69.53

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/lifecycle/seed-graduation-config-types.ts

@@ -0,0 +1,22 @@
+/**
+ * Leaf type definitions for seed graduation config (issue #2974). Kept
+ * import-free so `types.ts` can mix `SeedGraduationSettings` into
+ * `PluginConfig` without pulling the graduation implementation (and its
+ * storage.js cycle) into the types chunk — that import chain OOM'd the DTS
+ * build worker.
+ */
+
+export interface SeedGraduationConfig {
+  /** Master gate. Default false: review-mode stays the only promotion path. */
+  enabled: boolean;
+  /**
+   * Independent corroborating memories required before a seed graduates.
+   * `Infinity` is not a config value — `enabled: false` is the disabled state.
+   */
+  minCorroborations: number;
+}
+
+/** Mixed into `PluginConfig` so the nested block lives beside its parser. */
+export interface SeedGraduationSettings {
+  seedGraduation: SeedGraduationConfig;
+}

package/src/lifecycle/seed-graduation.test.ts

@@ -4,7 +4,16 @@ import { tmpdir } from "node:os";
 import * as path from "node:path";
 import { test } from "node:test";
 
+import { parseConfig } from "../config.js";
+import type { EmbeddingFallback } from "../embedding-fallback.js";
+import type { ExtractionEngine } from "../extraction.js";
+import {
+  LifecyclePolicyCoordinator,
+  type LifecyclePolicyCoordinatorDeps,
+} from "../orchestration/lifecycle-policy-coordinator.js";
+import { RecallHandleHistoryStore } from "../recall-state.js";
 import { StorageManager } from "../storage.js";
+import type { MemoryFile, MemoryFrontmatter } from "../types.js";
 import {
   SEED_GRADUATION_DEFAULTS,
   evaluateSeedGraduation,
@@ -12,7 +21,6 @@ import {
   runSeedGraduationPass,
   type SeedGraduationConfig,
 } from "./seed-graduation.js";
-import type { MemoryFile, MemoryFrontmatter } from "../types.js";
 
 const ENABLED: SeedGraduationConfig = { enabled: true, minCorroborations: 1 };
 
@@ -78,6 +86,37 @@ test("seedGraduation rejects invalid values instead of defaulting", () => {
     () => parseSeedGraduationConfig({ minCorroborations: 1.5 }),
     /minCorroborations must be an integer in \[1, 50\]/,
   );
+  assert.throws(
+    () => parseConfig({ memoryDir: "/tmp/remnic-seed-graduation-invalid", seedGraduation: "yes" }),
+    /seedGraduation must be an object/,
+  );
+});
+
+test("parseConfig wires seedGraduation; conservative pins it off", () => {
+  const memoryDir = "/tmp/remnic-seed-graduation-parse";
+  const defaults = parseConfig({ memoryDir });
+  assert.deepEqual(defaults.seedGraduation, SEED_GRADUATION_DEFAULTS);
+  assert.equal(defaults.seedGraduation.enabled, false);
+
+  const optedIn = parseConfig({
+    memoryDir,
+    seedGraduation: { enabled: true, minCorroborations: 3 },
+  });
+  assert.deepEqual(optedIn.seedGraduation, { enabled: true, minCorroborations: 3 });
+
+  assert.equal(
+    parseConfig({ memoryDir, memoryOsPreset: "conservative" }).seedGraduation.enabled,
+    false,
+    "the conservative preset pins seed graduation off",
+  );
+  assert.equal(
+    parseConfig({
+      memoryDir,
+      memoryOsPreset: "balanced",
+      seedGraduation: { enabled: true },
+    }).seedGraduation.enabled,
+    true,
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -422,3 +461,123 @@ test("pass: disabled config touches nothing", async () => {
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// Wiring — parseConfig + lifecycle policy pass
+// ---------------------------------------------------------------------------
+
+function coordinatorDeps(
+  storage: StorageManager,
+  config: ReturnType<typeof parseConfig>,
+  handleHistory?: RecallHandleHistoryStore,
+): LifecyclePolicyCoordinatorDeps {
+  return {
+    config,
+    getStorage: () => storage,
+    extraction: {} as unknown as ExtractionEngine,
+    embeddingFallback: {} as unknown as EmbeddingFallback,
+    getEffectiveLifecycleThresholds: () => ({
+      promoteHeatThreshold: 1,
+      staleDecayThreshold: 0,
+      archiveDecayThreshold: 0,
+    }),
+    async removeContentHashForMemory(): Promise<void> {},
+    async saveContentHashIndexes(): Promise<void> {},
+    getHandleHistory: handleHistory ? () => handleHistory : undefined,
+  };
+}
+
+test("lifecycle pass: gate off makes zero promoteWearableMemory calls", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    await storage.writeMemory("fact", SEED_TEXT, {
+      source: "wearable:bee",
+      status: "pending_review",
+    });
+    await storage.writeMemory("fact", RESTATE_TEXT, {
+      source: "wearable:limitless",
+    });
+    const config = parseConfig({ memoryDir: dir });
+    assert.equal(config.seedGraduation.enabled, false);
+
+    let promoteCalls = 0;
+    const original = storage.promoteWearableMemory.bind(storage);
+    storage.promoteWearableMemory = async (id, attrs, confidence) => {
+      promoteCalls += 1;
+      return original(id, attrs, confidence);
+    };
+
+    const memories = await storage.readAllMemories();
+    await new LifecyclePolicyCoordinator(coordinatorDeps(storage, config)).runLifecyclePolicyPass(
+      memories,
+      storage,
+    );
+    assert.equal(promoteCalls, 0, "disabled seed graduation must not call promoteWearableMemory");
+    const seed = (await storage.readAllMemories()).find(
+      (memory) => memory.frontmatter.source === "wearable:bee",
+    );
+    assert.equal(seed?.frontmatter.status, "pending_review");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("lifecycle pass: enabled independent corroboration promotes through the policy seam", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    await storage.writeMemory("fact", SEED_TEXT, {
+      source: "wearable:bee",
+      status: "pending_review",
+    });
+    await storage.writeMemory("fact", RESTATE_TEXT, {
+      source: "wearable:limitless",
+    });
+    const config = parseConfig({
+      memoryDir: dir,
+      seedGraduation: { enabled: true, minCorroborations: 1 },
+    });
+    const memories = await storage.readAllMemories();
+    await new LifecyclePolicyCoordinator(coordinatorDeps(storage, config)).runLifecyclePolicyPass(
+      memories,
+      storage,
+    );
+    const seed = (await storage.readAllMemories()).find(
+      (memory) => memory.frontmatter.source === "wearable:bee",
+    );
+    assert.equal(seed?.frontmatter.status, "active");
+    assert.equal(seed?.frontmatter.structuredAttributes?.graduatedBy, "independent-corroboration");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("lifecycle pass: recall-handle history suppresses echo corroboration", async () => {
+  const { storage, dir } = makeStorage();
+  try {
+    const seedWrite = await storage.writeMemory("fact", SEED_TEXT, {
+      source: "wearable:bee",
+      status: "pending_review",
+      structuredAttributes: { sessionKey: "session-a" },
+    });
+    await storage.writeMemory("fact", RESTATE_TEXT, {
+      source: "extraction",
+      structuredAttributes: { sessionKey: "session-b" },
+    });
+    const history = new RecallHandleHistoryStore(dir);
+    await history.record("session-b", [seedWrite.id]);
+    const config = parseConfig({
+      memoryDir: dir,
+      seedGraduation: { enabled: true, minCorroborations: 1 },
+    });
+    const memories = await storage.readAllMemories();
+    await new LifecyclePolicyCoordinator(
+      coordinatorDeps(storage, config, history),
+    ).runLifecyclePolicyPass(memories, storage);
+    const seed = (await storage.readAllMemories()).find(
+      (memory) => memory.frontmatter.source === "wearable:bee",
+    );
+    assert.equal(seed?.frontmatter.status, "pending_review", "quoted-back echo must not graduate");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/lifecycle/seed-graduation.ts

@@ -31,20 +31,18 @@ import { stripAttributesSuffix } from "../storage.js";
 import { STRUCTURED_ATTRIBUTE_LIMITS } from "../write-envelope.js";
 import { excludeSupportPassportPrivateMemories } from "../support-passport/card-projection.js";
 import type { MemoryFile, MemoryFrontmatter, MemoryStatus } from "../types.js";
+import type { SeedGraduationConfig } from "./seed-graduation-config-types.js";
 
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
 
-export interface SeedGraduationConfig {
-  /** Master gate. Default false: review-mode stays the only promotion path. */
-  enabled: boolean;
-  /**
-   * Independent corroborating memories required before a seed graduates.
-   * `Infinity` is not a config value — `enabled: false` is the disabled state.
-   */
-  minCorroborations: number;
-}
+// Canonical definitions live in seed-graduation-config-types.ts (a leaf) so
+// types.ts can consume them without this module's storage.js import cycle.
+export type {
+  SeedGraduationConfig,
+  SeedGraduationSettings,
+} from "./seed-graduation-config-types.js";
 
 export const SEED_GRADUATION_DEFAULTS: SeedGraduationConfig = {
   enabled: false,

package/src/orchestration/lifecycle-policy-coordinator.ts

@@ -49,6 +49,8 @@ import type {
   MemorySummary,
 } from "../types.js";
 import { excludeSupportPassportPrivateMemories } from "../support-passport/card-projection.js";
+import { runSeedGraduationPass } from "../lifecycle/seed-graduation.js";
+import type { RecallHandleHistoryStore } from "../recall-state.js";
 
 /** Dependencies injected by the orchestrator. All stable references or
  *  live accessors. */
@@ -76,6 +78,8 @@ export interface LifecyclePolicyCoordinatorDeps {
   ) => Promise<void>;
   /** Persist all dirty content-hash indexes to disk. */
   saveContentHashIndexes: () => Promise<void>;
+  /** Recall-handle ring used to suppress quoted-back echo during seed graduation. */
+  getHandleHistory?: () => RecallHandleHistoryStore;
 }
 
 /**
@@ -256,6 +260,14 @@ export class LifecyclePolicyCoordinator {
       if (wrote) updatedCount += 1;
     }
 
+    const history = this.deps.getHandleHistory?.();
+    await runSeedGraduationPass({
+      memories: allMemories,
+      storage,
+      config: this.config.seedGraduation,
+      recalledBySession: history ? (sessionKey) => history.recent(sessionKey) : undefined,
+    });
+
     // Report how many memories had frontmatter rewritten so callers can record a
     // catalog write touch for lifecycle-only passes (codex NR-tS).
     if (!lifecycleCaps.lifecycleMetrics) return updatedCount;

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}`);
+    }
+  }
+
 }