@remnic/core 1.1.2 → 1.1.3

package/dist/patterns-cli.d.ts

@@ -0,0 +1,160 @@
+import { MemoryCategory, MemoryFile } from './types.js';
+
+/**
+ * `remnic patterns` CLI helpers (issue #687 PR 4/4).
+ *
+ * Pure functions that:
+ *
+ *   1. Validate `--limit`, `--category`, `--since`, `--format` for
+ *      `remnic patterns list` and `--format` for
+ *      `remnic patterns explain <id>` (CLAUDE.md rules 14 + 51 — flags
+ *      throw listed-options errors instead of silently defaulting).
+ *
+ *   2. Filter the memory corpus to canonical memories produced by the
+ *      pattern-reinforcement maintenance job from issue #687 PR 2/4
+ *      (`reinforcement_count > 0`) and sort them by reinforcement
+ *      count, with `last_reinforced_at` (then `id`) as stable
+ *      tiebreakers (CLAUDE.md rule 19).
+ *
+ *   3. Reconstruct a single canonical's full picture: its
+ *      `derived_from` provenance chain (PR 2/4 stamps these), the
+ *      cluster members it absorbed (memories pointing at it via
+ *      `supersededBy`), and the canonical body so operators can read
+ *      it inline.
+ *
+ *   4. Render `text` (default) / `markdown` / `json` output for both
+ *      commands.  The CLI handler in `cli.ts` stays thin and delegates
+ *      formatting here so HTTP / MCP surfaces (if added later) can
+ *      reuse the same renderers (CLAUDE.md rule 22 — never fork
+ *      formatting).
+ */
+
+declare const PATTERNS_OUTPUT_FORMATS: readonly ["text", "markdown", "json"];
+type PatternsOutputFormat = (typeof PATTERNS_OUTPUT_FORMATS)[number];
+/**
+ * Validate `--format <fmt>`.  Throws a listed-options error for any
+ * value not in `PATTERNS_OUTPUT_FORMATS`.  Returns `"text"` when the
+ * value is `undefined` (no flag supplied).
+ */
+declare function parsePatternsFormat(value: unknown): PatternsOutputFormat;
+/**
+ * Validate `--limit <N>`.  Must be a positive integer.  Returns
+ * `undefined` when the flag is absent (the caller falls back to a
+ * default).
+ */
+declare function parsePatternsLimit(value: unknown): number | undefined;
+/**
+ * Validate `--category <list>`.  Accepts a comma-separated list of
+ * non-empty trimmed tokens.  Returns the deduplicated list, or
+ * `undefined` when no flag was supplied.  CLAUDE.md rules 14 + 51:
+ * `--category` with no value or with a value that resolves to zero
+ * tokens is rejected.
+ */
+declare function parsePatternsCategory(value: unknown): string[] | undefined;
+/**
+ * Validate `--since <ISO>`.  Delegates to `parseStrictCliDate` which
+ * enforces a strict ISO 8601 shape and rejects calendar overflows and
+ * non-ISO formats (e.g. "12/25/2026", "Dec 25 2026") that bare
+ * `Date.parse()` would silently accept.  Returns the canonical ISO
+ * string (round-trip through `toISOString`) so downstream comparisons
+ * use a consistent form.
+ */
+declare function parsePatternsSince(value: unknown): string | undefined;
+interface ParsedPatternsListOptions {
+    format: PatternsOutputFormat;
+    limit?: number;
+    categories?: string[];
+    sinceIso?: string;
+}
+interface ParsedPatternsExplainOptions {
+    format: PatternsOutputFormat;
+}
+/**
+ * Validate the full option bag for `remnic patterns list`.  Extracted
+ * from the CLI handler so validation can be unit-tested without
+ * booting an orchestrator (CLAUDE.md rules 14 + 51).
+ */
+declare function parsePatternsListOptions(options: Record<string, unknown>): ParsedPatternsListOptions;
+/**
+ * Validate `remnic patterns explain` options + positional id.  Throws
+ * when `<memoryId>` is missing or empty.
+ */
+declare function parsePatternsExplainOptions(rawId: unknown, options: Record<string, unknown>): {
+    id: string;
+} & ParsedPatternsExplainOptions;
+interface PatternListRow {
+    id: string;
+    category: MemoryCategory;
+    reinforcementCount: number;
+    lastReinforcedAt?: string;
+    status: string;
+    /** First non-empty content line, trimmed to ~120 chars for the table. */
+    preview: string;
+    /** Full path on disk (relative to memoryDir) for operators who want to inspect the file. */
+    path: string;
+}
+/**
+ * Filter, sort, and slice the memory corpus down to the rows the
+ * `remnic patterns list` command should print.
+ *
+ * Rules (each one is exercised by `tests/cli/patterns.test.ts`):
+ *
+ *   - Memories without `reinforcement_count` (or with a count <= 0) are
+ *     dropped — these are not pattern canonicals.
+ *   - When `categories` is supplied, only memories whose
+ *     `frontmatter.category` is in the list survive.
+ *   - When `sinceIso` is supplied, only memories whose
+ *     `last_reinforced_at` is `>= sinceIso` survive.  Memories without
+ *     `last_reinforced_at` are dropped under `--since` (PR 2/4 always
+ *     stamps the timestamp alongside the count, so a missing timestamp
+ *     means a malformed file the operator should not see in this view).
+ *   - Sort by `reinforcement_count DESC`, then `last_reinforced_at
+ *     DESC`, then `id ASC` for a stable, deterministic order
+ *     (CLAUDE.md rule 19).
+ *   - Apply `limit` (default 50).
+ */
+declare function collectPatternMemories(memories: readonly MemoryFile[], opts: ParsedPatternsListOptions): PatternListRow[];
+interface PatternDerivedFromEntry {
+    /** Raw `"<path>:<version>"` reference exactly as stored in `derived_from`. */
+    ref: string;
+    /** Source memory id, or the path component for older `path:version` references. */
+    path: string;
+    /** Page-version number component for older `path:version` references. */
+    version: number | null;
+    /** True when an older path-version reference had an invalid version component. */
+    malformed?: boolean;
+}
+interface PatternClusterMember {
+    id: string;
+    status: string;
+    supersededAt?: string;
+    path: string;
+    preview: string;
+}
+interface PatternExplainDetail {
+    id: string;
+    category: MemoryCategory;
+    reinforcementCount: number;
+    lastReinforcedAt?: string;
+    status: string;
+    derivedVia?: string;
+    /** Full canonical body (frontmatter stripped). */
+    canonicalContent: string;
+    canonicalPath: string;
+    /** Parsed `derived_from` chain — empty when PR 2/4 did not stamp it. */
+    derivedFrom: PatternDerivedFromEntry[];
+    /** Memories whose `supersededBy === <id>`, sorted by `supersededAt DESC` then `id ASC`. */
+    clusterMembers: PatternClusterMember[];
+}
+/**
+ * Build the structured detail object for a single canonical.  Returns
+ * `null` when the memory is not found or has never been touched by
+ * pattern reinforcement (i.e., no `reinforcement_count`).  The CLI
+ * handler then prints a clean "not a pattern" error rather than
+ * leaking an empty document.
+ */
+declare function explainPatternMemory(memories: readonly MemoryFile[], id: string): PatternExplainDetail | null;
+declare function renderPatternsList(rows: readonly PatternListRow[], format: PatternsOutputFormat): string;
+declare function renderPatternExplain(detail: PatternExplainDetail, format: PatternsOutputFormat): string;
+
+export { PATTERNS_OUTPUT_FORMATS, type ParsedPatternsExplainOptions, type ParsedPatternsListOptions, type PatternClusterMember, type PatternDerivedFromEntry, type PatternExplainDetail, type PatternListRow, type PatternsOutputFormat, collectPatternMemories, explainPatternMemory, parsePatternsCategory, parsePatternsExplainOptions, parsePatternsFormat, parsePatternsLimit, parsePatternsListOptions, parsePatternsSince, renderPatternExplain, renderPatternsList };

