@remnic/core 1.0.2 → 1.1.0

package/dist/orchestrator.d.ts

@@ -10,12 +10,15 @@ import './negative.js';
 import './recall-state.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-export { c as GraphRecallRankedResult, e as GraphRecallShadowComparison, G as GraphRecallSnapshot, I as IntentDebugSnapshot, O as Orchestrator, Q as QmdRecallSnapshot, f as RecallInvocationOptions, g as RecallModeDecision, h as appendMemoryToGraphContext, i as blendGraphExpandedRecallScore, j as buildCompressionGuidelinesMarkdown, k as buildMemoryPathById, l as computeArtifactCandidateFetchLimit, m as computeArtifactRecallLimit, n as computeQmdHybridFetchLimit, d as defaultWorkspaceDir, o as deriveTopicsFromExtraction, p as filterRecallCandidates, q as formatCompressionGuidelinesForRecall, r as graphPathRelativeToStorage, t as hasIdentityRecoveryIntent, u as isArtifactMemoryPath, v as lifecycleRecallScoreAdjustment, w as mergeArtifactRecallCandidates, x as mergeGraphExpandedResults, y as resolveEffectiveIdentityInjectionMode, z as resolveEffectiveRecallMode, A as resolvePersistedMemoryRelativePath, B as resolveRecallModeDecision, D as resolveRecentThreadMemoryPaths, s as sanitizeSessionKeyForFilename, E as shouldFilterLifecycleRecallCandidate, F as summarizeGraphShadowComparison } from './orchestrator-zTa-Qo-1.js';
+export { l as GraphRecallRankedResult, m as GraphRecallShadowComparison, G as GraphRecallSnapshot, I as IntentDebugSnapshot, O as Orchestrator, Q as QmdRecallSnapshot, n as RecallInvocationOptions, o as RecallModeDecision, q as appendMemoryToGraphContext, r as blendGraphExpandedRecallScore, t as buildCompressionGuidelinesMarkdown, u as buildMemoryPathById, w as computeArtifactCandidateFetchLimit, x as computeArtifactRecallLimit, y as computeQmdHybridFetchLimit, z as dedupeEntitySynthesisEvidenceEntries, j as defaultWorkspaceDir, A as deriveTopicsFromExtraction, D as filterRecallCandidates, E as formatCompressionGuidelinesForRecall, F as graphPathRelativeToStorage, H as hasIdentityRecoveryIntent, J as isArtifactMemoryPath, K as lifecycleRecallScoreAdjustment, L as mergeArtifactRecallCandidates, M as mergeGraphExpandedResults, N as resolveEffectiveIdentityInjectionMode, P as resolveEffectiveRecallMode, S as resolvePersistedMemoryRelativePath, T as resolveRecallModeDecision, U as resolveRecentThreadMemoryPaths, s as sanitizeSessionKeyForFilename, V as shouldFilterLifecycleRecallCandidate, W as summarizeGraphShadowComparison } from './orchestrator-DRYA6_lW.js';
 import './types.js';
-import './semantic-consolidation.js';
+import './semantic-consolidation-DrvSYRdB.js';
 import './policy-runtime.js';
 import './profiling.js';
-import './memory-projection-store-NxMkbocT.js';
+import './page-versioning.js';
+import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 import './session-integrity.js';
 import 'zod';
+import './codex-materialize-CQlLTzke.js';
+import './logger.js';

package/dist/orchestrator.js

@@ -7,6 +7,7 @@ import {
   computeArtifactCandidateFetchLimit,
   computeArtifactRecallLimit,
   computeQmdHybridFetchLimit,
+  dedupeEntitySynthesisEvidenceEntries,
   defaultWorkspaceDir,
   deriveTopicsFromExtraction,
   filterRecallCandidates,
@@ -25,96 +26,107 @@ import {
   sanitizeSessionKeyForFilename,
   shouldFilterLifecycleRecallCandidate,
   summarizeGraphShadowComparison
-} from "./chunk-OTFNI3OO.js";
-import "./chunk-UYSKNO6E.js";
-import "./chunk-IFFFR3MR.js";
-import "./chunk-Z5AAYHUC.js";
-import "./chunk-4A24LIM2.js";
-import "./chunk-TPB3I2AC.js";
+} from "./chunk-DEPL3635.js";
+import "./chunk-DHHP2Z4X.js";
 import "./chunk-UHGBNIOS.js";
-import "./chunk-ZKYI7UVO.js";
-import "./chunk-LP47L3ZX.js";
+import "./chunk-FSFEQI74.js";
+import "./chunk-N42IWANG.js";
 import "./chunk-ETOW6ACV.js";
