dsh-continual-evolve 0.7.5 → 0.8.0

package/lib/command.js

@@ -1,5 +1,6 @@
-import { ARCHIVED_AT_KEY } from "./types.js";
+import { ARCHIVED_AT_KEY, MEMORY_TYPE_KEY } from "./types.js";
 import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
+import { compactText } from "./render.js";
 import { planWithLlm } from "./planner.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -18,6 +19,7 @@ import { projectKeyOf } from "./project.js";
 import { loadUsage, getUsageCount } from "./usage.js";
 import { loadGateRuntime, saveGateRuntime } from "./runtime.js";
 import { planConsolidation } from "./consolidate.js";
+import { formatRecallResult, recallMemories, RECALL_MEMORY_TYPES } from "./recall.js";
 import { loadTokenUsage, renderTokenUsageReport } from "./token-usage.js";
 const USAGE = `Usage:
   /evolve                  show this help and the current local store
@@ -30,6 +32,12 @@ const USAGE = `Usage:
   /evolve archive <id> [global]   hide an entry from injection (data kept, restorable)
   /evolve unarchive <id> [global] restore an archived entry
   /evolve demote <id>             hide a (global) entry from injection, keep data
+  /evolve recall <query...> [scope] targeted memory recall: full content with version,
+                                   source, and staleness (same engine as the evolve_recall tool)
+  /evolve remember <type> [scope] <text...>
+                                   immediately persist one memory (type = user|feedback|project|reference;
+                                   feedback/project text must carry Why + How; default scope local)
+  /evolve forget [scope] <query...> locate one memory by query and archive it (restorable via /evolve unarchive)
   /evolve consolidate [apply] [merge]
                                   report (or apply) a batch archive of conflict-hinted
                                   and stale zero-use global entries; "merge" folds
@@ -206,6 +214,90 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 }, { scope });
                 return success(renderResult(result));
             }