package/dist/patterns-cli.js

@@ -0,0 +1,29 @@
+import {
+  PATTERNS_OUTPUT_FORMATS,
+  collectPatternMemories,
+  explainPatternMemory,
+  parsePatternsCategory,
+  parsePatternsExplainOptions,
+  parsePatternsFormat,
+  parsePatternsLimit,
+  parsePatternsListOptions,
+  parsePatternsSince,
+  renderPatternExplain,
+  renderPatternsList
+} from "./chunk-AJA46VX5.js";
+import "./chunk-G7D6GZ5J.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  PATTERNS_OUTPUT_FORMATS,
+  collectPatternMemories,
+  explainPatternMemory,
+  parsePatternsCategory,
+  parsePatternsExplainOptions,
+  parsePatternsFormat,
+  parsePatternsLimit,
+  parsePatternsListOptions,
+  parsePatternsSince,
+  renderPatternExplain,
+  renderPatternsList
+};
+//# sourceMappingURL=patterns-cli.js.map

package/dist/patterns-cli.js.map

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

package/dist/peers-6OSQ3NK6.js

@@ -0,0 +1,44 @@
+import {
+  buildPeerProfileReasonerPrompt,
+  parsePeerProfileReasonerResponse,
+  runPeerProfileReasoner
+} from "./chunk-3LCWFNVS.js";
+import {
+  PEERS_DIR_NAME,
+  PEER_ID_MAX_LENGTH,
+  PEER_ID_PATTERN,
+  appendInteractionLog,
+  assertValidPeerId,
+  deletePeer,
+  forgetPeer,
+  listPeers,
+  migrateFromIdentityAnchor,
+  readInteractionLogRaw,
+  readPeer,
+  readPeerInteractionLog,
+  readPeerProfile,
+  writePeer,
+  writePeerProfile
+} from "./chunk-TUFG6VXY.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  PEERS_DIR_NAME,
+  PEER_ID_MAX_LENGTH,
+  PEER_ID_PATTERN,
+  appendInteractionLog,
+  assertValidPeerId,
+  buildPeerProfileReasonerPrompt,
+  deletePeer,
+  forgetPeer,
+  listPeers,
+  migrateFromIdentityAnchor,
+  parsePeerProfileReasonerResponse,
+  readInteractionLogRaw,
+  readPeer,
+  readPeerInteractionLog,
+  readPeerProfile,
+  runPeerProfileReasoner,
+  writePeer,
+  writePeerProfile
+};
+//# sourceMappingURL=peers-6OSQ3NK6.js.map