-import "./chunk-GPGBSNKM.js";
-import "./chunk-V3RXWQIE.js";
-import "./chunk-G3AG3KZN.js";
-import "./chunk-2CJCWDMR.js";
-import "./chunk-HG2NKWR2.js";
+import "./chunk-W6SL7OFG.js";
+import "./chunk-Z5AAYHUC.js";
+import "./chunk-S75M5ZRK.js";
+import "./chunk-TPB3I2AC.js";
+import "./chunk-JR4ZC3G4.js";
+import "./chunk-KVE7R4CG.js";
 import "./chunk-X7XN6YU4.js";
-import "./chunk-BRK4ODMI.js";
+import "./chunk-5NPGSAVB.js";
 import "./chunk-C7VW7C3F.js";
+import "./chunk-K4FLSOR5.js";
+import "./chunk-V3RXWQIE.js";
+import "./chunk-5IZL4DCV.js";
 import "./chunk-YCN4BVDK.js";
-import "./chunk-L5RPWGFK.js";
-import "./chunk-GJR6D6KC.js";
+import "./chunk-YDBIWGNI.js";
+import "./chunk-7DHTMOND.js";
+import "./chunk-47UU5PU2.js";
+import "./chunk-D654IBA6.js";
 import "./chunk-H63EDPFJ.js";
-import "./chunk-WWIQTB2Y.js";
-import "./chunk-6UJQNRIO.js";
-import "./chunk-MWGVGUIS.js";
-import "./chunk-763GUIOU.js";
-import "./chunk-ONRU4L2N.js";
-import "./chunk-MDDAA2AO.js";
 import "./chunk-YAZNBMNF.js";
-import "./chunk-2PO5ZRKV.js";
+import "./chunk-GGD5W7TB.js";
+import "./chunk-LAYN4LDC.js";
+import "./chunk-3SV6CQHO.js";
+import "./chunk-UEYA6UC7.js";
+import "./chunk-NBNN5GOB.js";
+import "./chunk-FEMOX5AD.js";
+import "./chunk-JL2PU6AI.js";
+import "./chunk-GZCUW5IC.js";
 import "./chunk-VEWZZM3H.js";
-import "./chunk-QPKFPHOO.js";
-import "./chunk-V4YC4LUK.js";
-import "./chunk-HLBYLYRD.js";
-import "./chunk-OTAVQCSF.js";
+import "./chunk-ALXMCZEU.js";
+import "./chunk-7WQ6SLIE.js";
+import "./chunk-PAORGQRI.js";
+import "./chunk-6UJ47TVX.js";
+import "./chunk-PYXS46O7.js";
 import "./chunk-3QKK7QOS.js";
-import "./chunk-UIYZ5T3I.js";
-import "./chunk-UCYSTFZR.js";
-import "./chunk-J47FNDR7.js";
+import "./chunk-JRNQ3RNA.js";
+import "./chunk-JIU55F3X.js";
 import "./chunk-CULXMQJH.js";
-import "./chunk-UV2FO7J4.js";
-import "./chunk-T4WRIV2C.js";
-import "./chunk-LOBRX7VD.js";
-import "./chunk-IZME7KW2.js";
+import "./chunk-E6K4NIEU.js";
+import "./chunk-ZVBB3T7V.js";
 import "./chunk-YRMVARQP.js";
-import "./chunk-TVVVQQAK.js";
-import "./chunk-BDFZXRSO.js";
+import "./chunk-BLKTA7MM.js";
+import "./chunk-EABGC2TL.js";
+import "./chunk-LOBRX7VD.js";
+import "./chunk-HMDCOMYU.js";
+import "./chunk-J4IYOZZ5.js";
 import "./chunk-LK6SGL53.js";
-import "./chunk-AAI7JARD.js";
-import "./chunk-C6QPK5GG.js";
-import "./chunk-Q6FETXJA.js";
+import "./chunk-7SEAZFFB.js";
 import "./chunk-K6WK37A6.js";
-import "./chunk-SCHEKPYH.js";
-import "./chunk-ORZMT74A.js";
-import "./chunk-B7LOFDVE.js";
+import "./chunk-3PG3H5TD.js";
 import "./chunk-FYIYMQ5N.js";
 import "./chunk-2NMMFZ5T.js";
 import "./chunk-Z5LAYHGJ.js";
