recallnest 3.0.1 → 4.0.0

package/src/mcp-tools-advanced.ts

@@ -1,39 +1,78 @@
 import { z } from "zod";
-import { indexAsset, indexPinnedAsset } from "./asset-sync.js";
+import { indexAsset, pinMemory } from "./asset-sync.js";
 import { createAuditLogger } from "./audit-log.js";
 import { persistCaseMemory, persistMemoryBatch, persistWorkflowPattern, promoteMemory } from "./capture-engine.js";
 import { autoCapture } from "./capture-heuristic.js";
 import { computeSynthesisUptake } from "./consolidation-engine.js";
 import { runDataCheckup, formatCheckupReport } from "./data-checkup.js";
 import { runDream, formatDreamResult } from "./dream-pipeline.js";
-import { forgetMemory } from "./forget-engine.js";
+import { forgetMemory, summarizeVerification, type ForgetPinArchive, type ForgetResult } from "./forget-engine.js";
 import { exportMemoryGraph, formatGraphExportResult } from "./graph-export.js";
-import { assetSummaryLine, buildBriefAsset, buildPinAsset, listMemoryAssets, listPinAssets, saveBriefAsset, savePinAsset, writeExportArtifact } from "./memory-assets.js";
+import { archivePinAssetsForMemory, assetSummaryLine, buildBriefAsset, findPinAssetsForMemory, listMemoryAssets, listPinAssets, saveBriefAsset, writeExportArtifact } from "./memory-assets.js";
 import { runMemoryLint, formatMemoryLintReport } from "./memory-lint.js";
 import { distillResults, formatExplainResults, selectBriefSeedResults, summarizeResults } from "./memory-output.js";
 import { DurableMemoryCategorySchema, StoreMemorySourceSchema, DebugFramingSchema } from "./memory-schema.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
 import { persistSkill, retrieveSkills } from "./skill-engine.js";
 import { SkillImplementationTypeSchema } from "./skill-schema.js";
+import { formatBatchStoreReceipt } from "./store-receipts.js";
 import type { ToolRegistryDeps } from "./mcp-tool-deps.js";
-import type { RetrievalResult } from "./retriever.js";
-import type { MemoryStore } from "./store.js";
 