+            case "recall": {
+                // Human counterpart of the evolve_recall tool: same engine,
+                // same filters (memory kind, one scope or all three).
+                const { scope, rest: after } = scopeArg(rest);
+                const explicitScope = rest.length > 0 && (rest[0] === "global" || rest[0] === "project" || rest[0] === "local");
+                const query = after.join(" ");
+                const result = recallMemories(engine, { sessionId, projectKey: projectKeyOf(invocation.agent) ?? undefined }, { kinds: ["memory"], ...(explicitScope ? { scopes: [scope] } : {}), ...(query ? { query } : {}), limit: 10 });
+                return success(formatRecallResult(result, query || undefined));
+            }
+            case "remember": {
+                // Immediate manual memory path (P1 §6.6): one fact, explicit
+                // type, straight into the engine — validation, snapshot,
+                // versioning, and approval behave exactly like any other
+                // write. feedback/project text must already carry Why + How;
+                // the engine rejects it loudly otherwise.
+                const type = rest[0] ?? "";
+                if (!RECALL_MEMORY_TYPES.includes(type)) {
+                    return error(`remember requires a memory type: user|feedback|project|reference.\nExample: /evolve remember feedback local 对方偏好深色主题。Why：…… How to apply：……\n${USAGE}`);
+                }
+                const maybeScope = rest[1] ?? "";
+                const scoped = maybeScope === "global" || maybeScope === "project" || maybeScope === "local";
+                const scope = scoped ? maybeScope : "local";
+                const text = (scoped ? rest.slice(2) : rest.slice(1)).join(" ").trim();
+                if (!text) {
+                    return error(`remember requires the memory text after the type.\n${USAGE}`);
+                }
+                const storeId = storeIdForCommand(scope, invocation);
+                if ((scope === "global" || scope === "project") && opts.requireGlobalApproval) {
+                    await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve remember ${type} → ${scope} store: ${compactText(text, 120)}`);
+                }
+                const result = engine.apply(scope, storeId, {
+                    summary: `remember: ${compactText(text, 80)}`,
+                    rationale: "Human-invoked immediate memory via /evolve remember.",
+                    expectedOutcome: "The fact is persisted as a typed memory entry.",
+                    edits: [{
+                            action: "create",
+                            kind: "memory",
+                            title: compactText(text, 80),
+                            content: text,
+                            metadata: { [MEMORY_TYPE_KEY]: type },
+                        }],
+                }, { scope });
+                return success(renderResult(result));
+            }
+            case "forget": {
+                // Manual forget path (P1 §6.6): locate by query, archive the
+                // single match (restorable via unarchive). An ambiguous query
+                // lists candidates instead of archiving — a silent multi-
+                // archive would look like success while hiding too much.
+                const { scope, rest: after } = scopeArg(rest);
+                const explicitScope = rest.length > 0 && (rest[0] === "global" || rest[0] === "project" || rest[0] === "local");
+                const query = after.join(" ").trim();
+                if (!query) {
+                    return error(`forget requires a query to locate the memory.\n${USAGE}`);
+                }
+                const recalled = recallMemories(engine, { sessionId, projectKey: projectKeyOf(invocation.agent) ?? undefined }, { query, kinds: ["memory"], ...(explicitScope ? { scopes: [scope] } : {}), limit: 6, includeArchived: false });
+                if (recalled.hits.length === 0) {
+                    return error(`no memory matches "${query}"${recalled.notes.length > 0 ? ` (${recalled.notes.join("; ")})` : ""} — try fewer words, or /evolve list to browse.`);
+                }
+                if (recalled.hits.length > 1) {
+                    const list = recalled.hits.map((hit) => `- [${hit.scope}:${hit.id}] ${hit.title}`).join("\n");
+                    return success(`"${query}" matches ${recalled.hits.length} memories — refine the query so exactly one matches, then forget archives it:\n${list}`);
+                }
+                const hit = recalled.hits[0];
+                const state = engine.load(hit.scope, hit.scope === "local" ? sessionId : hit.scope === "project" ? (projectKeyOf(invocation.agent) ?? undefined) : undefined);
+                const entry = state.entries.memory[hit.id];
+                if (!entry) {
+                    return error(`memory ${hit.scope}:${hit.id} vanished since recall — run /evolve forget again.`);
+                }
+                const result = engine.apply(hit.scope, hit.scope === "local" ? sessionId : hit.scope === "project" ? (projectKeyOf(invocation.agent) ?? undefined) : undefined, {
+                    summary: `forget: archive memory ${hit.scope}:${hit.id}`,
+                    rationale: `Human-invoked forget via /evolve forget "${query}".`,
+                    expectedOutcome: "The entry is hidden from injection (data kept; restorable via /evolve unarchive).",
+                    edits: [{
+                            action: "update",
+                            kind: "memory",
+                            id: hit.id,
+                            title: entry.title,
+                            content: entry.content,
+                            metadata: { ...entry.metadata, [ARCHIVED_AT_KEY]: new Date().toISOString() },
+                        }],
+                }, { scope: hit.scope });
+                return success(`forgot [${hit.scope}:${hit.id}] ${hit.title} (archived — restore with /evolve unarchive ${hit.id}${hit.scope === "local" ? "" : ` ${hit.scope}`})\n${renderResult(result)}`);
+            }
             case "consolidate": {
                 // R3: deterministic global-store hygiene. Report by default;
                 // `apply` re-scans fresh state and lands the whole batch as ONE
@@ -376,10 +468,6 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
             }
             case "pause":
             case "resume": {
-                if (runtime.autoReview === false) {
-                    return success("automatic evolution wiring is disabled by project policy; no automatic Memory Agent listener is registered. Manual evolve_* tools and /evolve commands keep working.");
-                }
-                const memoryOnly = runtime.memoryOnly !== false;
                 // The switch is independent of the static registration flag. A
                 // resume explicitly enables the Memory Agent; a pause leaves the
                 // enable bit intact so status explains the paused state.
@@ -390,7 +478,7 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     return success("automatic Memory Agent is already paused (no change).");
                 }
                 if (!pausing && current.enabled && !current.paused) {
-                    return success(memoryOnly ? "automatic Memory Agent is already running (no change)." : "automatic evolution is already running (no change).");
+                    return success("automatic Memory Agent is already running (no change).");
                 }
                 saveGateRuntime(engine.baseDir, pausing, pausing ? current.enabled : true);
                 return success(pausing
@@ -468,16 +556,12 @@ function demoteEntry(engine, id, sessionId, projectKey) {
 function renderGateStatus(engine, sessionId, projectKey, runtime) {
     const configuredDefault = runtime.autoReview === undefined ? "unknown" : runtime.autoReview ? "on" : "off";
     const current = loadGateRuntime(engine.baseDir, runtime.autoReview ?? false);
-    const memoryOnly = runtime.memoryOnly !== false;
-    const effective = runtime.autoReview === false
-        ? "disabled by project policy"
-        : current.paused
-            ? "PAUSED (resume with /evolve resume)"
-            : current.enabled
-                ? memoryOnly ? "Memory Agent running" : "running"
-                : memoryOnly ? "Memory Agent off (enable with /evolve resume)" : "off (enable with /evolve resume)";
-    const listener = runtime.autoReview === false ? "not wired" : memoryOnly ? "Memory Agent-only listener registered" : "listener registered";
-    const gateLine = `gate: ${listener} · config default ${configuredDefault} · runtime ${effective}`;
+    const effective = current.paused
+        ? "PAUSED (resume with /evolve resume)"
+        : current.enabled
+            ? "Memory Agent running"
+            : "Memory Agent off (enable with /evolve resume)";
+    const gateLine = `gate: Memory Agent-only listener registered · config default ${configuredDefault} · runtime ${effective}`;
     const countEntries = (state) => Object.values(state.entries).reduce((n, byKind) => n + Object.keys(byKind).length, 0);
     const lines = [gateLine];
     lines.push(`stores: global ${countEntries(engine.load("global", undefined))} entries · local(${sessionId}) ${countEntries(engine.load("local", sessionId))} entries`);

package/lib/index.d.ts

@@ -10,10 +10,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     baseDir: z<string, string, "plain">;
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z<number, number, "defined">;
-    /** Explicit opt-in for the dedicated Memory Agent listener (off by default). */
+    /** Initial Memory Agent default when no `evolve/runtime.json` exists; not a registration gate. */
     autoReview: z<boolean, boolean, "defined">;
     /** ZCode-style minimum lexical words in one direct user text part. */
     memoryMinUserWords: z<number, number, "defined">;
+    /**
+     * Session-close bounded drain for in-flight extraction, in milliseconds.
+     * Absent → 15s; 0 restores the legacy immediate abort on dispose.
+     */
+    sessionCloseDrainMs: z<number, number, "defined">;
     /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z<number, number, "defined">;
     /** Trajectory slice handed to the gate, in characters. */
@@ -110,10 +115,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     baseDir: z<string, string, "plain">;
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z<number, number, "defined">;
-    /** Explicit opt-in for the dedicated Memory Agent listener (off by default). */
+    /** Initial Memory Agent default when no `evolve/runtime.json` exists; not a registration gate. */
     autoReview: z<boolean, boolean, "defined">;
     /** ZCode-style minimum lexical words in one direct user text part. */
     memoryMinUserWords: z<number, number, "defined">;
+    /**
+     * Session-close bounded drain for in-flight extraction, in milliseconds.
+     * Absent → 15s; 0 restores the legacy immediate abort on dispose.
+     */
+    sessionCloseDrainMs: z<number, number, "defined">;
     /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z<number, number, "defined">;
     /** Trajectory slice handed to the gate, in characters. */
@@ -215,7 +225,5 @@ export interface EvolutionService {
     readonly engine: EvolutionEngine;
     readonly baseDir: string;
 }
-/** True only when the project explicitly opts into automatic evolution wiring. */
-export declare function automaticEvolutionWired(config: Pick<EvolveConfig, "autoReview">): boolean;
 export declare function apply(ctx: Context, config: EvolveConfig): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -3,10 +3,11 @@
  *
  * Mounts the evolution engine, registers the model-facing evolve_* tools,
  * the human-facing /evolve command, the system-prompt guidance section, and
- * (only under an explicit `autoReview: true` opt-in) the dedicated Memory
- * Agent listener. With the default `autoReview: false`, the automatic
- * turn/compaction listeners are not registered; manual tools and commands
- * remain available.
+ * the dedicated Memory Agent listener. The listener is always registered so
+ * an install works without profile edits; `autoReview` only supplies the
+ * initial default when `evolve/runtime.json` does not exist yet, and
+ * `/evolve pause|resume` own it afterwards. Generic review/planner/fate are
+ * not reachable from this listener.
  */
 import { join } from "node:path";
 import z from "@deepseek-ai/schemastery";
@@ -30,10 +31,15 @@ export const Config = z.object({
     baseDir: z.string(),
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z.natural().default(118),
-    /** Explicit opt-in for the dedicated Memory Agent listener (off by default). */
+    /** Initial Memory Agent default when no `evolve/runtime.json` exists; not a registration gate. */
     autoReview: z.boolean().default(false),
     /** ZCode-style minimum lexical words in one direct user text part. */
     memoryMinUserWords: z.natural().default(3),
+    /**
+     * Session-close bounded drain for in-flight extraction, in milliseconds.
+     * Absent → 15s; 0 restores the legacy immediate abort on dispose.
+     */
+    sessionCloseDrainMs: z.natural().default(15000),
     /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z.natural().default(6),
     /** Trajectory slice handed to the gate, in characters. */
@@ -121,10 +127,6 @@ export const Config = z.object({
         tokenUsage: z.natural(),
     }),
 });
-/** True only when the project explicitly opts into automatic evolution wiring. */
-export function automaticEvolutionWired(config) {
-    return config.autoReview === true;
-}
 export function apply(ctx, config) {
     const baseDir = resolveDshHome(config.baseDir);
     const skillsRoot = config.skillsDir ? expandHomePath(config.skillsDir) : join(baseDir, "skills");
@@ -171,7 +173,6 @@ export function apply(ctx, config) {
         autoCase: config.autoCase ?? true,
         promotionPolicy,
         autoReview: config.autoReview ?? false,
-        memoryOnly: config.autoReview === true,
     });
     // Plugin-owned file logging: every cordis log message lands in
     // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
@@ -186,36 +187,33 @@ export function apply(ctx, config) {
     void restoreMounted(ctx, baseDir).catch((cause) => {
         ctx.logger("continual-evolve").warn(`mount restore failed: ${cause instanceof Error ? cause.message : String(cause)}`);
     });
-    // `autoReview` is an explicit opt-in for the dedicated Memory Agent only.
-    // The general review/planner, prompt/skill writes, and local-fate phases
-    // are not reachable from this listener. Manual tools and commands remain
-    // available below.
-    if (automaticEvolutionWired(config)) {
-        registerAutoReview(ctx, engine, {
-            intervalTurns: config.reviewIntervalTurns ?? 6,
-            enabledByDefault: true,
-            memoryOnly: true,
-            memoryMinUserWords: config.memoryMinUserWords ?? 3,
-            maxInputChars: config.maxReviewInputChars ?? 40000,
-            budgetTokens: config.reviewBudgetTokens ?? 4096,
-            notifyOnAutoReview: config.notifyOnAutoReview ?? true,
-            localFate: config.localFate ?? false,
-            fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
-            goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
-            promotionPolicy,
-            autoCase: config.autoCase ?? true,
-            rubricKey,
-            ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
-            ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
-            requireGlobalApproval: config.requireGlobalApproval ?? true,
-            ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
-            ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
-        });
-        ctx.logger("continual-evolve").info("continual-evolve automatic listener registered (Memory Agent only; generic review/planner/fate disconnected)");
-    }
-    else {
-        ctx.logger("continual-evolve").info("continual-evolve automatic evolution wiring disabled (autoReview is not explicitly true; manual tools and commands remain available)");
-    }
+    // The Memory Agent listener is always registered: an install must work
+    // without profile edits, so `autoReview` is only the initial default when
+    // no `evolve/runtime.json` exists yet — `/evolve pause|resume` own the
+    // switch afterwards. The general review/planner, prompt/skill writes, and
+    // local-fate phases are not reachable from this listener.
+    registerAutoReview(ctx, engine, {
+        intervalTurns: config.reviewIntervalTurns ?? 6,
+        enabledByDefault: config.autoReview ?? false,
+        memoryOnly: true,
+        memoryMinUserWords: config.memoryMinUserWords ?? 3,
+        sessionCloseDrainMs: config.sessionCloseDrainMs ?? 15000,
+        maxInputChars: config.maxReviewInputChars ?? 40000,
+        budgetTokens: config.reviewBudgetTokens ?? 4096,
+        notifyOnAutoReview: config.notifyOnAutoReview ?? true,
+        localFate: config.localFate ?? false,
+        fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
+        goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
+        promotionPolicy,
+        autoCase: config.autoCase ?? true,
+        rubricKey,
+        ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
+        ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
+        requireGlobalApproval: config.requireGlobalApproval ?? true,
+        ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
+        ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
+    });
+    ctx.logger("continual-evolve").info("continual-evolve automatic listener registered (Memory Agent only; generic review/planner/fate disconnected)");
     ctx.logger("continual-evolve").info(`continual-evolve mounted (baseDir=${baseDir})`);
 }
 //# sourceMappingURL=index.js.map

package/lib/memory-agent.d.ts

@@ -54,7 +54,7 @@ export interface MemoryApplicationResult {
 /** Provider-facing schemas for the closed memory-only tool set. */
 export declare const MEMORY_AGENT_TOOL_SCHEMAS: readonly ToolSchema[];
 /** Instructions for the dedicated loop; model text is always untrusted. */
-export declare const MEMORY_AGENT_SYSTEM_PROMPT = "You are the dedicated background memory extraction agent for a continual-evolution harness.\n\nYou receive only an incremental conversation checkpoint and a frozen manifest of existing memory entries. Your entire job is to decide whether this checkpoint contains a durable fact worth remembering. Never propose prompt notes, skills, subagent specs, code changes, or general conversation summaries.\n\nRules:\n- Use memory_search before creating when the manifest may already cover the topic. Update an existing entry instead of creating a near-duplicate.\n- Every memory entry contains exactly one fact. Classify it with metadata.memoryType = user | feedback | project | reference.\n- feedback and project memories must state the fact, Why it matters, and How to apply it next time.\n- Never invent a user preference. Ground every proposal in the supplied conversation evidence and existing memory.\n- Every edit must have kind=memory, an explicit targetScope, and a coherent blastRadius.\n- targetScope=local is session staging. project persists within the current repository. global persists across projects. project/global require human approval before application.\n- update/delete/archive must name an existing id from the same targetScope. Prefer archive over delete when the fact is obsolete but should remain restorable.\n- You cannot read or write source files, call agents, use MCP, use the network, or mutate the harness directly. memory_propose is the only finish tool and never writes state itself.\n- If no durable memory is justified, call memory_propose with edits=[].\n- Always finish by calling memory_propose. Do not return unproposed prose.";
+export declare const MEMORY_AGENT_SYSTEM_PROMPT = "You are the dedicated background memory extraction agent for a continual-evolution harness.\n\nYou receive only an incremental conversation checkpoint and a frozen manifest of existing memory entries. Your entire job is to decide whether this checkpoint contains a durable fact worth remembering. Never propose prompt notes, skills, subagent specs, code changes, or general conversation summaries.\n\nRules:\n- Use memory_search before creating when the manifest may already cover the topic. Update an existing entry instead of creating a near-duplicate.\n- Every memory entry contains exactly one fact. Classify it with metadata.memoryType = user | feedback | project | reference.\n- feedback and project memories must state the fact, Why it matters, and How to apply it next time.\n- Never invent a user preference. Ground every proposal in the supplied conversation evidence and existing memory.\n- Every edit must have kind=memory, an explicit targetScope, and a coherent blastRadius.\n- targetScope=local is session staging. project persists within the current repository. global persists across projects. project/global require human approval before application.\n- update/delete/archive must name an existing id from the same targetScope. Prefer archive over delete when the fact is obsolete but should remain restorable.\n- Do not remember: code structure or file paths re-readable from the repository; git history, diffs, commit hashes, or CI logs; content already written in project instruction files; temporary session state, one-off debugging trails, or current task progress; model-only speculation without conversation evidence.\n- You cannot read or write source files, call agents, use MCP, use the network, or mutate the harness directly. memory_propose is the only finish tool and never writes state itself.\n- If no durable memory is justified, call memory_propose with edits=[].\n- Always finish by calling memory_propose. Do not return unproposed prose.";
 /** Build the frozen memory manifest from a merged harness view. */
 export declare function buildMemoryManifest(state: HarnessState): MemoryManifestEntry[];
 /** Render a bounded manifest index; full bodies remain available through memory_search. */

package/lib/memory-agent.js

@@ -84,6 +84,7 @@ Rules:
 - Every edit must have kind=memory, an explicit targetScope, and a coherent blastRadius.
 - targetScope=local is session staging. project persists within the current repository. global persists across projects. project/global require human approval before application.
 - update/delete/archive must name an existing id from the same targetScope. Prefer archive over delete when the fact is obsolete but should remain restorable.
+- Do not remember: code structure or file paths re-readable from the repository; git history, diffs, commit hashes, or CI logs; content already written in project instruction files; temporary session state, one-off debugging trails, or current task progress; model-only speculation without conversation evidence.
 - You cannot read or write source files, call agents, use MCP, use the network, or mutate the harness directly. memory_propose is the only finish tool and never writes state itself.
 - If no durable memory is justified, call memory_propose with edits=[].
 - Always finish by calling memory_propose. Do not return unproposed prose.`;

package/lib/memory-benchmark.d.ts

@@ -0,0 +1,76 @@
+import type { HarnessEntry } from "./types.js";
+/** One labeled fact the extractor should (or, when outdated, should not) produce. */
+export interface MemoryBenchmarkFact {
+    id: string;
+    memoryType: string;
+    /** Key phrases; an edit matches when its title+content carry every phrase. */
+    mustContain: string[];
+    /** Outdated facts must be avoided (create/update) or removed (archive/delete). */
+    outdated?: boolean;
+}
+export interface MemoryBenchmarkReference {
+    facts: MemoryBenchmarkFact[];
+}
+/** One proposed edit in the shape the memory loop emits. */
+export interface MemoryBenchmarkEdit {
+    action: "create" | "update" | "delete" | "archive";
+    title?: string;
+    content?: string;
+    /** Target entry id for update/delete/archive. */
+    id?: string;
+}
+export interface ScoredMemoryBenchmarkEdit {
+    action: MemoryBenchmarkEdit["action"];
+    matchedFactIds: string[];
+    duplicateOf?: string;
+    staleReason?: string;
+    noisyReason?: string;
+}
+export interface MemoryBenchmarkScore {
+    totalEdits: number;
+    matchedFacts: number;
+    precision: number;
+    recall: number;
+    duplicate: number;
+    stale: number;
+    noise: number;
+    uncoveredFactIds: string[];
+    edits: ScoredMemoryBenchmarkEdit[];
+}
+export interface MemoryGradeThresholds {
+    minPrecision: number;
+    minRecall: number;
+    maxDuplicate: number;
+    maxStale: number;
+    maxNoise: number;
+}
+/** Strict-by-default gate: duplicates and stale operations never pass unnoticed. */
+export declare const DEFAULT_MEMORY_GRADE_THRESHOLDS: MemoryGradeThresholds;
+/**
+ * v1 exclusion heuristics for noise ("不该记什么" in mechanical form):
+ * git history, repo paths re-readable from disk, stack traces, and
+ * explicitly temporary session state. Keep this list short and documented —
+ * every pattern here is a precision/recall tradeoff, not ground truth.
+ */
+export declare const MEMORY_NOISE_PATTERNS: readonly RegExp[];
+/** Content shorter than this is too thin to be a durable fact. */
+export declare const MEMORY_MIN_FACT_CHARS = 30;
+/**
+ * Score one proposal against the reference and the pre-extraction manifest.
+ *
+ * @param reference Labeled facts (live + outdated).
+ * @param edits The proposal's memory edits.
+ * @param manifest Memory entries visible before extraction (duplicate source).
+ * @returns Per-dimension counts plus a per-edit breakdown.
+ */
+export declare function scoreMemoryExtraction(reference: MemoryBenchmarkReference, edits: readonly MemoryBenchmarkEdit[], manifest: readonly HarnessEntry[]): MemoryBenchmarkScore;
+/**
+ * Grade a score against explicit thresholds.
+ *
+ * @returns pass plus one failure line per violated dimension (empty when passing).
+ */
+export declare function gradeMemoryScore(score: MemoryBenchmarkScore, thresholds?: MemoryGradeThresholds): {
+    pass: boolean;
+    failures: string[];
+};
+//# sourceMappingURL=memory-benchmark.d.ts.map

package/lib/memory-benchmark.js

@@ -0,0 +1,170 @@
+/**
+ * Memory-specific extraction benchmark (P1): deterministic scoring of one
+ * memory proposal against a labeled reference.
+ *
+ * Unlike the harness benchmark (which runs subagents against rubrics), this
+ * module scores a proposal's SHAPE without any model call: precision and
+ * recall over reference facts, duplicate creates (update-first violations),
+ * stale operations (re-proposing outdated facts, or removing live ones), and
+ * noise (unmatched or exclusion-list material). Suite authors hand-build
+ * small references plus transcripts; the extraction loop under test produces
+ * the proposal, this module grades it.
+ *
+ * Matching is phrase-substring based (case-insensitive): a reference fact
+ * lists must-contain phrases, and a proposed edit matches when its title
+ * plus content carry every phrase. Deliberately mechanical — the benchmark
+ * measures extraction coverage, not paraphrase quality.
+ */
+import { CONFLICT_BLOCK_SCORE, mostSimilarEntry } from "./promotion.js";
+import { isArchived } from "./types.js";
+/** Strict-by-default gate: duplicates and stale operations never pass unnoticed. */
+export const DEFAULT_MEMORY_GRADE_THRESHOLDS = {
+    minPrecision: 0.7,
+    minRecall: 0.7,
+    maxDuplicate: 0,
+    maxStale: 0,
+    maxNoise: 0,
+};
+/**
+ * v1 exclusion heuristics for noise ("不该记什么" in mechanical form):
+ * git history, repo paths re-readable from disk, stack traces, and
+ * explicitly temporary session state. Keep this list short and documented —
+ * every pattern here is a precision/recall tradeoff, not ground truth.
+ */
+export const MEMORY_NOISE_PATTERNS = [
+    /\bgit\s+(log|show|commit|diff)\b/i,
+    /\bcommit\s+[0-9a-f]{5,40}\b/i,
+    /\b[0-9a-f]{40}\b/,
+    /(?:^|[\s("'])((?:src|lib|test|tests|docs|scripts)\/[A-Za-z0-9_./-]+\.[a-z]+)/,
+    /\bat\s+[\w$.]+\s*\(.*:\d+:\d+\)/,
+    /\b(temporary|one-off debugging|current task progress|in this session only)\b/i,
+];
+/** Content shorter than this is too thin to be a durable fact. */
+export const MEMORY_MIN_FACT_CHARS = 30;
+/**
+ * Score one proposal against the reference and the pre-extraction manifest.
+ *
+ * @param reference Labeled facts (live + outdated).
+ * @param edits The proposal's memory edits.
+ * @param manifest Memory entries visible before extraction (duplicate source).
+ * @returns Per-dimension counts plus a per-edit breakdown.
+ */
+export function scoreMemoryExtraction(reference, edits, manifest) {
+    const live = reference.facts.filter((fact) => !fact.outdated);
+    const outdated = reference.facts.filter((fact) => fact.outdated);
+    const liveMatched = new Set();
+    const outdatedHandled = new Set();
+    const scored = [];
+    let duplicate = 0;
+    let stale = 0;
+    let noise = 0;
+    for (const edit of edits) {
+        const text = `${edit.title ?? ""}\n${edit.content ?? ""}`;
+        const liveHits = live.filter((fact) => matchesFact(text, fact));
+        const outdatedHits = outdated.filter((fact) => matchesFact(text, fact));
+        const entry = { action: edit.action, matchedFactIds: [] };
+        if (edit.action === "create" || edit.action === "update") {
+            if (outdatedHits.length > 0) {
+                stale += 1;
+                entry.staleReason = `re-proposes outdated fact(s): ${outdatedHits.map((fact) => fact.id).join(",")}`;
+            }
+            else if (edit.action === "create") {
+                const hit = mostSimilarEntry(manifest.filter((candidate) => candidate.kind === "memory"), edit.title ?? "", edit.content ?? "", CONFLICT_BLOCK_SCORE);
+                if (hit) {
+                    duplicate += 1;
+                    entry.duplicateOf = hit.id;
+                }
+                else if (liveHits.length > 0) {
+                    for (const fact of liveHits) {
+                        liveMatched.add(fact.id);
+                        entry.matchedFactIds.push(fact.id);
+                    }
+                }
+                else {
+                    noise += 1;
+                    entry.noisyReason = noiseReason(text);
+                }
+            }
+            else if (liveHits.length > 0) {
+                for (const fact of liveHits) {
+                    liveMatched.add(fact.id);
+                    entry.matchedFactIds.push(fact.id);
+                }
+            }
+            else {
+                noise += 1;
+                entry.noisyReason = noiseReason(text);
+            }
+        }
+        else {
+            // delete/archive: correct only against outdated facts.
+            const targetHits = [...liveHits, ...outdatedHits];
+            const targetOutdated = outdatedHits.length > 0;
+            const targetEntry = edit.id !== undefined ? manifest.find((candidate) => candidate.id === edit.id) : undefined;
+            if (targetOutdated) {
+                for (const fact of outdatedHits) {
+                    outdatedHandled.add(fact.id);
+                    entry.matchedFactIds.push(fact.id);
+                }
+            }
+            else if (targetEntry !== undefined && isArchived(targetEntry)) {
+                // Re-archiving an already archived entry is harmless housekeeping.
+                entry.matchedFactIds.push(`archived:${targetEntry.id}`);
+            }
+            else if (targetHits.length > 0 || (targetEntry !== undefined && !isArchived(targetEntry))) {
+                stale += 1;
+                entry.staleReason = `removes live fact(s): ${targetHits.map((fact) => fact.id).join(",") || targetEntry?.id || "(unknown target)"}`;
+            }
+            else {
+                noise += 1;
+                entry.noisyReason = "removal matches no reference fact";
+            }
+        }
+        scored.push(entry);
+    }
+    const total = edits.length;
+    const preciseEdits = scored.filter((entry) => entry.matchedFactIds.length > 0).length;
+    const precision = total === 0 ? 1 : preciseEdits / total;
+    const recall = live.length === 0 ? 1 : liveMatched.size / live.length;
+    return {
+        totalEdits: total,
+        matchedFacts: liveMatched.size + outdatedHandled.size,
+        precision,
+        recall,
+        duplicate,
+        stale,
+        noise,
+        uncoveredFactIds: live.filter((fact) => !liveMatched.has(fact.id)).map((fact) => fact.id),
+        edits: scored,
+    };
+}
+/**
+ * Grade a score against explicit thresholds.
+ *
+ * @returns pass plus one failure line per violated dimension (empty when passing).
+ */
+export function gradeMemoryScore(score, thresholds = DEFAULT_MEMORY_GRADE_THRESHOLDS) {
+    const failures = [];
+    if (score.precision < thresholds.minPrecision)
+        failures.push(`precision ${score.precision.toFixed(2)} < ${thresholds.minPrecision}`);
+    if (score.recall < thresholds.minRecall)
+        failures.push(`recall ${score.recall.toFixed(2)} < ${thresholds.minRecall}`);
+    if (score.duplicate > thresholds.maxDuplicate)
+        failures.push(`duplicate ${score.duplicate} > ${thresholds.maxDuplicate}`);
+    if (score.stale > thresholds.maxStale)
+        failures.push(`stale ${score.stale} > ${thresholds.maxStale}`);
+    if (score.noise > thresholds.maxNoise)
+        failures.push(`noise ${score.noise} > ${thresholds.maxNoise}`);
+    return { pass: failures.length === 0, failures };
+}
+function matchesFact(text, fact) {
+    const lowered = text.toLowerCase();
+    return fact.mustContain.every((phrase) => lowered.includes(phrase.toLowerCase()));
+}
+function noiseReason(text) {
+    if (text.trim().length < MEMORY_MIN_FACT_CHARS)
+        return `thin content (<${MEMORY_MIN_FACT_CHARS} chars)`;
+    const hit = MEMORY_NOISE_PATTERNS.findIndex((pattern) => pattern.test(text));
+    return hit >= 0 ? `matches exclusion pattern #${hit + 1}` : "matches no reference fact";
+}
+//# sourceMappingURL=memory-benchmark.js.map

package/lib/notify.d.ts

@@ -29,4 +29,31 @@ export declare function buildGateNotice(result: RefinementResult, turnsSinceLast
  * the decision in reviews.jsonl.
  */
 export declare function notifyAutoReview(ctx: Context, agent: Agent, result: RefinementResult, turnsSinceLastReview: number): void;
+/** Unified extraction receipt: one shape for applied / declined / no-op. */
+export interface MemoryReceipt {
+    outcome: "applied" | "declined" | "noop";
+    /** Applied refinement batches (one per scope) for applied outcomes. */
+    results?: RefinementResult[];
+    /** Scopes the human explicitly declined. */
+    declinedScopes?: string[];
+    /** Extractor loop turns / manifest searches / wall time. */
+    turns: number;
+    searches: number;
+    durationMs: number;
+}
+/**
+ * Compose the user-visible memory receipt from applied refinement batches
+ * (never model text): every landed memory edit with its rollback command.
+ * No-op and declined-only outcomes render one quiet line each — a foreground
+ * notice for zero landed edits would be nagging, so callers only queue
+ * follow-ups for applied outcomes.
+ */
+export declare function buildMemoryReceipt(receipt: MemoryReceipt): string;
+/**
+ * Queue the memory receipt follow-up. Same containment as the gate notice:
+ * notification failure only logs. Callers gate on applied outcomes — no-op
+ * and declined-only runs stay audit-only (reviews.jsonl) and never wake
+ * the agent.
+ */
+export declare function notifyMemoryExtraction(ctx: Context, agent: Agent, receipt: MemoryReceipt): void;
 //# sourceMappingURL=notify.d.ts.map