@remnic/core 9.45.5 → 9.46.0

package/src/orchestration/recall-search-prefilter.ts

@@ -0,0 +1,254 @@
+import path from "node:path";
+import { resolveIndexingCapabilities, resolveMemoryLifecycleCapabilities } from "../capabilities.js";
+import type { EmbeddingFallback } from "../embedding-fallback.js";
+import type { StorageManager } from "../index.js";
+import type { NamespaceStorageRouter } from "../namespaces/storage.js";
+import {
+  computeArtifactCandidateFetchLimit,
+  throwIfRecallAborted,
+  type QueryAwarePrefilter,
+} from "../orchestrator.js";
+import {
+  extractTagsFromPrompt,
+  isTemporalQuery,
+  queryByDateRangeAsync,
+  readIndexSnapshotAsync,
+  recencyWindowFromPrompt,
+  resolvePromptTagPrefilterAsync,
+} from "../temporal-index.js";
+import type { MemoryFile, PluginConfig, QmdSearchResult } from "../types.js";
+import { isGenericRecallExcludedPath } from "./generic-recall-paths.js";
+
+export interface PrefilterAndArtifactDeps {
+  readonly config: PluginConfig;
+  readonly storageRouter: NamespaceStorageRouter;
+  readonly storage: StorageManager;
+  readonly embeddingFallback: EmbeddingFallback;
+  resolveArtifactSourceStatuses(
+    storage: StorageManager,
+    sourceIds: string[],
+  ): Promise<Map<string, "active" | "superseded" | "archived" | "missing">>;
+  scopeQueryAwarePaths(
+    paths: Set<string> | null,
+    recallNamespaces: string[],
+  ): Set<string> | null;
+  searchScopedMemoryCandidates(
+    candidatePaths: Set<string>,
+    query: string,
+    limit: number,
+    options?: {
+      allowArchived?: boolean;
+    },
+  ): Promise<QmdSearchResult[]>;
+}
+
+export async function fetchActiveArtifactsForNamespace(
+  deps: Pick<PrefilterAndArtifactDeps, "storageRouter" | "resolveArtifactSourceStatuses">,
+  namespace: string,
+  prompt: string,
+  targetCount: number,
+): Promise<MemoryFile[]> {
+  const storage = await deps.storageRouter.storageFor(namespace);
+  let fetchLimit = computeArtifactCandidateFetchLimit(targetCount);
+  const maxFetchLimit = Math.min(800, Math.max(fetchLimit, targetCount * 8));
+  const MAX_ATTEMPTS = 4;
+  let bestFiltered: MemoryFile[] = [];
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    const rawResults = await storage.searchArtifacts(prompt, fetchLimit);
+    const sourceIds = Array.from(
+      new Set(
+        rawResults
+          .map((a) => a.frontmatter.sourceMemoryId)
+          .filter(
+            (id): id is string => typeof id === "string" && id.length > 0,
+          ),
+      ),
+    );
+    const sourceStatus =
+      sourceIds.length > 0
+        ? await deps.resolveArtifactSourceStatuses(storage, sourceIds)
+        : new Map<string, "active" | "superseded" | "archived" | "missing">();
+
+    const filtered: MemoryFile[] = [];
+    for (const artifact of rawResults) {
+      const sourceId = artifact.frontmatter.sourceMemoryId;
+      if (!sourceId) {
+        filtered.push(artifact);
+        if (filtered.length >= targetCount) break;
+        continue;
+      }
+      const status = sourceStatus.get(sourceId) ?? "missing";
+      if (status !== "active") continue;
+      filtered.push(artifact);
+      if (filtered.length >= targetCount) break;
+    }
+
+    if (filtered.length >= targetCount) return filtered.slice(0, targetCount);
+    if (filtered.length > bestFiltered.length) {
+      bestFiltered = filtered;
+    }
+    if (rawResults.length === 0) return filtered;
+    if (rawResults.length < fetchLimit && filtered.length > 0)
+      return filtered;
+    if (fetchLimit >= maxFetchLimit) return filtered;
+
+    const growth = Math.max(targetCount * 2, 12);
+    fetchLimit = Math.min(maxFetchLimit, fetchLimit + growth);
+  }
+
+  return bestFiltered;
+}
+
+export async function buildQueryAwarePrefilter(
+  deps: Pick<PrefilterAndArtifactDeps, "config" | "scopeQueryAwarePaths">,
+  prompt: string,
+  recallNamespaces: string[],
+): Promise<QueryAwarePrefilter> {
+  if (!resolveIndexingCapabilities(deps.config).queryAwareIndexing || !prompt.trim()) {
+    return {
+      candidatePaths: null,
+      temporalFromDate: null,
+      matchedTags: [],
+      expandedTags: [],
+      combination: "none",
+      filteredToFullSearch: false,
+    };
+  }
+
+  const temporalFromDate = isTemporalQuery(prompt)
+    ? recencyWindowFromPrompt(prompt, Date.now())
+    : null;
+  // Read the temporal + tag prefilter indexes as ONE consistent snapshot
+  // (issue #1911, Codex Medium) so a concurrent async index mutation can't be
+  // observed half-applied (new temporal row, tag membership not yet written),
+  // which would drop the current memory from the tag prefilter.
+  const [rawTemporal, tagSignals] = await readIndexSnapshotAsync(
+    deps.config.memoryDir,
+    () =>
+      Promise.all([
+        temporalFromDate
+          ? queryByDateRangeAsync(deps.config.memoryDir, temporalFromDate)
+          : Promise.resolve<Set<string> | null>(null),
+        resolvePromptTagPrefilterAsync(deps.config.memoryDir, prompt).catch(
+          () => ({
+            matchedTags: extractTagsFromPrompt(prompt),
+            expandedTags: extractTagsFromPrompt(prompt),
+            paths: null,
+          }),
+        ),
+      ]),
+  );
+
+  const temporalCandidates = deps.scopeQueryAwarePaths(
+    rawTemporal,
+    recallNamespaces,
+  );
+  const tagCandidates = deps.scopeQueryAwarePaths(
+    tagSignals.paths,
+    recallNamespaces,
+  );
+  const maxCandidates = deps.config.queryAwareIndexingMaxCandidates;
+
+  let candidatePaths: Set<string> | null = null;
+  let combination: QueryAwarePrefilter["combination"] = "none";
+  let filteredToFullSearch = false;
+
+  if (
+    tagSignals.matchedTags.length > 0 &&
+    tagCandidates !== null &&
+    tagCandidates.size === 0
+  ) {
+    candidatePaths = tagCandidates;
+    combination = "tag";
+  } else if (temporalCandidates !== null && tagCandidates !== null) {
+    const intersection = new Set(
+      Array.from(temporalCandidates).filter((memoryPath) =>
+        tagCandidates.has(memoryPath),
+      ),
+    );
+    if (intersection.size > 0) {
+      candidatePaths = intersection;
+      combination = "intersection";
+    } else {
+      candidatePaths = new Set([...temporalCandidates, ...tagCandidates]);
+      combination = "union";
+    }
+  } else if (temporalCandidates !== null) {
+    candidatePaths = temporalCandidates;
+    combination = "temporal";
+  } else if (tagCandidates !== null) {
+    candidatePaths = tagCandidates;
+    combination = "tag";
+  }
+
+  if (
+    candidatePaths &&
+    maxCandidates > 0 &&
+    candidatePaths.size > maxCandidates
+  ) {
+    filteredToFullSearch = true;
+    candidatePaths = null;
+  }
+
+  return {
+    candidatePaths,
+    temporalFromDate,
+    matchedTags: tagSignals.matchedTags,
+    expandedTags: tagSignals.expandedTags,
+    combination,
+    filteredToFullSearch,
+  };
+}
+
+export async function searchEmbeddingFallback(
+  deps: Pick<PrefilterAndArtifactDeps, "config" | "embeddingFallback" | "storage">,
+  query: string,
+  limit: number,
+): Promise<QmdSearchResult[]> {
+  if (!resolveMemoryLifecycleCapabilities(deps.config).embeddingFallback) return [];
+  if (!(await deps.embeddingFallback.isAvailable())) return [];
+  const hits = await deps.embeddingFallback.search(query, limit);
+  if (hits.length === 0) return [];
+
+  const results: QmdSearchResult[] = [];
+  for (const hit of hits) {
+    const fullPath = path.isAbsolute(hit.path)
+      ? hit.path
+      : path.join(deps.config.memoryDir, hit.path);
+    const memory = await deps.storage.readMemoryByPath(fullPath);
+    if (!memory) continue;
+    results.push({
+      docid: hit.id,
+      path: fullPath,
+      score: hit.score,
+      snippet: memory.content.slice(0, 400).replace(/\n/g, " "),
+    });
+  }
+  return results;
+}
+
+export async function searchQueryAwareFallback(
+  deps: Pick<PrefilterAndArtifactDeps, "config" | "searchScopedMemoryCandidates">,
+  prompt: string,
+  limit: number,
+  queryAwarePrefilter?: QueryAwarePrefilter,
+  abortSignal?: AbortSignal,
+): Promise<QmdSearchResult[]> {
+  throwIfRecallAborted(abortSignal);
+  const cappedLimit = Math.max(0, limit);
+  if (cappedLimit === 0 || queryAwarePrefilter?.candidatePaths?.size === 0) return [];
+
+  const candidatePaths = queryAwarePrefilter?.candidatePaths;
+  const scopedSeedResults = (
+    candidatePaths?.size
+      ? await deps.searchScopedMemoryCandidates(
+          candidatePaths,
+          prompt,
+          candidatePaths.size,
+          { allowArchived: true },
+        )
+      : []
+  ).filter((result) => !isGenericRecallExcludedPath(result.path, deps.config, "qmd"));
+  return scopedSeedResults.slice(0, cappedLimit);
+}