-function entryToRetrievalResult(entry: Awaited<ReturnType<MemoryStore["get"]>>): RetrievalResult {
-  if (!entry) {
-    throw new Error("Memory entry not found.");
+/** The data/pins directory, as forget_memory uses it when nothing else is injected. */
+const defaultForgetPins: ForgetPinArchive = {
+  archiveForMemory: (id) => archivePinAssetsForMemory(id).length,
+  countForMemory: (id) => findPinAssetsForMemory(id).length,
+};
+
+/**
+ * forget_memory 的输出：逐项报数，回读结果写在明处。
+ * 第一行只有在回读「干净」时才打勾：id 取不到了、哪一层都没数出残留、也没有哪一层查不了。
+ */
+function formatForgetResult(result: ForgetResult): string {
+  const id = result.memoryId.slice(0, 8);
+  const count = (n: number | null | undefined) => (n === null || n === undefined ? "n/a" : String(n));
+  const v = result.verification;
+  const state = v ? summarizeVerification(v) : "unverified";
+
+  let head: string;
+  if (state === "clean") {
+    head = `✅ Memory ${id} forgotten.`;
+  } else if (state === "leftovers" && v) {
+    const leftovers: string[] = [];
+    if (v.triggerRowsLeft) leftovers.push(`trigger rows ${v.triggerRowsLeft}`);
+    if (v.pinsLeft) leftovers.push(`pin files ${v.pinsLeft}`);
+    if (v.pinIndexRowsLeft) leftovers.push(`pin index rows ${v.pinIndexRowsLeft}`);
+    if (v.kgTriplesLeft) leftovers.push(`KG triples ${v.kgTriplesLeft}`);
+    head = `⚠️ Memory ${id} forgotten, but the read-back found leftovers: ${leftovers.join(", ")}.`;
+  } else {
+    const unchecked = v && v.unverified.length > 0 ? v.unverified.join(", ") : "primary";
+    head = `⚠️ Memory ${id} deleted, but the read-back could not check: ${unchecked}.`;
   }
-  return {
-    entry,
-    score: entry.importance || 0.7,
-    sources: {
-      fused: { score: entry.importance || 0.7 },
-    },
-  };
+
+  const lines = [
+    head,
+    `Privacy tier: ${result.evidence?.privacyTier || "unknown"}`,
+    `KG triples removed: ${result.kgTriplesRemoved ? "yes" : "no/N/A"}`,
+    `Trigger rows removed: ${count(result.triggerRowsRemoved)}`,
+    `Pins archived: ${count(result.pinsArchived)} (index rows removed: ${count(result.pinIndexRowsRemoved)})`,
+    `Cascade demoted: ${result.cascadeResult.demotedCount} related memories`,
+    `Read-back: ${v?.primary ?? "unverified"} (left: trigger rows ${count(v?.triggerRowsLeft)}, pin files ${count(v?.pinsLeft)}, pin index rows ${count(v?.pinIndexRowsLeft)}, KG triples ${count(v?.kgTriplesLeft)})`,
+  ];
+  if (v && v.unverified.length > 0 && state !== "unverified") {
+    lines.push(`Could not check: ${v.unverified.join(", ")}`);
+  }
+  if (result.pinsArchived) {
+    // 归档是挪走不是删：文件里还有那段正文，调用方得知道它在哪
+    lines.push("Archived pin files were moved, not erased: they are in data/archive/forgotten-pins and still hold the snippet. Delete them there if the content itself has to go.");
+  }
+  if (result.evidence?.reason) {
+    lines.push(`Reason: ${result.evidence.reason}`);
+  }
+  return lines.join("\n");
 }
 
 export function registerAdvancedTools(deps: ToolRegistryDeps): void {
-  const { registerTool, getComponents, conflictStore, getKGExtractor, getKGStore, auditLogger } = deps;
+  const { registerTool, getComponents, conflictStore, getKGExtractor, getKGStore, auditLogger, forgetPins } = deps;
 
 registerTool(
   "store_workflow_pattern",
@@ -391,15 +430,16 @@ registerTool(
       return { content: [{ type: "text" as const, text: `Memory not found: ${memory_id}` }] };
     }
 
-    await store.update(entry.id, { importance: Math.max(entry.importance || 0.7, 0.95) }, scopeSelection.scopeFilter);
-    const asset = buildPinAsset(entryToRetrievalResult(entry), {
+    const pinned = await pinMemory(store, embedder, entry, scopeSelection.scopeFilter, {
       title,
       summary,
       query,
       profile: profileName || "default",
     });
-    const path = savePinAsset(asset);
-    await indexPinnedAsset(store, embedder, asset);
+    if (!pinned) {
+      return { content: [{ type: "text" as const, text: `Memory not found: ${memory_id}` }] };
+    }
+    const { asset, path } = pinned;
 
     return {
       content: [{
@@ -473,7 +513,7 @@ registerTool(
 
 registerTool(
   "forget_memory",
-  "Permanently forget a memory with full cascade: delete primary entry, remove KG triples, demote related memories, and log an audit trail. Requires confirm=true for durable-tier memories. Use when the user explicitly requests a memory be forgotten, or to clean up sensitive/incorrect data.",
+  "Permanently forget a memory: delete the primary entry, remove its KG triples and trigger rows, remove pins made from it (the file is archived, its indexed copy deleted), demote related memories, read back to confirm, and log an audit trail. Requires confirm=true for durable-tier memories. Use when the user explicitly requests a memory be forgotten, or to clean up sensitive/incorrect data.",
   {
     memoryId: z.string().min(1).max(128).describe("Memory ID to forget (full UUID or 8+ hex prefix)"),
     confirm: z.boolean().default(false).describe("Required confirmation — must be true for durable-tier memories"),
@@ -481,13 +521,19 @@ registerTool(
     scope: z.string().min(1).max(160).optional().describe("Optional scope filter for permission check"),
   },
   async ({ memoryId, confirm, reason, scope }) => {
-    const { store } = getComponents();
+    const { store, triggerStore } = getComponents();
     const kgStoreInstance = getKGStore();
     const auditLogger = createAuditLogger();
     const scopeFilter = scope ? [scope] : undefined;
 
     const result = await forgetMemory(
-      { store, kgStore: kgStoreInstance, auditLogger },
+      {
+        store,
+        kgStore: kgStoreInstance,
+        auditLogger,
+        triggerStore,
+        pins: forgetPins ?? defaultForgetPins,
+      },
       { memoryId, confirm, reason, scopeFilter },
     );
 
@@ -497,20 +543,10 @@ registerTool(
       throw new Error(result.error || "forget_memory failed");
     }
 
-    const lines = [
-      `✅ Memory ${result.memoryId.slice(0, 8)} forgotten.`,
-      `Privacy tier: ${result.evidence?.privacyTier || "unknown"}`,
-      `KG triples removed: ${result.kgTriplesRemoved ? "yes" : "no/N/A"}`,
-      `Cascade demoted: ${result.cascadeResult.demotedCount} related memories`,
-    ];
-    if (result.evidence?.reason) {
-      lines.push(`Reason: ${result.evidence.reason}`);
-    }
-
     return {
       content: [{
         type: "text" as const,
-        text: lines.join("\n"),
+        text: formatForgetResult(result),
       }],
     };
   },
@@ -555,9 +591,14 @@ registerTool(
     // 在产无人消费的内容或读打点断链，是能报警的健康度数字。
     // cap 取 totalCount 自适应库大小（2026-07-23 实测库已 117K，固定 cap 追不上增长）。
     const uptake = await computeSynthesisUptake(store, stats.totalCount + 1_000);
+    // 两行两个口径（2026-09-09）：第一行是老数字，保留可比但标明它可被检索刷高、只能读成
+    // "被碰过"；第二行 distinctReaderCount≥2 是更难被扰动的口径。判断"合成产物有没有用"看第二行。
     const uptakeLine = uptake.uptakeRate === null
-      ? "  uptake: n/a (no derived insights found)"
-      : `  uptake: ${(uptake.uptakeRate * 100).toFixed(1)}% (${uptake.derivedRead}/${uptake.derivedTotal} read ≥1)`;
+      ? "  touched ≥1: n/a (no derived insights found)"
+      : `  touched ≥1 (accessCount>0; every search hit counts — inflatable, not a usefulness signal): ${(uptake.uptakeRate * 100).toFixed(1)}% (${uptake.derivedRead}/${uptake.derivedTotal})`;
+    const multiReaderLine = uptake.multiReaderRate === null
+      ? "  read by ≥2 distinct readers: n/a"
+      : `  read by ≥2 distinct readers (harder to inflate — use this one): ${(uptake.multiReaderRate * 100).toFixed(1)}% (${uptake.derivedReadByMultiple}/${uptake.derivedTotal})`;
 
     const lines = [
       `Total entries: ${stats.totalCount}`,
@@ -575,6 +616,7 @@ registerTool(
       `Synthesis uptake${uptake.truncated ? ` (scan capped at ${uptake.scanned})` : ""}:`,
       `  derived insights: ${uptake.derivedTotal}`,
       uptakeLine,
+      multiReaderLine,
     ];
 
     return {
@@ -761,7 +803,7 @@ registerTool(
 
 registerTool(
   "retrieve_skill",
-  "Retrieve executable skills matching a task description by semantic similarity. Read-only. Use when you need a stored procedure to act on, not just recall knowledge.",
+  "Retrieve agent-readable runbooks matching a task description by semantic similarity. Read-only. RecallNest returns stored instructions; it does not execute them.",
   {
     query: z.string().min(1).max(300).describe("Natural language task description to match, e.g. 'deploy the app to production'"),
     scope: z.string().min(1).max(160).optional().describe("Restrict to skills in a specific scope, e.g. 'project:myapp'. Omit to search all scopes"),
@@ -838,17 +880,10 @@ registerTool(
       })),
     });
 
-    const counts = { new: 0, deduped: 0, updated: 0 };
-    for (const r of stored) {
-      if (r.disposition === "deduped") counts.deduped++;
-      else if (r.disposition === "updated") counts.updated++;
-      else counts.new++;
-    }
-
     return {
       content: [{
         type: "text" as const,
-        text: `Stored ${stored.length} memories (${counts.new} new, ${counts.deduped} deduped, ${counts.updated} updated)`,
+        text: formatBatchStoreReceipt(stored),
       }],
     };
   },

package/src/mcp-tools-core.ts

@@ -1,15 +1,17 @@
 import { z } from "zod";
 import { persistMemory } from "./capture-engine.js";
+import { formatStoreMemoryReceipt } from "./store-receipts.js";
 import { composeLightResumeContext, composeResumeContext } from "./context-composer.js";
 import { renderMemories } from "./context-renderer.js";
 import { formatSearchResults, formatBriefResults, formatFullResults, formatCollapsedResults } from "./memory-output.js";
-import { DurableMemoryCategorySchema, StoreMemorySourceSchema, PrivacyTierSchema, isPredictiveMemoryEnabled } from "./memory-schema.js";
+import { DurableMemoryCategorySchema, StoreMemorySourceSchema, PrivacyTierSchema, isPredictiveMemoryEnabled, MemoryTriggersSchema } from "./memory-schema.js";
 import type { PredictionContext } from "./prediction-engine.js";
 import { setReminder, checkTriggers, fireReminder, suggestPredictedReminders, formatSuggestedReminders } from "./prospective-memory.js";
 import { resolveRecallMode } from "./runtime-config.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
 import { createScopeSuggester } from "./scope-suggester.js";
 import { buildSessionCheckpointResult } from "./session-engine.js";
+import { mirrorCheckpointWithDeadline } from "./checkpoint-mirror.js";
 import { formatCheckpointSaved, formatCheckpointSummary, formatResumeContext } from "./session-output.js";
 import { matchesTemporalConstraint, type TemporalConstraint } from "./temporal-parser.js";
 import { buildManagedCheckpointObservation, buildManagedResumeObservation } from "./workflow-observation-managed.js";
@@ -95,6 +97,7 @@ registerTool(
     canonicalKey: z.string().min(1).max(120).optional().describe("Optional stable key for merge/update semantics"),
     topicTag: z.string().min(1).max(60).optional().describe("Optional topic tag for intra-scope partitioning (e.g. 'auth', 'deploy', 'testing'). Auto-detected if omitted."),
     privacyTier: PrivacyTierSchema.default("durable").describe("Privacy tier: ephemeral (auto-expire, no KG), private (persist, no KG), durable (default), shared (cross-scope)"),
+    triggers: MemoryTriggersSchema.describe("写入时预演触发器：这条记忆「她以后会怎么问起」的 2–5 句口语问法，各说一个角度、别互为变体、别复述正文。只参与召回、不进正文。scope 为 memory:pivot 时必填（§5.3）。例：[\"那个跑分要不要再跑一次\", \"别人的榜我们要不要也去排个名\"]"),
     validUntil: z.union([z.string(), z.number()]).optional().describe("Optional expiration: ISO date string or ms timestamp. Memory will be deprioritized after this time."),
     eventTime: z.union([z.string(), z.number()]).optional().describe("Optional event time: when the event actually happened (ISO date or ms), distinct from storage time."),
     confidence: z.union([
@@ -106,8 +109,8 @@ registerTool(
     ]).optional().describe("Optional confidence override: number (0-1) or {score, reliability}. Auto-assigned from source if omitted."),
     dependsOn: DependsOnSchema.optional().describe("Optional freshness dependencies (borrowed). Declare what this memory depends on so recall shows a cheap validity verdict (exact/compatible/uncertain/invalid). Items: {kind:'file'|'git-rev', ref, expected?}. file → ref=path, expected=mtime-ms string; git-rev → ref=repo path, expected=commit hash (short ok). expected may be an array: first=exact, rest=compatible set. Omit expected for existence-only checks."),
   },
-  async ({ text, category, importance, scope, source, tags, canonicalKey, topicTag, privacyTier, validUntil, eventTime, confidence, dependsOn }) => {
-    const { store, embedder } = getComponents();
+  async ({ text, category, importance, scope, source, tags, canonicalKey, topicTag, privacyTier, triggers, validUntil, eventTime, confidence, dependsOn }) => {
+    const { store, embedder, triggerStore } = getComponents();
     const kgExtractor = getKGExtractor();
     const stored = await persistMemory({
       store,
@@ -115,6 +118,8 @@ registerTool(
       conflictStore,
       kgExtractor,
       auditLogger,
+      triggerStore,
+      embedQueryBatch: (texts: string[]) => embedder.embedBatchQuery(texts),
     }, {
       text,
       category,
@@ -125,6 +130,7 @@ registerTool(
       canonicalKey,
       topicTag,
       privacyTier,
+      triggers,
       // F3: Pass temporal validity params (extracted by persistMemory before Zod parse)
       validUntil,
       eventTime,
@@ -137,16 +143,7 @@ registerTool(
     return {
       content: [{
         type: "text" as const,
-        text: [
-          `Stored memory ${stored.id.slice(0, 8)}`,
-          `Disposition: ${stored.disposition}`,
-          ...(stored.rejectionReason ? [`Rejection reason: ${stored.rejectionReason}`] : []),
-          `Category: ${stored.category}`,
-          `Scope: ${stored.resolvedScope}`,
-          `Canonical key: ${stored.canonicalKey}`,
-          ...(stored.conflictId ? [`Conflict: ${stored.conflictId.slice(0, 8)}`] : []),
-          `Stored at: ${stored.storedAt}`,
-        ].join("\n"),
+        text: formatStoreMemoryReceipt(stored, { requestedTriggers: triggers?.length ?? 0, scope }),
       }],
     };
   }
@@ -215,6 +212,11 @@ registerTool(
       ...result,
       record: storedRecord,
     }));
+    // Mirror into the memory table so search_memory can find it; never throws, capped wait.
+    await mirrorCheckpointWithDeadline(() => {
+      const { store, embedder } = getComponents();
+      return { store, embedder };
+    }, storedRecord);
     return {
       content: [{
         type: "text" as const,
@@ -332,7 +334,9 @@ registerTool(
       return {
         content: [{
           type: "text" as const,
-          text: lightResult.text,
+          text: lightResult.resolvedScope
+            ? `Scope: ${lightResult.resolvedScope}\n${lightResult.text}`
+            : lightResult.text,
         }],
       };
     }
@@ -373,11 +377,11 @@ registerTool(
 
 registerTool(
   "search_memory",
-  "Search indexed memories by hybrid relevance (vector + BM25 + reranking) and return ranked results with optional temporal filtering. The shown score is a fused ranking score (0-100%), NOT pure cosine similarity — read it as relative ranking within this result set, not as match confidence. Read-only, but may fire stored reminders as a side effect. Use proactively at the start of tasks, when debugging, writing, or when the user references past work.",
+  "Search indexed memories by semantic relevance (vector search + reranking; BM25 keyword fusion runs only when retrieval.mode is \"hybrid\", and the default is vector-only) and return ranked results with optional temporal filtering. With the default mode there is no keyword channel, so exact identifiers such as commit hashes or variable names may not surface — use a raw-text search for those. The shown score is a fused ranking score (0-100%), NOT pure cosine similarity — read it as relative ranking within this result set, not as match confidence. Read-only, but may fire stored reminders as a side effect. Use proactively at the start of tasks, when debugging, writing, or when the user references past work.",
   {
     query: z.string().describe("Search query — natural language or keywords"),
     limit: z.number().min(1).max(20).default(5).describe("Max results to return"),
-    scope: z.string().optional().describe("Optional explicit scope"),
+    scope: z.string().optional().describe("Explicit scope; reuse Scope returned by resume_context. May be omitted when sessionId or configured environment supplies a scope, or allScopes=true explicitly requests cross-scope search. Omission alone does not mean global search."),
     sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier to infer session:<id> scope"),
     allScopes: z.boolean().default(false).describe("When true, explicitly allow cross-scope search"),
     includeRelatedScopes: z.boolean().default(false).describe("When true, also query configured related scopes from scopeRelations and show them in a separate sidecar section. Requires an explicit or inferred scoped search; never changes the main result ranking."),
@@ -389,7 +393,7 @@ registerTool(
     graph: z.boolean().default(false).optional().describe("Enable KG graph traversal (PPR) for relationship-aware search. Use when query involves entity relationships (e.g. 'what tools does Alice use', 'Bob的朋友')."),
     includeArchived: z.boolean().default(false).optional().describe("When true, also return archived/superseded/consolidated memories (default: only active)"),
     detail_level: z.enum(["brief", "normal", "full", "adaptive"]).default("normal").optional()
-      .describe("Result detail level: brief (ID+score+one-liner), normal (default, table), full (include metadata), adaptive (per-result L0/L1/L2 fidelity by relevance within an 8k token budget — high-relevance gets full text, lower gets summary/one-line)"),
+      .describe("Result detail level: normal (default — the full text of each hit, in rank order. One entry is capped at 2400 chars. Full text is handed out until an 8k-token budget is used up; hits past that point get a query-aware snippet instead of being dropped, so a long list can run past 8k by one snippet per remaining hit, and each related-scope block has its own budget. Any shortened entry says how much of it is shown and gives the id for memory_drill_down), brief (ID+score+one-liner), full (table with 120-char snippets plus extra metadata), adaptive (full text only for hits scoring above the threshold, query-aware snippet for the rest, 8k-token budget)"),
     topicTag: z.string().min(1).max(60).optional()
       .describe("Filter by topic tag (e.g. 'auth', 'deploy', 'testing'). Only returns memories tagged with this topic."),
     reconstruct: z.boolean().default(false).describe(
@@ -531,6 +535,8 @@ registerTool(
           includeArchived,
           topicTag,
           source: "auto-recall",
+          // 旁路标 auto-recall 只为不做强化写入；查询本身是人发起的，不过琐碎查询闸
+          trivialQueryGate: false,
           validAt: validAt ? new Date(validAt).getTime() : undefined,
           includeExpired: includeExpired ?? undefined,
         }, {

package/src/mcp-tools-governance.ts

@@ -7,7 +7,7 @@ import { CONFLICT_ATTENTION_LEVELS, summarizeConflictLifecycle } from "./conflic
 import { formatConflictAudit, formatConflictClusters, formatConflictEscalation, formatConflictList, formatConflictRecord, formatConflictResolution } from "./conflict-output.js";
 import { ConflictStatusSchema } from "./conflict-schema.js";
 import { ConsolidationEngine, formatConsolidationResult } from "./consolidation-engine.js";
-import { archiveDirtyBriefAsset, listDirtyBriefAssets } from "./memory-assets.js";
+import { archiveDirtyBriefAsset, formatDirtyBriefEmptyMessage, formatDirtyBriefReadErrors, scanDirtyBriefAssets } from "./memory-assets.js";
 import {
   scanMemoryPromotions,
   scanSynthesisPromotions,
@@ -266,15 +266,18 @@ registerTool(
   "List memory briefs generated before current cleanup rules that may need re-indexing. Read-only. Use when auditing brief quality or before running clean_dirty_briefs.",
   {},
   async () => {
-    const rows = listDirtyBriefAssets();
+    const scan = scanDirtyBriefAssets();
+    const rows = scan.items;
     if (rows.length === 0) {
-      return { content: [{ type: "text" as const, text: "No dirty briefs found." }] };
+      return { content: [{ type: "text" as const, text: formatDirtyBriefEmptyMessage(scan) }] };
     }
     const lines = [
       "Brief ID  Title  Scope  Reasons",
       "--------  -----  -----  ----------------------------------------",
       ...rows.map(row => `${row.id.slice(0, 8)}  ${row.title}  [${row.scope}]  ${row.reasons.join("; ")}`),
     ];
+    const readErrors = formatDirtyBriefReadErrors(scan.readErrors);
+    if (readErrors) lines.push("", readErrors);
     return { content: [{ type: "text" as const, text: lines.join("\n") }] };
   }
 );
@@ -287,9 +290,12 @@ registerTool(
   },
   async ({ apply }) => {
     const { store } = getComponents();
-    const rows = listDirtyBriefAssets();
+    const scan = scanDirtyBriefAssets();
+    const rows = scan.items;
+    const readErrors = formatDirtyBriefReadErrors(scan.readErrors);
+    const readErrorsTail = readErrors ? `\n\n${readErrors}` : "";
     if (rows.length === 0) {
-      return { content: [{ type: "text" as const, text: "No dirty briefs found." }] };
+      return { content: [{ type: "text" as const, text: formatDirtyBriefEmptyMessage(scan) }] };
     }
 
     if (!apply) {
@@ -297,7 +303,7 @@ registerTool(
       return {
         content: [{
           type: "text" as const,
-          text: `Dirty briefs detected: ${rows.length}\n\n${preview}\n\nCall clean_dirty_briefs with apply=true to archive them.`,
+          text: `Dirty briefs detected: ${rows.length}\n\n${preview}\n\nCall clean_dirty_briefs with apply=true to archive them.${readErrorsTail}`,
         }],
       };
     }
@@ -321,7 +327,7 @@ registerTool(
     return {
       content: [{
         type: "text" as const,
-        text: `Dirty briefs: ${rows.length}\nArchived: ${archived}\nIndex rows deleted: ${deleted}`,
+        text: `Dirty briefs: ${rows.length}\nArchived: ${archived}\nIndex rows deleted: ${deleted}${readErrorsTail}`,
       }],
     };
   }

package/src/memory-assets.ts

@@ -76,6 +76,7 @@ const DATA_DIR = resolve(metaDir(import.meta), "../data");
 const PINS_DIR = join(DATA_DIR, "pins");
 const ASSETS_DIR = join(DATA_DIR, "assets");
 const ARCHIVE_DIR = join(DATA_DIR, "archive", "dirty-briefs");
+const FORGOTTEN_PINS_DIR = join(DATA_DIR, "archive", "forgotten-pins");
 const EXPORTS_DIR = join(DATA_DIR, "exports");
 
 function ensureDir(dir: string): string {
@@ -112,6 +113,7 @@ function retrievalPath(result: RetrievalResult): string {
   if (result.sources.vector) parts.push("vector");
   if (result.sources.bm25) parts.push("bm25");
   if (result.sources.reranked) parts.push("reranked");
+  if (result.sources.trigger) parts.push("trigger");
   return parts.join("+") || "direct";
 }
 
@@ -231,7 +233,98 @@ export function listPinAssets(limit = 20): Array<PinAsset & { path: string }> {
   return items;
 }
 
-function listJsonRecords<T extends MemoryAsset>(dir: string, limit = 20): Array<T & { path: string }> {
+/**
+ * 来源是这条记忆的 pin 文件（不限条数）。pins 目录不存在就返回空，不顺手建目录。
+ *
+ * 「读不了」和「读出来不是 JSON」分开处理：
+ * - 读不了（EIO、EACCES、iCloud 占位文件的 EDEADLK……）直接抛出。说不清这个文件属于谁，
+ *   就不能当它不存在——forget 靠这里判断「还有没有 pin」，吞掉错误等于谎报没有。
+ * - 不是 JSON 的跳过：list_pins 和 resume_context 同样读不了它，它进不了任何输出。
+ */
+export function findPinAssetsForMemory(
+  memoryId: string,
+  pinsDir: string = PINS_DIR,
+): Array<PinAsset & { path: string }> {
+  if (!existsSync(pinsDir)) return [];
+  const items: Array<PinAsset & { path: string }> = [];
+  for (const dirent of readdirSync(pinsDir, { withFileTypes: true })) {
+    if (dirent.isDirectory() || !dirent.name.endsWith(".json")) continue;
+    const path = join(pinsDir, dirent.name);
+    const raw = readFileSync(path, "utf-8");
+    let parsed: PinAsset;
+    try {
+      parsed = JSON.parse(raw) as PinAsset;
+    } catch {
+      continue;
+    }
+    if (parsed?.source?.memoryId === memoryId) items.push({ ...parsed, path });
+  }
+  return items;
+}
+
+/**
+ * archivePinAssetsForMemory 挪到一半出错时抛这个。已经挪走的不挪回去：数量与新路径带在错误上，
+ * 调用方（forget 引擎）据此如实报「已经动过什么」，而不是当作什么都没发生。
+ */
+export class PinArchiveIncompleteError extends Error {
+  /** 出错之前已经挪到归档目录的文件（新路径）。 */
+  readonly archived: string[];
+  /** 同上，条数。forget 引擎按这个字段名读（ForgetPinArchive 的约定）。 */
+  readonly archivedCount: number;
+
+  constructor(cause: unknown, archived: string[], total: number) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(`${reason} (${archived.length} of ${total} pin file(s) had already been moved to the archive)`, { cause });
+    this.name = "PinArchiveIncompleteError";
+    this.archived = [...archived];
+    this.archivedCount = archived.length;
+  }
+}
+
+/**
+ * 把来源是这条记忆的 pin 挪出 pins 目录（forget 用）。
+ *
+ * pin 文件是记忆正文的一份拷贝（标题、摘要、320 字片段），会被 list_pins 列出、被 resume_context
+ * 拼进上下文；记忆被 forget 之后它不该继续出现。这里挪到 data/archive/forgotten-pins/ 而不是删：
+ * 文件离开了会被读到的目录，误删时还能挪回。同名不覆盖。
+ * 返回挪到的新路径。读不了或挪不动就抛错，由调用方决定要不要继续；已经挪走几个之后才出错的，
+ * 抛 PinArchiveIncompleteError，已挪走的数量与新路径带在错误上（不挪回去）。
+ *
+ * 只管文件这一半。pin 在主表里还有一行可检索的索引副本（asset-sync.ts），那一半由
+ * forget 引擎在同一步里删。
+ */
+export function archivePinAssetsForMemory(
+  memoryId: string,
+  dirs: { pinsDir?: string; archiveDir?: string } = {},
+): string[] {
+  const matches = findPinAssetsForMemory(memoryId, dirs.pinsDir ?? PINS_DIR);
+  if (matches.length === 0) return [];
+  const archiveDir = ensureDir(dirs.archiveDir ?? FORGOTTEN_PINS_DIR);
+  const moved: string[] = [];
+  for (const asset of matches) {
+    const stem = basename(asset.path, ".json");
+    let target = join(archiveDir, `${stem}.json`);
+    for (let n = 2; existsSync(target); n++) {
+      target = join(archiveDir, `${stem}-${n}.json`);
+    }
+    try {
+      renameSync(asset.path, target);
+    } catch (err) {
+      // 第一个就挪不动：什么都没变，原样抛。后面的才挪不动：前面的已经离开 pins 目录了，得让调用方知道。
+      if (moved.length === 0) throw err;
+      throw new PinArchiveIncompleteError(err, moved, matches.length);
+    }
+    moved.push(target);
+  }
+  return moved;
+}
+
+export interface AssetReadError {
+  path: string;
+  reason: string;
+}
+
+function readJsonRecords<T extends MemoryAsset>(dir: string, limit = 20): { items: Array<T & { path: string }>; readErrors: AssetReadError[] } {
   ensureDir(dir);
   const files = readdirSync(dir)
     .filter(name => name.endsWith(".json"))
@@ -240,15 +333,21 @@ function listJsonRecords<T extends MemoryAsset>(dir: string, limit = 20): Array<
     .slice(0, limit);
 
   const items: Array<T & { path: string }> = [];
+  const readErrors: AssetReadError[] = [];
   for (const path of files) {
     try {
       const parsed = JSON.parse(readFileSync(path, "utf-8")) as T;
       items.push({ ...parsed, path });
-    } catch {
-      // Skip corrupt records.
+    } catch (err) {
+      readErrors.push({ path, reason: err instanceof Error ? err.message : String(err) });
     }
   }
-  return items;
+  return { items, readErrors };
+}
+
+function listJsonRecords<T extends MemoryAsset>(dir: string, limit = 20): Array<T & { path: string }> {
+  // 读不了的文件在这里照旧跳过；要知道有哪些读不了，用 readJsonRecords。
+  return readJsonRecords<T>(dir, limit).items;
 }
 
 export function listBriefAssets(limit = 20): Array<BriefAsset & { path: string }> {
@@ -275,8 +374,14 @@ function detectDirtyBriefReasons(asset: BriefAsset): string[] {
   return reasons;
 }
 
-export function listDirtyBriefAssets(limit = 200): DirtyBriefAssetRecord[] {
-  return listBriefAssets(limit)
+export interface DirtyBriefScan {
+  items: DirtyBriefAssetRecord[];
+  /** 读取或解析失败的文件：没有判定、不会被归档，原样留在资产目录里。 */
+  readErrors: AssetReadError[];
+}
+
+function toDirtyBriefRecords(assets: Array<BriefAsset & { path: string }>): DirtyBriefAssetRecord[] {
+  return assets
     .map((asset) => {
       const reasons = detectDirtyBriefReasons(asset);
       return {
@@ -288,8 +393,39 @@ export function listDirtyBriefAssets(limit = 200): DirtyBriefAssetRecord[] {
     .filter((asset) => asset.reasons.length > 0);
 }
 
-export function archiveDirtyBriefAsset(asset: DirtyBriefAssetRecord): string {
-  const dir = getDirtyBriefArchiveDir();
+export function scanDirtyBriefAssets(limit = 200, assetsDir?: string): DirtyBriefScan {
+  const { items, readErrors } = readJsonRecords<BriefAsset>(assetsDir ?? getAssetsDir(), limit);
+  return { items: toDirtyBriefRecords(items), readErrors };
+}
+
+export function listDirtyBriefAssets(limit = 200): DirtyBriefAssetRecord[] {
+  return scanDirtyBriefAssets(limit).items;
+}
+
+/**
+ * 脏 brief 扫描结果里「没有要清的」那句话。有文件读不了时不说「没有」，
+ * 免得把坏文件藏起来：真干净才回 "No dirty briefs found."。
+ */
+export function formatDirtyBriefEmptyMessage(scan: DirtyBriefScan): string {
+  if (scan.readErrors.length === 0) return "No dirty briefs found.";
+  return [
+    "No dirty briefs among readable files, but the scan is incomplete.",
+    formatDirtyBriefReadErrors(scan.readErrors),
+  ].join("\n");
+}
+
+/** 读不了的文件清单；没有读取失败时返回空串。 */
+export function formatDirtyBriefReadErrors(readErrors: AssetReadError[]): string {
+  if (readErrors.length === 0) return "";
+  const noun = readErrors.length === 1 ? "file" : "files";
+  return [
+    `${readErrors.length} brief ${noun} could not be read (left in place, not archived):`,
+    ...readErrors.map((item) => `  ${item.path} — ${item.reason}`),
+  ].join("\n");
+}
+
+export function archiveDirtyBriefAsset(asset: DirtyBriefAssetRecord, archiveDir?: string): string {
+  const dir = archiveDir ? ensureDir(archiveDir) : getDirtyBriefArchiveDir();
   const targetPath = join(dir, basename(asset.path));
   renameSync(asset.path, targetPath);
   return targetPath;

package/src/memory-boundaries.ts

@@ -99,6 +99,25 @@ export function isTranscriptScope(scope: string): boolean {
   return TRANSCRIPT_SCOPE_PREFIXES.some((prefix) => scope.startsWith(prefix));
 }
 
+/**
+ * Scope of the session-checkpoint mirror (src/checkpoint-mirror.ts): one `events` row per session.
+ * Lives here so the retriever can refer to it without importing the mirror module.
+ */
+export const CHECKPOINT_MIRROR_SCOPE = "checkpoint";
+
+/**
+ * Scopes a retrieval must keep out of its candidate pool. The vector / BM25 candidate pool is
+ * cut to at most 20 rows before the category filter runs, so rows that the category filter is
+ * certain to drop still take candidate slots from the rows it would keep. Mirror rows are all
+ * `events`; any other category filter therefore drops every one of them — excluding the scope up
+ * front is lossless and keeps category searches as they were before the mirror existed.
+ */
+export function resolveExcludedScopes(params: { category?: string; excludeScopes?: string[] }): string[] {
+  const excluded = new Set(params.excludeScopes ?? []);
+  if (params.category && params.category !== "events") excluded.add(CHECKPOINT_MIRROR_SCOPE);
+  return [...excluded];
+}
+
 export function isDurableMemoryScope(scope: string): boolean {
   return scope.startsWith("memory:") || scope.startsWith("asset:");
 }

package/src/memory-evolution.ts

@@ -158,6 +158,15 @@ export function recordAccess(metadata: string | undefined): string {
   });
 }
 
+/**
+ * recordAccess 的对象版：给 patchMetadataBatch 的 patchFn 用——在写锁内、以库里最新的元数据为底座加访问计数，
+ * 不再拿检索时读到的元数据整行写回（那样会把检索与写回之间别的进程写下的状态盖掉）。
+ */
+export function recordAccessOnMeta(meta: Record<string, unknown>, now: number = Date.now()): Record<string, unknown> {
+  const evo = parseEvolution(JSON.stringify(meta));
+  return patchEvolutionOnMeta(meta, { accessCount: evo.accessCount + 1, lastAccessedAt: now });
+}
+
 // ---------------------------------------------------------------------------
 // Supersede / Consolidate helpers
 // ---------------------------------------------------------------------------