-import "./chunk-JWPLJLDU.js";
-import "./chunk-YNI4S5WT.js";
-import "./chunk-DORBM6OB.js";
-import "./chunk-XYIK4LF6.js";
-import "./chunk-XUHI52HK.js";
-import "./chunk-M5ZBBBJI.js";
-import "./chunk-OOSWAUYB.js";
+import "./chunk-C6QPK5GG.js";
+import "./chunk-SYUK3VLY.js";
+import "./chunk-EJI5XIBB.js";
+import "./chunk-44ICJRF3.js";
+import "./chunk-XZ2TIKGC.js";
 import "./chunk-Y27UJK6V.js";
+import "./chunk-ODWDQNRE.js";
 import "./chunk-UZB5KHKX.js";
-import "./chunk-M5KEYE5E.js";
+import "./chunk-C2EFFULQ.js";
+import "./chunk-4WMCPJWX.js";
+import "./chunk-6HZ6AO2P.js";
+import "./chunk-JWPLJLDU.js";
+import "./chunk-N53K2EXC.js";
+import "./chunk-URB2WSKZ.js";
+import "./chunk-UVJFDP7P.js";
+import "./chunk-XYIK4LF6.js";
+import "./chunk-PVGDJXVK.js";
 import "./chunk-NGAVDO7E.js";
 import "./chunk-MARWOCVP.js";
-import "./chunk-N5AKDXAI.js";
 import "./chunk-EQINRHYR.js";
+import "./chunk-QDYXG4CS.js";
+import "./chunk-QNJMBKFK.js";
 import "./chunk-EEQLFRUM.js";
-import "./chunk-QWUUMMIK.js";
-import "./chunk-U4PV25RD.js";
-import "./chunk-ESSMF2FR.js";
-import "./chunk-TP4FZJIZ.js";
+import "./chunk-QDW3E4RD.js";
+import "./chunk-4NRAJUDS.js";
+import "./chunk-DT5TVLJE.js";
+import "./chunk-N5AKDXAI.js";
+import "./chunk-TBBDFYXW.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+import "./chunk-GV6NLQ4X.js";
+import "./chunk-3WHVNEN7.js";
+import "./chunk-4KAN3GZ3.js";
+import "./chunk-6ZH4TU6I.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
+import "./chunk-6PFRXT4K.js";
+import "./chunk-TP4FZJIZ.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
-import "./chunk-YNCQ7E4M.js";
-import "./chunk-HLXVTBF3.js";
 import "./chunk-M62O4P4T.js";
-import "./chunk-DT5TVLJE.js";
-import "./chunk-KWBU5S5U.js";
-import "./chunk-DGXUHMOV.js";
-import "./chunk-LPSF4OQH.js";
-import "./chunk-6HZ6AO2P.js";
-import "./chunk-QCCCQT3O.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   Orchestrator,
   appendMemoryToGraphContext,