package/dist/peers-6OSQ3NK6.js.map

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

package/dist/plugin-id.js

@@ -3,6 +3,7 @@ import {
   PLUGIN_ID,
   resolveRemnicPluginEntry
 } from "./chunk-U66YHYC7.js";
+import "./chunk-PZ5AY32C.js";
 export {
   LEGACY_PLUGIN_ID,
   PLUGIN_ID,

package/dist/policy-runtime.js

@@ -5,6 +5,7 @@ import {
 } from "./chunk-EABGC2TL.js";
 import "./chunk-6HZ6AO2P.js";
 import "./chunk-TBBDFYXW.js";
+import "./chunk-PZ5AY32C.js";
 export {
   PolicyRuntimeManager,
   readRuntimePolicySnapshot,

package/dist/{port-BADbLZU5.d.ts → port-hqGnoStS.d.ts}

@@ -33,6 +33,12 @@ interface SearchBackend {
     hybridSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
     update(execution?: SearchExecutionOptions): Promise<void>;
     updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
+    /**
+     * Optional strict refresh used by callers that must know whether a collection
+     * was actually refreshed before writing success markers. Ordinary update
+     * calls remain fail-open for migration/maintenance resilience.
+     */
+    updateCollectionStrict?(collection: string, execution?: SearchExecutionOptions): Promise<void>;
     embed(): Promise<void>;
     embedCollection(collection: string): Promise<void>;
     ensureCollection(memoryDir: string): Promise<"present" | "missing" | "unknown" | "skipped">;

package/dist/profiling.js

@@ -3,6 +3,7 @@ import {
   formatProfileTraceAscii
 } from "./chunk-NBNN5GOB.js";
 import "./chunk-2ODBA7MQ.js";
+import "./chunk-PZ5AY32C.js";
 export {
   ProfilingCollector,
   formatProfileTraceAscii

package/dist/purge-6ATBGT77.js

@@ -0,0 +1,205 @@
+import "./chunk-PZ5AY32C.js";
+
+// src/maintenance/purge.ts
+import path from "path";
+import { appendFile, mkdir, unlink } from "fs/promises";
+function hasErrorCode(err, code) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === code;
+}
+function resolveTimestamp(memory) {
+  const fm = memory.frontmatter;
+  const updated = typeof fm.updated === "string" ? fm.updated : "";
+  const created = typeof fm.created === "string" ? fm.created : "";
+  return updated.length > 0 ? updated : created;
+}
+async function logPurgeAudit(storage, candidates, now, event = "PURGE_HARD_DELETE") {
+  if (candidates.length === 0) return;
+  const ledgerDir = path.join(storage.dir, "state", "observation-ledger");
+  await mkdir(ledgerDir, { recursive: true });
+  const ledgerPath = path.join(ledgerDir, "purge-audit.jsonl");
+  const entries = candidates.map(
+    (c) => JSON.stringify({
+      event,
+      timestamp: now.toISOString(),
+      memoryId: c.id,
+      path: c.path,
+      tier: c.tier,
+      status: c.status,
+      updatedOrCreated: c.updatedOrCreated
+    })
+  );
+  if (entries.length > 0) {
+    await appendFile(ledgerPath, `${entries.join("\n")}
+`, "utf-8");
+  }
+}
+async function purgeMemories(options) {
+  const {
+    storage,
+    olderThanMs,
+    tier = "cold",
+    forgottenOnly = false,
+    dryRun = true,
+    qmd,
+    hotCollection = "openclaw-engram",
+    coldCollection = "openclaw-engram-cold"
+  } = options;
+  if (!Number.isFinite(olderThanMs) || olderThanMs <= 0) {
+    throw new Error("olderThanMs must be a finite positive number");
+  }
+  const now = (options.now ?? (() => /* @__PURE__ */ new Date()))();
+  const nowMs = now.getTime();
+  const [hotMemories, coldMemories, archivedMemories] = await Promise.all([
+    tier === "all" ? storage.readAllMemories() : Promise.resolve([]),
+    storage.readAllColdMemories(),
+    tier === "all" ? storage.readArchivedMemories() : Promise.resolve([])
+  ]);
+  const poolEntries = [];
+  if (tier === "all") {
+    for (const m of hotMemories) {
+      poolEntries.push({ memory: m, resolvedTier: "hot" });
+    }
+    for (const m of archivedMemories) {
+      poolEntries.push({ memory: m, resolvedTier: "archive" });
+    }
+  }
+  for (const m of coldMemories) {
+    poolEntries.push({ memory: m, resolvedTier: "cold" });
+  }
+  const candidates = [];
+  const candidateMemoriesById = /* @__PURE__ */ new Map();
+  for (const { memory, resolvedTier } of poolEntries) {
+    const ts = resolveTimestamp(memory);
+    if (ts.length === 0) continue;
+    const tsMs = Date.parse(ts);
+    if (!Number.isFinite(tsMs)) continue;
+    const ageMs = nowMs - tsMs;
+    if (ageMs < olderThanMs) continue;
+    const fm = memory.frontmatter;
+    const status = typeof fm.status === "string" ? fm.status : "active";
+    if (forgottenOnly && status !== "forgotten") continue;
+    candidates.push({
+      id: memory.frontmatter.id,
+      path: memory.path,
+      tier: resolvedTier,
+      status,
+      updatedOrCreated: ts,
+      ageMs
+    });
+    candidateMemoriesById.set(memory.frontmatter.id, memory);
+  }
+  if (dryRun) {
+    return {
+      dryRun: true,
+      tier,
+      olderThanMs,
+      candidates,
+      purgedCount: 0,
+      alreadyAbsentCount: 0,
+      errorCount: 0,
+      errors: []
+    };
+  }
+  const errors = [];
+  try {
+    await logPurgeAudit(storage, candidates, now, "PURGE_DELETE_INTENT");
+  } catch (auditErr) {
+    errors.push({
+      id: "(purge-audit)",
+      path: path.join(storage.dir, "state", "observation-ledger", "purge-audit.jsonl"),
+      error: auditErr instanceof Error ? auditErr.message : String(auditErr)
+    });
+  }
+  const actuallyPurged = [];
+  const alreadyAbsent = [];
+  const collectionsToUpdate = /* @__PURE__ */ new Set();
+  const addCollectionForCandidate = (candidate) => {
+    if (candidate.tier === "cold") {
+      collectionsToUpdate.add(coldCollection);
+    } else if (candidate.tier === "hot") {
+      collectionsToUpdate.add(hotCollection);
+    }
+  };
+  for (const candidate of candidates) {
+    try {
+      await unlink(candidate.path);
+      actuallyPurged.push(candidate);
+      addCollectionForCandidate(candidate);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (hasErrorCode(err, "ENOENT")) {
+        alreadyAbsent.push(candidate);
+        addCollectionForCandidate(candidate);
+      } else {
+        errors.push({ id: candidate.id, path: candidate.path, error: message });
+      }
+    }
+  }
+  const recordPostDeleteAudit = async (purgedCandidates, event) => {
+    try {
+      await logPurgeAudit(storage, purgedCandidates, now, event);
+    } catch (auditErr) {
+      errors.push({
+        id: "(purge-audit)",
+        path: path.join(storage.dir, "state", "observation-ledger", "purge-audit.jsonl"),
+        error: auditErr instanceof Error ? auditErr.message : String(auditErr)
+      });
+    }
+  };
+  await recordPostDeleteAudit(actuallyPurged, "PURGE_HARD_DELETE");
+  await recordPostDeleteAudit(alreadyAbsent, "PURGE_ALREADY_ABSENT");
+  const resolvedPurges = [...actuallyPurged, ...alreadyAbsent];
+  const invalidateTierCaches = storage.invalidateMemoryCachesForTiers;
+  if (typeof invalidateTierCaches === "function") {
+    invalidateTierCaches.call(storage, new Set(resolvedPurges.map((candidate) => candidate.tier)));
+  } else if (typeof storage.invalidateAllMemoriesCacheForDir === "function") {
+    storage.invalidateAllMemoriesCacheForDir();
+  }
+  if (qmd) {
+    for (const collection of collectionsToUpdate) {
+      try {
+        if (typeof qmd.updateCollectionStrict === "function") {
+          await qmd.updateCollectionStrict(collection, { signal: options.signal });
+        } else {
+          await qmd.updateCollection(collection, { signal: options.signal });
+        }
+      } catch (indexErr) {
+        errors.push({
+          id: "(qmd-update)",
+          path: collection,
+          error: indexErr instanceof Error ? indexErr.message : String(indexErr)
+        });
+      }
+    }
+  }
+  const purgedFactMemories = resolvedPurges.map((candidate) => candidateMemoriesById.get(candidate.id)).filter((memory) => memory?.frontmatter.category === "fact");
+  if (purgedFactMemories.length > 0) {
+    const removeFactHashes = storage.removeFactContentHashesForMemories;
+    if (typeof removeFactHashes === "function") {
+      try {
+        await removeFactHashes.call(storage, purgedFactMemories);
+        await options.afterFactHashRemoval?.();
+      } catch (hashErr) {
+        errors.push({
+          id: "(fact-hash-index)",
+          path: path.join(storage.dir, "state", "fact-hashes.txt"),
+          error: hashErr instanceof Error ? hashErr.message : String(hashErr)
+        });
+      }
+    }
+  }
+  return {
+    dryRun: false,
+    tier,
+    olderThanMs,
+    candidates,
+    purgedCount: actuallyPurged.length,
+    alreadyAbsentCount: alreadyAbsent.length,
+    errorCount: errors.length,
+    errors
+  };
+}
+export {
+  purgeMemories
+};
+//# sourceMappingURL=purge-6ATBGT77.js.map

package/dist/purge-6ATBGT77.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/maintenance/purge.ts"],"sourcesContent":["/**\n * Operator-facing bulk hard-delete (issue #686 retention-completion).\n *\n * `purgeMemories(opts)` hard-deletes memories that are:\n *   - older than `olderThanMs` (measured against `updated ?? created`), AND\n *   - in the specified tier (`\"cold\"` or `\"all\"`), AND\n *   - optionally in `status: \"forgotten\"` only (when `forgottenOnly` is true)\n *\n * Hard-delete means:\n *   1. Remove the file from disk.\n *   2. Trigger a QMD collection update so the index no longer contains it.\n *   3. Append a purge audit entry to the observation ledger.\n *\n * `dryRun: true` (the default) reports what *would* be deleted without\n * actually removing anything — callers must opt into mutations by\n * setting `dryRun: false`.\n *\n * The CLI surface enforces an explicit `--confirm yes` guard and\n * defaults to `--dry-run` to make accidental data loss impossible.\n */\n\nimport path from \"node:path\";\nimport { appendFile, mkdir, unlink } from \"node:fs/promises\";\nimport type { StorageManager } from \"../storage.js\";\nimport type { MemoryFile } from \"../types.js\";\nimport type { SearchBackend } from \"../search/port.js\";\n\nexport type PurgeTierFilter = \"cold\" | \"all\";\n\nexport interface PurgeMemoriesOptions {\n  storage: StorageManager;\n  /**\n   * Only memories whose `updated ?? created` timestamp is older than this\n   * value (in milliseconds, Unix epoch) will be candidates.\n   */\n  olderThanMs: number;\n  /**\n   * `\"cold\"` — only memories in the cold tier (files under `.../cold/`).\n   * `\"all\"` — memories in any tier (hot, cold, or archived).\n   * Default: `\"cold\"`.\n   */\n  tier?: PurgeTierFilter;\n  /**\n   * When `true`, only memories with `status === \"forgotten\"` are candidates.\n   * Default: `false` (purge by age + tier regardless of status).\n   */\n  forgottenOnly?: boolean;\n  /** When `true` (default), report candidates but do not delete. */\n  dryRun?: boolean;\n  /**\n   * Optional QMD backend. When supplied and `dryRun === false`, a\n   * `updateCollection` call is issued after each deletion so the index stays\n   * consistent. Pass `undefined` or omit to skip index maintenance (e.g. in\n   * tests that don't have a live QMD instance).\n   */\n  qmd?: SearchBackend;\n  /** Hot-tier QMD collection name (default: `\"openclaw-engram\"`). */\n  hotCollection?: string;\n  /** Cold-tier QMD collection name (default: `\"openclaw-engram-cold\"`). */\n  coldCollection?: string;\n  /** Optional hook for long-lived hosts to clear their live dedupe mirror after purge hash cleanup. */\n  afterFactHashRemoval?: () => void | Promise<void>;\n  /** Optional shutdown signal forwarded to QMD collection refreshes. */\n  signal?: AbortSignal;\n  /** Override clock for tests. */\n  now?: () => Date;\n}\n\nexport interface PurgeCandidate {\n  id: string;\n  path: string;\n  tier: \"hot\" | \"cold\" | \"archive\";\n  status: string;\n  updatedOrCreated: string;\n  ageMs: number;\n}\n\nexport interface PurgeMemoriesResult {\n  dryRun: boolean;\n  tier: PurgeTierFilter;\n  olderThanMs: number;\n  candidates: PurgeCandidate[];\n  purgedCount: number;\n  alreadyAbsentCount: number;\n  errorCount: number;\n  errors: Array<{ id: string; path: string; error: string }>;\n}\n\nfunction hasErrorCode(err: unknown, code: string): boolean {\n  return typeof err === \"object\" && err !== null && \"code\" in err && (err as { code?: unknown }).code === code;\n}\n\nfunction resolveTimestamp(memory: MemoryFile): string {\n  const fm = memory.frontmatter as unknown as Record<string, unknown>;\n  const updated = typeof fm.updated === \"string\" ? (fm.updated as string) : \"\";\n  const created = typeof fm.created === \"string\" ? (fm.created as string) : \"\";\n  return updated.length > 0 ? updated : created;\n}\n\nasync function logPurgeAudit(\n  storage: StorageManager,\n  candidates: PurgeCandidate[],\n  now: Date,\n  event: \"PURGE_DELETE_INTENT\" | \"PURGE_HARD_DELETE\" | \"PURGE_ALREADY_ABSENT\" = \"PURGE_HARD_DELETE\",\n): Promise<void> {\n  if (candidates.length === 0) return;\n  const ledgerDir = path.join(storage.dir, \"state\", \"observation-ledger\");\n  await mkdir(ledgerDir, { recursive: true });\n  const ledgerPath = path.join(ledgerDir, \"purge-audit.jsonl\");\n  const entries = candidates.map((c) =>\n    JSON.stringify({\n      event,\n      timestamp: now.toISOString(),\n      memoryId: c.id,\n      path: c.path,\n      tier: c.tier,\n      status: c.status,\n      updatedOrCreated: c.updatedOrCreated,\n    }),\n  );\n  if (entries.length > 0) {\n    await appendFile(ledgerPath, `${entries.join(\"\\n\")}\\n`, \"utf-8\");\n  }\n}\n\nexport async function purgeMemories(\n  options: PurgeMemoriesOptions,\n): Promise<PurgeMemoriesResult> {\n  const {\n    storage,\n    olderThanMs,\n    tier = \"cold\",\n    forgottenOnly = false,\n    dryRun = true,\n    qmd,\n    hotCollection = \"openclaw-engram\",\n    coldCollection = \"openclaw-engram-cold\",\n  } = options;\n\n  if (!Number.isFinite(olderThanMs) || olderThanMs <= 0) {\n    throw new Error(\"olderThanMs must be a finite positive number\");\n  }\n\n  const now = (options.now ?? (() => new Date()))();\n  const nowMs = now.getTime();\n\n  // Collect all memories from applicable tiers\n  const [hotMemories, coldMemories, archivedMemories] = await Promise.all([\n    tier === \"all\" ? storage.readAllMemories() : Promise.resolve([]),\n    storage.readAllColdMemories(),\n    tier === \"all\" ? storage.readArchivedMemories() : Promise.resolve([]),\n  ]);\n\n  const poolEntries: Array<{ memory: MemoryFile; resolvedTier: \"hot\" | \"cold\" | \"archive\" }> = [];\n\n  if (tier === \"all\") {\n    for (const m of hotMemories) {\n      poolEntries.push({ memory: m, resolvedTier: \"hot\" });\n    }\n    for (const m of archivedMemories) {\n      poolEntries.push({ memory: m, resolvedTier: \"archive\" });\n    }\n  }\n  for (const m of coldMemories) {\n    poolEntries.push({ memory: m, resolvedTier: \"cold\" });\n  }\n\n  // Build candidate list\n  const candidates: PurgeCandidate[] = [];\n  const candidateMemoriesById = new Map<string, MemoryFile>();\n  for (const { memory, resolvedTier } of poolEntries) {\n    const ts = resolveTimestamp(memory);\n    if (ts.length === 0) continue;\n\n    const tsMs = Date.parse(ts);\n    if (!Number.isFinite(tsMs)) continue;\n\n    const ageMs = nowMs - tsMs;\n    if (ageMs < olderThanMs) continue;\n\n    const fm = memory.frontmatter as unknown as Record<string, unknown>;\n    const status: string =\n      typeof fm.status === \"string\" ? (fm.status as string) : \"active\";\n\n    if (forgottenOnly && status !== \"forgotten\") continue;\n\n    candidates.push({\n      id: memory.frontmatter.id,\n      path: memory.path,\n      tier: resolvedTier,\n      status,\n      updatedOrCreated: ts,\n      ageMs,\n    });\n    candidateMemoriesById.set(memory.frontmatter.id, memory);\n  }\n\n  if (dryRun) {\n    return {\n      dryRun: true,\n      tier,\n      olderThanMs,\n      candidates,\n      purgedCount: 0,\n      alreadyAbsentCount: 0,\n      errorCount: 0,\n      errors: [],\n    };\n  }\n\n  // Hard-delete phase\n  const errors: Array<{ id: string; path: string; error: string }> = [];\n  try {\n    await logPurgeAudit(storage, candidates, now, \"PURGE_DELETE_INTENT\");\n  } catch (auditErr) {\n    errors.push({\n      id: \"(purge-audit)\",\n      path: path.join(storage.dir, \"state\", \"observation-ledger\", \"purge-audit.jsonl\"),\n      error: auditErr instanceof Error ? auditErr.message : String(auditErr),\n    });\n  }\n\n  const actuallyPurged: PurgeCandidate[] = [];\n  const alreadyAbsent: PurgeCandidate[] = [];\n  const collectionsToUpdate = new Set<string>();\n  const addCollectionForCandidate = (candidate: PurgeCandidate) => {\n    if (candidate.tier === \"cold\") {\n      collectionsToUpdate.add(coldCollection);\n    } else if (candidate.tier === \"hot\") {\n      collectionsToUpdate.add(hotCollection);\n    }\n  };\n\n  for (const candidate of candidates) {\n    try {\n      await unlink(candidate.path);\n      actuallyPurged.push(candidate);\n      addCollectionForCandidate(candidate);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      // ENOENT is fine — already gone\n      if (hasErrorCode(err, \"ENOENT\")) {\n        alreadyAbsent.push(candidate);\n        addCollectionForCandidate(candidate);\n      } else {\n        errors.push({ id: candidate.id, path: candidate.path, error: message });\n      }\n    }\n  }\n\n  const recordPostDeleteAudit = async (\n    purgedCandidates: PurgeCandidate[],\n    event: \"PURGE_HARD_DELETE\" | \"PURGE_ALREADY_ABSENT\",\n  ) => {\n    try {\n      await logPurgeAudit(storage, purgedCandidates, now, event);\n    } catch (auditErr) {\n      errors.push({\n        id: \"(purge-audit)\",\n        path: path.join(storage.dir, \"state\", \"observation-ledger\", \"purge-audit.jsonl\"),\n        error: auditErr instanceof Error ? auditErr.message : String(auditErr),\n      });\n    }\n  };\n  await recordPostDeleteAudit(actuallyPurged, \"PURGE_HARD_DELETE\");\n  await recordPostDeleteAudit(alreadyAbsent, \"PURGE_ALREADY_ABSENT\");\n\n  const resolvedPurges = [...actuallyPurged, ...alreadyAbsent];\n\n  const invalidateTierCaches = (\n    storage as unknown as {\n      invalidateMemoryCachesForTiers?: (tiers: Iterable<\"hot\" | \"cold\" | \"archive\">) => void;\n    }\n  ).invalidateMemoryCachesForTiers;\n  if (typeof invalidateTierCaches === \"function\") {\n    invalidateTierCaches.call(storage, new Set(resolvedPurges.map((candidate) => candidate.tier)));\n  } else if (typeof (storage as unknown as { invalidateAllMemoriesCacheForDir?: () => void }).invalidateAllMemoriesCacheForDir === \"function\") {\n    (storage as unknown as { invalidateAllMemoriesCacheForDir: () => void }).invalidateAllMemoriesCacheForDir();\n  }\n\n  // Update QMD index for affected collections\n  if (qmd) {\n    for (const collection of collectionsToUpdate) {\n      try {\n        if (typeof qmd.updateCollectionStrict === \"function\") {\n          await qmd.updateCollectionStrict(collection, { signal: options.signal });\n        } else {\n          await qmd.updateCollection(collection, { signal: options.signal });\n        }\n      } catch (indexErr) {\n        // Non-fatal — operator can re-index manually\n        errors.push({\n          id: \"(qmd-update)\",\n          path: collection,\n          error: indexErr instanceof Error ? indexErr.message : String(indexErr),\n        });\n      }\n    }\n  }\n\n  const purgedFactMemories = resolvedPurges\n    .map((candidate) => candidateMemoriesById.get(candidate.id))\n    .filter((memory): memory is MemoryFile => memory?.frontmatter.category === \"fact\");\n  if (purgedFactMemories.length > 0) {\n    const removeFactHashes = (\n      storage as unknown as {\n        removeFactContentHashesForMemories?: (memories: MemoryFile[]) => Promise<void>;\n      }\n    ).removeFactContentHashesForMemories;\n    if (typeof removeFactHashes === \"function\") {\n      try {\n        await removeFactHashes.call(storage, purgedFactMemories);\n        await options.afterFactHashRemoval?.();\n      } catch (hashErr) {\n        errors.push({\n          id: \"(fact-hash-index)\",\n          path: path.join(storage.dir, \"state\", \"fact-hashes.txt\"),\n          error: hashErr instanceof Error ? hashErr.message : String(hashErr),\n        });\n      }\n    }\n  }\n\n  return {\n    dryRun: false,\n    tier,\n    olderThanMs,\n    candidates,\n    purgedCount: actuallyPurged.length,\n    alreadyAbsentCount: alreadyAbsent.length,\n    errorCount: errors.length,\n    errors,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/qmd-recall-cache.d.ts

@@ -1,5 +1,5 @@
 import { RecallPlanMode } from './types.js';
-import { a as SearchQueryOptions } from './port-BADbLZU5.js';
+import { a as SearchQueryOptions } from './port-hqGnoStS.js';
 
 type QmdRecallCacheSource = "fresh" | "stale";
 interface QmdRecallCacheHit<T> {

package/dist/qmd-recall-cache.js

@@ -4,6 +4,7 @@ import {
   getCachedQmdRecall,
   setCachedQmdRecall
 } from "./chunk-YCN4BVDK.js";
+import "./chunk-PZ5AY32C.js";
 export {
   buildQmdRecallCacheKey,
   clearQmdRecallCache,

package/dist/qmd.d.ts

@@ -1,5 +1,5 @@
 import { QmdSearchResult, QmdSearchExplain } from './types.js';
-import { S as SearchBackend, a as SearchQueryOptions, b as SearchExecutionOptions } from './port-BADbLZU5.js';
+import { S as SearchBackend, a as SearchQueryOptions, b as SearchExecutionOptions } from './port-hqGnoStS.js';
 
 interface QmdClientOptions {
     slowLog?: {
@@ -101,6 +101,7 @@ declare class QmdClient implements SearchBackend {
     private searchGlobalViaSubprocess;
     update(execution?: SearchExecutionOptions): Promise<void>;
     updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
+    updateCollectionStrict(collection: string, execution?: SearchExecutionOptions): Promise<void>;
     private runUpdateForCollection;
     embed(): Promise<void>;
     embedCollection(collection: string): Promise<void>;

package/dist/qmd.js

@@ -1,12 +1,13 @@
 import {
   QmdClient,
   parseQmdExplain
-} from "./chunk-4HQS2HPX.js";
-import "./chunk-OR64ZGRZ.js";
+} from "./chunk-WSZIHQBK.js";
 import "./chunk-PVGDJXVK.js";
-import "./chunk-6PFRXT4K.js";
+import "./chunk-OR64ZGRZ.js";
+import "./chunk-PFV5C235.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-2ODBA7MQ.js";
+import "./chunk-PZ5AY32C.js";
 export {
   QmdClient,
   parseQmdExplain

package/dist/reasoning-trace-recall.js

@@ -4,6 +4,7 @@ import {
   isReasoningTracePath,
   looksLikeProblemSolvingQuery
 } from "./chunk-ZZTOURJI.js";
+import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_REASONING_TRACE_BOOST,
   applyReasoningTraceBoost,

package/dist/reasoning-trace-types.js

@@ -6,6 +6,7 @@ import {
   normalizeReasoningTraceSteps,
   parseReasoningTraceFromBody
 } from "./chunk-54V4BZWP.js";
+import "./chunk-PZ5AY32C.js";
 export {
   buildReasoningTraceMarkdownBody,
   buildReasoningTracePersistBody,

package/dist/recall-audit-anomaly.js

@@ -3,6 +3,7 @@ import {
   detectRecallAnomalies,
   normalizeQueryText
 } from "./chunk-RFYAYKTD.js";
+import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_ANOMALY_DETECTOR_CONFIG,
   detectRecallAnomalies,

package/dist/recall-audit.js

@@ -3,6 +3,7 @@ import {
   buildRecallAuditPath,
   pruneRecallAuditEntries
 } from "./chunk-LBLXEFWK.js";
+import "./chunk-PZ5AY32C.js";
 export {
   appendRecallAuditEntry,
   buildRecallAuditPath,