package/src/orchestration/session-context.ts

@@ -306,7 +306,7 @@ export class SessionContextCoordinator {
    * Register a peer ID for a session so recall can inject the peer's
    * profile into context (issue #679 PR 3/5). Pass `null` to clear.
    *
-   * Connectors and the `before_agent_start` hook call this when the
+   * Connectors and the `before_prompt_build` hook call this when the
    * session's counter-party is known. The ID is validated against
    * `PEER_ID_PATTERN` before storing.
    *

package/src/orchestrator.ts

@@ -656,7 +656,7 @@ export class Orchestrator {
 
   /**
    * Per-session workspace selections keyed by sessionKey.
-   * Set by the before_agent_start hook so recall() uses the correct
+   * Set by the before_prompt_build hook so recall() uses the correct
    * agent workspace for BOOT.md injection. Cleared after each recall.
    * Using a Map prevents concurrent sessions from overwriting each other.
    */

package/src/sdk-compat.ts

@@ -64,10 +64,8 @@ export function detectSdkCapabilities(api: Record<string, unknown>): SdkCapabili
   //   - registerMemoryCapability   (capability-based SDKs, ≥2026.4.5; the
   //     deprecated registerMemoryPromptSection may be absent)
   //   - registrationMode           (explicit registration lifecycle signal)
-  // Just having runtime.version is NOT sufficient — some legacy builds
-  // expose it. Omitting registerMemoryCapability here would cause the
-  // legacy before_agent_start hook to be registered on new SDKs that only
-  // expose registerMemoryCapability, silently breaking memory injection.
+  // Runtime version alone is not authoritative because some transitional
+  // builds expose it without the modern prompt-hook surfaces.
   const hasNewHookSystem =
     hasRegisterMemoryPromptSection || hasRegisterMemoryCapability || hasRegistrationMode;
 

package/src/source-agent-qualifier.ts

@@ -48,6 +48,9 @@ export interface ExtractionGroundingContext {
   roleAssertionSources?: ExtractionGroundingRoleSources;
   messageTimestamp: Date | undefined;
   sourceConnector?: string;
+  /** Input came from an always-on recorder (issue #2294); the proactive
+   *  second pass reads it so its prompts carry the same media warning. */
+  ambientCapture?: boolean;
   scopeClassificationEnabled?: boolean;
 }
 

package/src/testing/subjects/recall-profile-storage.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Recall-profile-storage contract lifecycle subject for the scenario-matrix harness.
+ * Exercises resolveCompositeProfileStorage across single-storage pass-through,
+ * empty storage fallback, multi-storage precedence, and aggregation deduplication.
+ */
+
+import assert from "node:assert/strict";
+import path from "node:path";
+
+import {
+  type CompositeProfileStorageResult,
+  resolveCompositeProfileStorage,
+} from "../../orchestration/recall-profile-storage.js";
+import { StorageManager } from "../../storage.js";
+import { type LifecycleSubject, type MatrixRow, runLifecycleMatrix } from "../lifecycle-matrix.js";
+import { cleanupDir, mkTempMemoryDir } from "../orchestrator-lite.js";
+
+interface RecallProfileStorageState {
+  readonly memoryDir: string;
+  readonly storages: StorageManager[];
+  readonly extraDirs: string[];
+  result?: CompositeProfileStorageResult;
+  readProfileResult?: string;
+  readQuestionsResult?: unknown[];
+  readIdentityAnchorResult?: string | null;
+  readIdentityImprovementLoopsResult?: string | null;
+  readContinuityIncidentsResult?: unknown[];
+  listEntityNamesResult?: string[];
+  readEntityResult?: unknown;
+  readMemoryByPathResult?: unknown;
+  readAllMemoriesResult?: unknown[];
+}
+
+const subject: LifecycleSubject<RecallProfileStorageState> = {
+  appliesTo(row: MatrixRow): boolean | string {
+    if (row.id === "compaction-flush") {
+      return "profile storage proxying has no compaction flush behavior; compaction operates on transcripts";
+    }
+    if (row.id === "before-reset") {
+      return "profile storage proxying has no before_reset lifecycle hook; reset operates on session state";
+    }
+    return true;
+  },
+
+  async setup(row: MatrixRow): Promise<RecallProfileStorageState> {
+    const memoryDir = await mkTempMemoryDir(`recall-profile-storage-${row.id}`);
+    const extraDirs: string[] = [];
+
+    try {
+      if (row.id === "sparse-metadata-without-binding") {
+        return { memoryDir, storages: [], extraDirs };
+      }
+
+      if (row.id === "sparse-metadata-with-binding") {
+        const s1 = new StorageManager(memoryDir);
+        await s1.writeProfile("# Single Profile\n- Fact 1");
+        return { memoryDir, storages: [s1], extraDirs };
+      }
+
+      if (row.id === "explicit-provider-identity") {
+        const dir2 = await mkTempMemoryDir(`recall-profile-storage-${row.id}-2`);
+        extraDirs.push(dir2);
+        const dir3 = await mkTempMemoryDir(`recall-profile-storage-${row.id}-3`);
+        extraDirs.push(dir3);
+
+        const s1 = new StorageManager(memoryDir);
+        const s2 = new StorageManager(dir2);
+        const s3 = new StorageManager(dir3);
+
+        await s1.writeEntity("Alice", "person", ["Alice works on Remnic"]);
+
+        await s2.writeProfile("# Profile 2\n- User prefers TypeScript");
+        await s2.writeIdentityAnchor("# Identity Anchor 2\n- Value: Integrity");
+        await s2.writeEntity("Bob", "person", ["Bob works on Remnic"]);
+
+        await s3.writeProfile("# Profile 3\n- User prefers Rust");
+        await s3.writeIdentityAnchor("# Identity Anchor 3\n- Value: Speed");
+
+        return { memoryDir, storages: [s1, s2, s3], extraDirs };
+      }
+
+      if (row.id === "provider-rebinding") {
+        const dir2 = await mkTempMemoryDir(`recall-profile-storage-${row.id}-2`);
+        extraDirs.push(dir2);
+
+        const s1 = new StorageManager(memoryDir);
+        const s2 = new StorageManager(memoryDir);
+        const s3 = new StorageManager(dir2);
+        const s4 = { dir: "" } as unknown as StorageManager;
+
+        return { memoryDir, storages: [s1, s2, s3, s4], extraDirs };
+      }
+
+      if (row.id === "restart-reload-recovery") {
+        const dir2 = await mkTempMemoryDir(`recall-profile-storage-${row.id}-2`);
+        extraDirs.push(dir2);
+
+        const s1Seed = new StorageManager(memoryDir);
+        const s2Seed = new StorageManager(dir2);
+        await s2Seed.writeProfile("# Recovered Profile\n- Persisted value");
+        await s2Seed.writeIdentityAnchor("# Recovered Anchor\n- Persisted anchor");
+
+        const seedResult = resolveCompositeProfileStorage({
+          profileStorages: [s1Seed, s2Seed],
+          memoryDir,
+        });
+        const seedProfile = await seedResult.profileStorage.readProfile();
+        assert.ok(seedProfile.includes("Recovered Profile"));
+
+        const s1Recovered = new StorageManager(memoryDir);
+        const s2Recovered = new StorageManager(dir2);
+
+        return { memoryDir, storages: [s1Recovered, s2Recovered], extraDirs };
+      }
+
+      if (row.id === "session-end") {
+        const dir2 = await mkTempMemoryDir(`recall-profile-storage-${row.id}-2`);
+        extraDirs.push(dir2);
+
+        const s1 = new StorageManager(memoryDir);
+        const s2 = new StorageManager(dir2);
+
+        await s2.writeProfile("# Final Session Profile\n- Summary");
+
+        return { memoryDir, storages: [s1, s2], extraDirs };
+      }
+
+      if (row.id === "dedupe-replay") {
+        const dir2 = await mkTempMemoryDir(`recall-profile-storage-${row.id}-2`);
+        extraDirs.push(dir2);
+
+        const s1 = new StorageManager(memoryDir);
+        const s2 = new StorageManager(memoryDir);
+        const s3 = new StorageManager(dir2);
+
+        await s1.writeQuestion("What is Remnic?", "context 1", 5);
+        await s1.writeQuestion("How does recall work?", "context 2", 10);
+        await s1.appendContinuityIncident({
+          symptom: "Incident 1 symptom",
+          suspectedCause: "Cause 1",
+          triggerWindow: "2026-08-01",
+        });
+        await s1.writeIdentityImprovementLoops("# Improvement Loop A");
+        await s1.writeEntity("ProjectX", "project", ["Fact X1"]);
+        await s1.writeMemory("fact", "Memory fact 1");
+
+        await s3.writeQuestion("Where are memories saved?", "context 3", 1);
+        await s3.appendContinuityIncident({
+          symptom: "Incident 2 symptom",
+          suspectedCause: "Cause 2",
+          triggerWindow: "2026-08-01",
+        });
+        await s3.writeIdentityImprovementLoops("# Improvement Loop B");
+        await s3.writeEntity("ProjectY", "project", ["Fact Y1"]);
+        await s3.writeMemory("fact", "Memory fact 2");
+
+        return { memoryDir, storages: [s1, s2, s3], extraDirs };
+      }
+
+      return { memoryDir, storages: [], extraDirs };
+    } catch (error) {
+      await cleanupDir(memoryDir);
+      for (const dir of extraDirs) {
+        await cleanupDir(dir);
+      }
+      throw error;
+    }
+  },
+
+  async exercise(state: RecallProfileStorageState, row: MatrixRow): Promise<void> {
+    const result = resolveCompositeProfileStorage({
+      profileStorages: state.storages,
+      memoryDir: state.memoryDir,
+    });
+    state.result = result;
+
+    const storage = result.profileStorage;
+
+    if (row.id === "sparse-metadata-without-binding") {
+      state.readProfileResult = await storage.readProfile();
+      state.readQuestionsResult = await storage.readQuestions();
+      state.readIdentityAnchorResult = await storage.readIdentityAnchor();
+      state.readIdentityImprovementLoopsResult = await storage.readIdentityImprovementLoops();
+      state.readContinuityIncidentsResult = await storage.readContinuityIncidents();
+      state.listEntityNamesResult = await storage.listEntityNames();
+      state.readEntityResult = await storage.readEntity("Alice");
+      state.readMemoryByPathResult = await storage.readMemoryByPath("fact/1.md");
+      state.readAllMemoriesResult = await storage.readAllMemories();
+      return;
+    }
+
+    if (row.id === "sparse-metadata-with-binding") {
+      state.readProfileResult = await storage.readProfile();
+      return;
+    }
+
+    if (row.id === "explicit-provider-identity") {
+      state.readProfileResult = await storage.readProfile();
+      state.readIdentityAnchorResult = await storage.readIdentityAnchor();
+      state.readEntityResult = await storage.readEntity("person-bob");
+      state.readMemoryByPathResult = await storage.readMemoryByPath("nonexistent.md");
+      return;
+    }
+
+    if (row.id === "restart-reload-recovery") {
+      state.readProfileResult = await storage.readProfile();
+      state.readIdentityAnchorResult = await storage.readIdentityAnchor();
+      return;
+    }
+
+    if (row.id === "session-end") {
+      state.readProfileResult = await storage.readProfile();
+      return;
+    }
+
+    if (row.id === "dedupe-replay") {
+      state.readQuestionsResult = await storage.readQuestions();
+      state.readIdentityImprovementLoopsResult = await storage.readIdentityImprovementLoops();
+      state.readContinuityIncidentsResult = await storage.readContinuityIncidents(10);
+      state.listEntityNamesResult = await storage.listEntityNames();
+      state.readAllMemoriesResult = await storage.readAllMemories();
+      return;
+    }
+  },
+
+  async invariants(state: RecallProfileStorageState, row: MatrixRow): Promise<void> {
+    assert.ok(state.result, "composite profile storage result was populated");
+
+    if (row.id === "sparse-metadata-without-binding") {
+      assert.equal(state.result.profileStorageDirs.length, 0, "empty storage list returns empty storage dirs");
+      assert.equal(
+        state.result.profileStorage.dir,
+        path.join(state.memoryDir, ".empty-scope-profile"),
+        "empty storage fallback has .empty-scope-profile dir"
+      );
+      assert.equal(state.readProfileResult, "", "empty storage readProfile returns empty string");
+      assert.deepEqual(state.readQuestionsResult, [], "empty storage readQuestions returns empty array");
+      assert.equal(state.readIdentityAnchorResult, "", "empty storage readIdentityAnchor returns empty string");
+      assert.equal(
+        state.readIdentityImprovementLoopsResult,
+        "",
+        "empty storage readIdentityImprovementLoops returns empty string"
+      );
+      assert.deepEqual(
+        state.readContinuityIncidentsResult,
+        [],
+        "empty storage readContinuityIncidents returns empty array"
+      );
+      assert.deepEqual(state.listEntityNamesResult, [], "empty storage listEntityNames returns empty array");
+      assert.equal(state.readEntityResult, null, "empty storage readEntity returns null");
+      assert.equal(state.readMemoryByPathResult, null, "empty storage readMemoryByPath returns null");
+      assert.deepEqual(state.readAllMemoriesResult, [], "empty storage readAllMemories returns empty array");
+      return;
+    }
+
+    if (row.id === "sparse-metadata-with-binding") {
+      assert.strictEqual(
+        state.result.profileStorage,
+        state.storages[0],
+        "single storage pass-through returns unproxied target instance"
+      );
+      assert.deepEqual(
+        state.result.profileStorageDirs,
+        [state.memoryDir],
+        "single storage pass-through returns target storage directory"
+      );
+      assert.ok(
+        state.readProfileResult?.includes("Single Profile"),
+        "single storage readProfile delegates to target storage"
+      );
+      return;
+    }
+
+    if (row.id === "explicit-provider-identity") {
+      assert.ok(
+        state.readProfileResult?.includes("Profile 2"),
+        "readProfile returns first non-empty profile in composite order"
+      );
+      assert.ok(
+        state.readIdentityAnchorResult?.includes("Identity Anchor 2"),
+        "readIdentityAnchor returns first non-empty anchor in composite order"
+      );
+      assert.ok(typeof state.readEntityResult === "string", "readEntity returns raw entity string");
+      assert.ok(
+        (state.readEntityResult as string).includes("Bob"),
+        "readEntity returns entity content from matching storage"
+      );
+      assert.equal(state.readMemoryByPathResult, null, "readMemoryByPath returns null when absent in all storages");
+      return;
+    }
+
+    if (row.id === "provider-rebinding") {
+      assert.deepEqual(
+        state.result.profileStorageDirs,
+        [state.memoryDir, state.extraDirs[0]],
+        "profileStorageDirs deduplicates directories and filters out empty strings"
+      );
+      return;
+    }
+
+    if (row.id === "restart-reload-recovery") {
+      assert.ok(
+        state.readProfileResult?.includes("Recovered Profile"),
+        "composite profile storage recovers state over fresh instances after restart"
+      );
+      assert.ok(
+        state.readIdentityAnchorResult?.includes("Recovered Anchor"),
+        "composite identity anchor recovers state over fresh instances after restart"
+      );
+      return;
+    }
+
+    if (row.id === "session-end") {
+      assert.ok(
+        state.readProfileResult?.includes("Final Session Profile"),
+        "session-end readProfile correctly falls back past blank profile to non-empty profile"
+      );
+      return;
+    }
+
+    if (row.id === "dedupe-replay") {
+      const questions = state.readQuestionsResult;
+      assert.ok(Array.isArray(questions), "readQuestions returns an array");
+      assert.equal(questions.length, 3, "readQuestions deduplicates repeated storage records");
+      const firstQ = questions[0];
+      assert.ok(firstQ && typeof firstQ === "object" && "question" in firstQ && "priority" in firstQ);
+      assert.equal(firstQ.question, "How does recall work?", "readQuestions sorts by priority descending");
+      assert.equal(firstQ.priority, 10, "highest priority question comes first");
+
+      const loops = state.readIdentityImprovementLoopsResult;
+      assert.equal(
+        loops,
+        "# Improvement Loop A\n\n# Improvement Loop B",
+        "readIdentityImprovementLoops deduplicates identical sections and joins with double newline"
+      );
+
+      const incidents = state.readContinuityIncidentsResult as unknown[];
+      assert.ok(Array.isArray(incidents), "readContinuityIncidents returns an array");
+      assert.equal(incidents.length, 2, "readContinuityIncidents deduplicates repeated storage records");
+
+      const entityNames = state.listEntityNamesResult;
+      assert.ok(Array.isArray(entityNames), "listEntityNames returns an array");
+      assert.deepEqual(new Set(entityNames), new Set(["project-projectx", "project-projecty"]));
+
+      const memories = state.readAllMemoriesResult as unknown[];
+      assert.ok(Array.isArray(memories), "readAllMemories returns an array");
+      assert.equal(memories.length, 2, "readAllMemories aggregates memories across composite storages");
+      return;
+    }
+  },
+
+  async teardown(state: RecallProfileStorageState): Promise<void> {
+    if (state.memoryDir) {
+      await cleanupDir(state.memoryDir);
+    }
+    for (const dir of state.extraDirs) {
+      await cleanupDir(dir);
+    }
+  },
+};
+
+runLifecycleMatrix("recall-profile-storage", subject);