@@ -124,6 +136,7 @@ export {
   computeArtifactCandidateFetchLimit,
   computeArtifactRecallLimit,
   computeQmdHybridFetchLimit,
+  dedupeEntitySynthesisEvidenceEntries,
   defaultWorkspaceDir,
   deriveTopicsFromExtraction,
   filterRecallCandidates,

package/dist/page-versioning.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Page-level versioning with history and revert (issue #371).
+ *
+ * Provides snapshot-based versioning for memory files using a sidecar
+ * directory layout.  Each memory page gets a `.versions/<pageName>/`
+ * subdirectory containing numbered snapshots and a `manifest.json` that
+ * records the version history.
+ *
+ * Storage layout:
+ *   memoryDir/
+ *     facts/preferences.md              <- current file
+ *     .versions/
+ *       facts__preferences/
+ *         manifest.json                  <- VersionHistory
+ *         1.md                           <- version 1 snapshot
+ *         2.md                           <- version 2 snapshot
+ */
+interface PageVersion {
+    versionId: string;
+    timestamp: string;
+    contentHash: string;
+    sizeBytes: number;
+    trigger: VersionTrigger;
+    note?: string;
+}
+type VersionTrigger = "write" | "consolidation" | "revert" | "manual";
+interface VersionHistory {
+    pagePath: string;
+    versions: PageVersion[];
+    currentVersion: string;
+}
+interface VersioningConfig {
+    enabled: boolean;
+    maxVersionsPerPage: number;
+    sidecarDir: string;
+}
+interface VersioningLogger {
+    debug(msg: string): void;
+    warn(msg: string): void;
+}
+/**
+ * Create a new version snapshot for a page.
+ *
+ * Call this BEFORE overwriting the current file so the previous content is
+ * preserved. If the file does not exist yet (first write), the provided
+ * `content` is snapshotted as version 1.
+ *
+ * Pruning: when the number of versions exceeds `config.maxVersionsPerPage`,
+ * the oldest snapshots (and their files) are removed.
+ */
+declare function createVersion(pagePath: string, content: string, trigger: VersionTrigger, config: VersioningConfig, log?: VersioningLogger, note?: string, memoryDir?: string): Promise<PageVersion>;
+/**
+ * List all versions for a page.
+ */
+declare function listVersions(pagePath: string, config: VersioningConfig, memoryDir?: string): Promise<VersionHistory>;
+/**
+ * Read the content of a specific version.
+ */
+declare function getVersion(pagePath: string, versionId: string, config: VersioningConfig, memoryDir?: string): Promise<string>;
+/**
+ * Revert a page to a previous version.
+ *
+ * 1. Reads the target version's content.
+ * 2. Snapshots the CURRENT content as a new version (trigger: "revert").
+ * 3. Writes the reverted content to the page file.
+ *
+ * Returns the newly created version entry for the revert snapshot.
+ */
+declare function revertToVersion(pagePath: string, versionId: string, config: VersioningConfig, log?: VersioningLogger, memoryDir?: string): Promise<PageVersion>;
+/**
+ * Simple line-based diff between two versions.
+ *
+ * Returns a unified-style diff string showing added (+) and removed (-) lines.
+ */
+declare function diffVersions(pagePath: string, v1: string, v2: string, config: VersioningConfig, memoryDir?: string): Promise<string>;
+
+export { type PageVersion, type VersionHistory, type VersionTrigger, type VersioningConfig, type VersioningLogger, createVersion, diffVersions, getVersion, listVersions, revertToVersion };

package/dist/page-versioning.js

@@ -0,0 +1,15 @@
+import {
+  createVersion,
+  diffVersions,
+  getVersion,
+  listVersions,
+  revertToVersion
+} from "./chunk-6ZH4TU6I.js";
+export {
+  createVersion,
+  diffVersions,
+  getVersion,
+  listVersions,
+  revertToVersion
+};
+//# sourceMappingURL=page-versioning.js.map

package/dist/page-versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/plugin-id.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical plugin id for @remnic/plugin-openclaw.
+ *
+ * This is the identifier OpenClaw uses as a lookup key in plugins.slots.memory
+ * and plugins.entries.<id>. The legacy shim package @joshuaswarren/openclaw-engram
+ * intentionally uses a different id ("openclaw-engram") as a backwards-compat alias.
+ */
+declare const PLUGIN_ID: "openclaw-remnic";
+declare const LEGACY_PLUGIN_ID: "openclaw-engram";
+/**
+ * Resolve the Remnic plugin entry from an OpenClaw-shaped config object.
+ *
+ * Lookup order:
+ *   1. `plugins.slots.memory` — but **only** when it resolves to a known
+ *      Remnic plugin id; foreign slots are ignored so mixed-plugin installs
+ *      do not accidentally apply another plugin's config to Remnic.
+ *   2. `preferredId` — the caller's own plugin id (e.g. `"openclaw-engram"` for
+ *      the shim package); only consulted when no active slot overrides the choice.
+ *   3. `plugins.entries["openclaw-remnic"]`
+ *   4. `plugins.entries["openclaw-engram"]` (legacy backward-compat)
+ *
+ * Returns `undefined` when no Remnic entry is found.
+ *
+ * All five config-loader sites (loadPluginEntryFromFile, readPluginHooksPolicy,
+ * loadPluginConfig in access-cli.ts, loadCliPluginConfig in operator-toolkit.ts,
+ * and unwrapOpenClawEntry in materialize.cjs) delegate here so fallback order
+ * and guard logic are defined in exactly one place.
+ *
+ * @param raw - The raw OpenClaw config object.
+ * @param preferredId - The calling plugin's own id.  When present and no
+ *   `plugins.slots.memory` slot is set, this id is tried before the hardcoded
+ *   `PLUGIN_ID`/`LEGACY_PLUGIN_ID` fallbacks.  Ignored if it is not a known
+ *   Remnic plugin id (safety guard against unexpected values).
+ */
+declare function resolveRemnicPluginEntry(raw: unknown, preferredId?: string): Record<string, unknown> | undefined;
+
+export { LEGACY_PLUGIN_ID, PLUGIN_ID, resolveRemnicPluginEntry };

package/dist/plugin-id.js

@@ -0,0 +1,11 @@
+import {
+  LEGACY_PLUGIN_ID,
+  PLUGIN_ID,
+  resolveRemnicPluginEntry
+} from "./chunk-U66YHYC7.js";
+export {
+  LEGACY_PLUGIN_ID,
+  PLUGIN_ID,
+  resolveRemnicPluginEntry
+};
+//# sourceMappingURL=plugin-id.js.map

package/dist/plugin-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/policy-runtime.js

@@ -2,9 +2,9 @@ import {
   PolicyRuntimeManager,
   readRuntimePolicySnapshot,
   sanitizeRuntimePolicyValues
-} from "./chunk-T4WRIV2C.js";
+} from "./chunk-EABGC2TL.js";
 import "./chunk-6HZ6AO2P.js";
-import "./chunk-QCCCQT3O.js";
+import "./chunk-TBBDFYXW.js";
 export {
   PolicyRuntimeManager,
   readRuntimePolicySnapshot,

package/dist/profiling.js

@@ -1,8 +1,8 @@
 import {
   ProfilingCollector,
   formatProfileTraceAscii
-} from "./chunk-763GUIOU.js";
-import "./chunk-KWBU5S5U.js";
+} from "./chunk-NBNN5GOB.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   ProfilingCollector,
   formatProfileTraceAscii

package/dist/qmd.d.ts

@@ -17,9 +17,12 @@ declare class QmdClient implements SearchBackend {
     private readonly collection;
     private readonly maxResults;
     private available;
-    private lastUpdateFailAtMs;
+    private _lastUpdateFailAtMs;
     private lastEmbedFailAtMs;
     private lastUpdateRunAtMs;
+    get lastUpdateFailedAtMs(): number | null;
+    get lastUpdateRanAtMs(): number | null;
+    resetUpdateThrottles(): void;
     private readonly updateTimeoutMs;
     private readonly updateMinIntervalMs;
     private readonly slowLog?;
@@ -94,7 +97,7 @@ declare class QmdClient implements SearchBackend {
     private bm25SearchViaSubprocess;
     private vsearchViaSubprocess;
     private searchGlobalViaSubprocess;
-    update(): Promise<void>;
+    update(signal?: AbortSignal): Promise<void>;
     updateCollection(collection: string): Promise<void>;
     private runUpdateForCollection;
     embed(): Promise<void>;

package/dist/qmd.js

@@ -1,11 +1,12 @@
 import {
   QmdClient,
   parseQmdExplain
-} from "./chunk-TVVVQQAK.js";
+} from "./chunk-BLKTA7MM.js";
 import "./chunk-LK6SGL53.js";
+import "./chunk-PVGDJXVK.js";
 import "./chunk-MARWOCVP.js";
-import "./chunk-ESSMF2FR.js";
-import "./chunk-KWBU5S5U.js";
+import "./chunk-6PFRXT4K.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   QmdClient,
   parseQmdExplain

package/dist/recall-audit.d.ts

@@ -0,0 +1,20 @@
+interface RecallAuditEntry {
+    ts: string;
+    sessionKey: string;
+    agentId: string;
+    trigger: string;
+    queryText: string;
+    candidateMemoryIds: string[];
+    summary: string | null;
+    injectedChars: number;
+    toggleState: "enabled" | "disabled-primary" | "disabled-secondary";
+    latencyMs?: number;
+    plannerMode?: string;
+    requestedMode?: string;
+    fallbackUsed?: boolean;
+}
+declare function buildRecallAuditPath(rootDir: string, ts: string, sessionKey: string): string;
+declare function appendRecallAuditEntry(rootDir: string, entry: RecallAuditEntry): Promise<string>;
+declare function pruneRecallAuditEntries(rootDir: string, retentionDays: number, now?: Date): Promise<string[]>;
+
+export { type RecallAuditEntry, appendRecallAuditEntry, buildRecallAuditPath, pruneRecallAuditEntries };

package/dist/recall-audit.js

@@ -0,0 +1,50 @@
+// src/recall-audit.ts
+import { appendFile, mkdir, readdir, rm } from "fs/promises";
+import path from "path";
+function formatIsoDate(ts) {
+  const normalized = new Date(ts);
+  if (Number.isNaN(normalized.getTime())) {
+    return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  }
+  return normalized.toISOString().slice(0, 10);
+}
+function buildRecallAuditPath(rootDir, ts, sessionKey) {
+  const safeSessionKey = encodeURIComponent(sessionKey);
+  return path.join(rootDir, "transcripts", formatIsoDate(ts), `${safeSessionKey}.jsonl`);
+}
+async function appendRecallAuditEntry(rootDir, entry) {
+  const filePath = buildRecallAuditPath(rootDir, entry.ts, entry.sessionKey);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await appendFile(filePath, `${JSON.stringify(entry)}
+`, "utf8");
+  return filePath;
+}
+async function pruneRecallAuditEntries(rootDir, retentionDays, now = /* @__PURE__ */ new Date()) {
+  const transcriptsDir = path.join(rootDir, "transcripts");
+  const removed = [];
+  const cutoff = new Date(now);
+  cutoff.setUTCHours(0, 0, 0, 0);
+  cutoff.setUTCDate(cutoff.getUTCDate() - Math.max(1, Math.floor(retentionDays)));
+  let entries;
+  try {
+    entries = await readdir(transcriptsDir, { withFileTypes: true });
+  } catch {
+    return removed;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.name)) continue;
+    const day = /* @__PURE__ */ new Date(`${entry.name}T00:00:00.000Z`);
+    if (Number.isNaN(day.getTime()) || day >= cutoff) continue;
+    const dirPath = path.join(transcriptsDir, entry.name);
+    await rm(dirPath, { recursive: true, force: true });
+    removed.push(dirPath);
+  }
+  return removed;
+}
+export {
+  appendRecallAuditEntry,
+  buildRecallAuditPath,
+  pruneRecallAuditEntries
+};
+//# sourceMappingURL=recall-audit.js.map

package/dist/recall-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-audit.ts"],"sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { appendFile, mkdir, readdir, rm } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nexport interface RecallAuditEntry {\n  ts: string;\n  sessionKey: string;\n  agentId: string;\n  trigger: string;\n  queryText: string;\n  candidateMemoryIds: string[];\n  summary: string | null;\n  injectedChars: number;\n  toggleState: \"enabled\" | \"disabled-primary\" | \"disabled-secondary\";\n  latencyMs?: number;\n  plannerMode?: string;\n  requestedMode?: string;\n  fallbackUsed?: boolean;\n}\n\nfunction formatIsoDate(ts: string): string {\n  const normalized = new Date(ts);\n  if (Number.isNaN(normalized.getTime())) {\n    return new Date().toISOString().slice(0, 10);\n  }\n  return normalized.toISOString().slice(0, 10);\n}\n\nexport function buildRecallAuditPath(rootDir: string, ts: string, sessionKey: string): string {\n  const safeSessionKey = encodeURIComponent(sessionKey);\n  return path.join(rootDir, \"transcripts\", formatIsoDate(ts), `${safeSessionKey}.jsonl`);\n}\n\nexport async function appendRecallAuditEntry(\n  rootDir: string,\n  entry: RecallAuditEntry,\n): Promise<string> {\n  const filePath = buildRecallAuditPath(rootDir, entry.ts, entry.sessionKey);\n  await mkdir(path.dirname(filePath), { recursive: true });\n  await appendFile(filePath, `${JSON.stringify(entry)}\\n`, \"utf8\");\n  return filePath;\n}\n\nexport async function pruneRecallAuditEntries(\n  rootDir: string,\n  retentionDays: number,\n  now: Date = new Date(),\n): Promise<string[]> {\n  const transcriptsDir = path.join(rootDir, \"transcripts\");\n  const removed: string[] = [];\n  const cutoff = new Date(now);\n  cutoff.setUTCHours(0, 0, 0, 0);\n  cutoff.setUTCDate(cutoff.getUTCDate() - Math.max(1, Math.floor(retentionDays)));\n  let entries: Dirent[];\n  try {\n    entries = await readdir(transcriptsDir, { withFileTypes: true });\n  } catch {\n    return removed;\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory()) continue;\n    if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(entry.name)) continue;\n    const day = new Date(`${entry.name}T00:00:00.000Z`);\n    if (Number.isNaN(day.getTime()) || day >= cutoff) continue;\n    const dirPath = path.join(transcriptsDir, entry.name);\n    await rm(dirPath, { recursive: true, force: true });\n    removed.push(dirPath);\n  }\n\n  return removed;\n}\n"],"mappings":";AACA,SAAS,YAAY,OAAO,SAAS,UAAU;AAC/C,OAAO,UAAU;AAkBjB,SAAS,cAAc,IAAoB;AACzC,QAAM,aAAa,IAAI,KAAK,EAAE;AAC9B,MAAI,OAAO,MAAM,WAAW,QAAQ,CAAC,GAAG;AACtC,YAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAAA,EAC7C;AACA,SAAO,WAAW,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEO,SAAS,qBAAqB,SAAiB,IAAY,YAA4B;AAC5F,QAAM,iBAAiB,mBAAmB,UAAU;AACpD,SAAO,KAAK,KAAK,SAAS,eAAe,cAAc,EAAE,GAAG,GAAG,cAAc,QAAQ;AACvF;AAEA,eAAsB,uBACpB,SACA,OACiB;AACjB,QAAM,WAAW,qBAAqB,SAAS,MAAM,IAAI,MAAM,UAAU;AACzE,QAAM,MAAM,KAAK,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AACvD,QAAM,WAAW,UAAU,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,GAAM,MAAM;AAC/D,SAAO;AACT;AAEA,eAAsB,wBACpB,SACA,eACA,MAAY,oBAAI,KAAK,GACF;AACnB,QAAM,iBAAiB,KAAK,KAAK,SAAS,aAAa;AACvD,QAAM,UAAoB,CAAC;AAC3B,QAAM,SAAS,IAAI,KAAK,GAAG;AAC3B,SAAO,YAAY,GAAG,GAAG,GAAG,CAAC;AAC7B,SAAO,WAAW,OAAO,WAAW,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,aAAa,CAAC,CAAC;AAC9E,MAAI;AACJ,MAAI;AACF,cAAU,MAAM,QAAQ,gBAAgB,EAAE,eAAe,KAAK,CAAC;AAAA,EACjE,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,MAAM,YAAY,EAAG;AAC1B,QAAI,CAAC,sBAAsB,KAAK,MAAM,IAAI,EAAG;AAC7C,UAAM,MAAM,oBAAI,KAAK,GAAG,MAAM,IAAI,gBAAgB;AAClD,QAAI,OAAO,MAAM,IAAI,QAAQ,CAAC,KAAK,OAAO,OAAQ;AAClD,UAAM,UAAU,KAAK,KAAK,gBAAgB,MAAM,IAAI;AACpD,UAAM,GAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAClD,YAAQ,KAAK,OAAO;AAAA,EACtB;AAEA,SAAO;AACT;","names":[]}

package/dist/recall-mmr.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Maximal Marginal Relevance (MMR) re-selection for recall candidates.
+ *
+ * After the reranker produces its ordered candidate list, we run an MMR pass
+ * over the top N candidates (per-section) so that a cluster of near-duplicate
+ * high-scoring facts cannot dominate the injected context.
+ *
+ *     MMR(d) = λ * sim(d, query) − (1 − λ) * max_{d' ∈ selected} sim(d, d')
+ *
+ * - λ defaults to 0.7 (tilted toward relevance, with meaningful diversity).
+ * - Similarity uses cosine over pre-computed embeddings when available, and
+ *   falls back to Jaccard over normalized tokens (lowercased alphanumerics)
+ *   when embeddings are missing.
+ * - Per-section application is the caller's responsibility: pass each
+ *   section's ordered candidate slice independently so one cluster in one
+ *   section cannot starve another section.
+ *
+ * Pure, deterministic, no IO. Input arrays are never mutated.
+ */
+/** Minimal candidate shape used by MMR. Callers may wrap their own records. */
+interface MmrCandidate {
+    /** Stable identifier for the candidate. Only used for tie-breaking. */
+    id: string;
+    /** Text content used for the Jaccard similarity fallback. */
+    content: string;
+    /**
+     * Relevance score from the upstream ranker (e.g. rerank score or RRF).
+     * Used as the `sim(d, query)` term when no query embedding is available.
+     */
+    score: number;
+    /** Optional pre-computed embedding vector for cosine similarity. */
+    embedding?: readonly number[] | null;
+}
+interface ApplyMmrOptions<C extends MmrCandidate> {
+    /** Ordered candidate list (most relevant first). */
+    candidates: readonly C[];
+    /** Optional query embedding. If provided and candidates carry embeddings,
+     *  relevance is measured by cosine similarity to the query. Otherwise
+     *  candidate `score` is normalized and used. */
+    queryEmbedding?: readonly number[] | null;
+    /** λ ∈ [0, 1]. 1 = pure relevance, 0 = pure diversity. Default 0.7. */
+    lambda?: number;
+    /** Apply MMR only over the top N candidates. Default 40. */
+    topN?: number;
+    /** Maximum number of candidates to select. Default = candidates length. */
+    budget?: number;
+}
+interface MmrDiversityReport {
+    /**
+     * Total number of candidates MMR considered (the full input pool, pre-MMR).
+     * Previously this mirrored `kept` and was therefore uninformative; it now
+     * reflects the true pool size so `kept/considered` logs carry signal even
+     * though MMR is reorder-only.
+     */
+    considered: number;
+    /**
+     * Number of candidates present in the MMR output. With the current
+     * orchestrator pipeline MMR is reorder-only (no drops), so this is the
+     * same as `considered`. It's still reported separately so a future
+     * drop-mode MMR can distinguish them without another schema change.
+     */
+    kept: number;
+    /**
+     * Head-of-list positions whose candidate identity changed between the
+     * pre-MMR and post-MMR slices. This is the *actionable* diversity signal:
+     * it tells the caller how many of the top `sampleSize` results MMR
+     * promoted or demoted. Zero means MMR had no head-of-list effect; a value
+     * greater than zero means at least one diverse candidate was swapped in.
+     */
+    headReorderCount: number;
+    /** Average pairwise similarity of the head-of-list input slice (pre-MMR). */
+    avgPairwiseSimBefore: number;
+    /** Average pairwise similarity of the head-of-list MMR output slice. */
+    avgPairwiseSimAfter: number;
+}
+declare const DEFAULT_LAMBDA = 0.7;
+declare const DEFAULT_TOP_N = 40;
+/**
+ * Pure MMR re-selection over an ordered candidate list.
+ *
+ * Returns a new array — the input is never mutated. When `candidates.length`
+ * is `<= 1` or `budget <= 0`, a defensive copy is returned as a no-op.
+ */
+declare function applyMmrToCandidates<C extends MmrCandidate>(opts: ApplyMmrOptions<C>): C[];
+/**
+ * Summarize how much MMR reshuffled the head of the candidate list, for
+ * logging. Optional — callers can skip this if they don't care about metrics.
+ *
+ * IMPORTANT: `before` should be the score-ordered input (the same ordering the
+ * upstream reranker emitted, *not* the MMR output), and `after` should be the
+ * MMR-reordered list. Both are truncated to `sampleSize` before their pairwise
+ * similarity is averaged.
+ *
+ * The sample size intentionally defaults to a small number
+ * ({@link DEFAULT_DIVERSITY_SAMPLE_SIZE}) so that when the caller uses
+ * `budget >= candidates.length` (i.e. MMR only reorders without dropping), the
+ * head-of-list comparison still reflects whether MMR promoted diverse
+ * candidates. Passing a sample size `>= candidates.length` in that situation
+ * makes `avgPairwiseSimBefore` and `avgPairwiseSimAfter` trivially equal
+ * because pairwise similarity is order-independent.
+ */
+declare function summarizeMmrDiversity<C extends MmrCandidate>(before: readonly C[], after: readonly C[], sampleSize?: number): MmrDiversityReport;
+declare function normalizeTokens(text: string): Set<string>;
+/**
+ * Minimum shape the recall-MMR orchestration helper expects from a result.
+ * Any richer result type (e.g. {@link QmdSearchResult}) satisfies this.
+ */
+interface MmrRecallResult {
+    readonly docid?: string;
+    readonly path?: string;
+    readonly snippet?: string;
+    readonly score?: number;
+}
+interface ReorderRecallResultsOptions {
+    readonly lambda?: number;
+    readonly topN?: number;
+    /**
+     * Head-of-list sample size used by the diversity metric. Defaults to
+     * {@link DEFAULT_DIVERSITY_SAMPLE_SIZE}. Intentionally small so the metric
+     * reflects head-of-list changes even when `budget >= results.length`.
+     */
+    readonly diversitySampleSize?: number;
+}
+interface ReorderRecallResultsOutcome<R extends MmrRecallResult> {
+    readonly reordered: R[];
+    readonly diversity: MmrDiversityReport;
+    readonly lambda: number;
+}
+/**
+ * Apply MMR to an ordered list of recall results and return the reordered
+ * list plus a head-of-list diversity report.
+ *
+ * This helper is the single source of truth for the orchestrator's
+ * per-section MMR pass. It is pure and deterministic so it can be unit
+ * tested without constructing an Orchestrator.
+ *
+ * Key invariants:
+ * 1. **No silent drops.** Candidates are keyed by a stable unique key derived
+ *    from `path` first, falling back to `docid`, and always suffixed with the
+ *    candidate's original index. Two results that share a basename-style
+ *    docid but differ in path are treated as distinct candidates and both
+ *    survive the reorder.
+ * 2. **No mutation.** The input array is never mutated; a new array is
+ *    returned.
+ * 3. **Diversity metric is meaningful.** The report compares the *head of
+ *    list* before and after MMR using a small sample size, so it reflects
+ *    whether MMR promoted diverse candidates even when
+ *    `budget >= results.length`.
+ */
+declare function reorderRecallResultsWithMmr<R extends MmrRecallResult>(results: readonly R[], options?: ReorderRecallResultsOptions): ReorderRecallResultsOutcome<R>;
+
+export { type ApplyMmrOptions, DEFAULT_LAMBDA, DEFAULT_TOP_N, type MmrCandidate, type MmrDiversityReport, type MmrRecallResult, type ReorderRecallResultsOptions, type ReorderRecallResultsOutcome, applyMmrToCandidates, normalizeTokens, reorderRecallResultsWithMmr, summarizeMmrDiversity };