dsh-continual-evolve 0.10.6 → 0.12.0

package/lib/memory-agent.js

@@ -1,568 +0,0 @@
-import { createAssistantMessage, createToolResultMessage, createUserMessage, } from "@deepseek-ai/dsh-llm";
-import { requestScopeApproval } from "./approval.js";
-import { fingerprintMemoryBatch, isDeclinedRepeat, loadDeclinedMemory, recordDeclinedMemory, } from "./declines.js";
-import { streamModelTurn } from "./llm-text.js";
-import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
-import { extractJsonObject, parseJsonCandidate } from "./plan.js";
-import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
-import { compactText } from "./render.js";
-import { buildConflictNotice, CONFLICT_WARN_SCORE, mostSimilarEntry } from "./promotion.js";
-import { EvolutionApplyPostCommitError } from "./service.js";
-import { tokenize } from "./search.js";
-import { createTokenUsageObserver } from "./token-usage.js";
-import { recordLanguageInstruction, resolveRecordLanguage } from "./record-language.js";
-import { isArchived, isMemoryType, MEMORY_TYPE_KEY, slug } from "./types.js";
-import { validateBlastRadiusScope, validateEdit } from "./validate.js";
-/** ZCode parity: the extractor may inspect memory and propose at most five times. */
-export const MEMORY_AGENT_MAX_TURNS = 5;
-/** Bound one proposal so approval text and engine compensation stay reviewable. */
-export const MEMORY_AGENT_MAX_EDITS = 20;
-/**
- * System-prompt size budget (chars): the prompt ships on EVERY extractor
- * turn (up to five per snapshot), so each added line is recurring token
- * spend, not one-off text. Raise this cap only in the same commit that
- * justifies the added lines (regression pressure beats silent bloat).
- */
-export const MEMORY_AGENT_SYSTEM_PROMPT_BUDGET_CHARS = 3000;
-/** The complete tool-name allowlist exposed by the memory agent. */
-export const MEMORY_AGENT_TOOL_NAMES = ["memory_search", "memory_propose"];
-/** Provider-facing schemas for the closed memory-only tool set. */
-export const MEMORY_AGENT_TOOL_SCHEMAS = [
-    {
-        name: "memory_search",
-        description: "Read full content from the frozen memory manifest. This is the only data-reading tool available to the memory extractor.",
-        parameters: {
-            type: "object",
-            additionalProperties: false,
-            properties: {
-                query: { type: "string", description: "Keywords, title text, scope:id, or content terms to retrieve." },
-            },
-            required: ["query"],
-        },
-    },
-    {
-        name: "memory_propose",
-        description: "Finish extraction with one auditable memory-only proposal. An empty edits array is a valid no-op.",
-        parameters: {
-            type: "object",
-            additionalProperties: false,
-            properties: {
-                summary: { type: "string" },
-                rationale: { type: "string" },
-                expectedOutcome: { type: "string" },
-                edits: {
-                    type: "array",
-                    maxItems: MEMORY_AGENT_MAX_EDITS,
-                    items: {
-                        type: "object",
-                        additionalProperties: false,
-                        properties: {
-                            action: { type: "string", enum: ["create", "update", "delete", "archive"] },
-                            kind: { type: "string", enum: ["memory"] },
-                            targetScope: { type: "string", enum: ["local", "project", "global"] },
-                            blastRadius: { type: "string", enum: ["general", "project", "session"] },
-                            id: { type: "string", pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
-                            title: { type: "string" },
-                            content: { type: "string" },
-                            path: { type: "string" },
-                            metadata: {
-                                type: "object",
-                                additionalProperties: false,
-                                properties: { memoryType: { type: "string", enum: ["user", "feedback", "project", "reference"] } },
-                            },
-                            reason: { type: "string" },
-                        },
-                        required: ["action", "kind", "targetScope", "blastRadius"],
-                    },
-                },
-            },
-            required: ["summary", "rationale", "expectedOutcome", "edits"],
-        },
-    },
-];
-/** Instructions for the dedicated loop; model text is always untrusted. */
-export const MEMORY_AGENT_SYSTEM_PROMPT = `You are the dedicated background memory extraction agent for a continual-evolution harness.
-
-You 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.
-
-Rules:
-- Use memory_search before creating when the manifest may already cover the topic. Update an existing entry instead of creating a near-duplicate.
-- Every memory entry contains exactly one fact. Classify it with metadata.memoryType = user | feedback | project | reference.
-- feedback and project memories must state the fact, Why it matters, and How to apply it next time.
-- Never invent a user preference. Ground every proposal in the supplied conversation evidence and existing memory.
-- 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; an already-applied troubleshooting fix with no recurrence evidence (the fixed state on disk is its own record).
-- Be specific enough to act on: prefer a fact that tells the next session what to DO over a summary of what happened. If the fact is obvious from the conversation itself with no future action attached, skip it.
-- Save only what is surprising or non-obvious: routine chatter, restated context, and facts with no bearing on future work are no-ops, not memories.
-- Granularity examples (vague → reject; sharp → save):
-  - "user communicates in Chinese" → "user reads English with effort — write memory and handoff content in Chinese prose".
-  - "user works on the desktop project" → "desktop profile loads npm-installed plugin copies — source edits need a release before they take effect".
-  - "fixed fcitx5 by setting GTK_IM_MODULE tonight" → reject (one-off applied fix, already on disk, no recurrence 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.`;
-/** Build the frozen memory manifest from a merged harness view. */
-export function buildMemoryManifest(state) {
-    return Object.values(state.entries.memory)
-        .map((entry) => ({ ...entry, metadata: { ...entry.metadata }, reference: {}, arguments: {} }))
-        .sort((a, b) => manifestOrder(a).localeCompare(manifestOrder(b), "en"));
-}
-/** Render a bounded manifest index; full bodies remain available through memory_search. */
-export function formatMemoryManifest(entries, maxChars = 8000) {
-    if (entries.length === 0)
-        return "No saved memory entries yet.";
-    const lines = [];
-    let used = 0;
-    for (const entry of entries) {
-        const type = isMemoryType(entry.metadata[MEMORY_TYPE_KEY]) ? entry.metadata[MEMORY_TYPE_KEY] : "untyped";
-        const archived = isArchived(entry) ? ", archived" : "";
-        const line = `- [${entry.scope}:${entry.id}] ${entry.title} (memoryType=${type}, path=${entry.path}${archived}): ${compactText(entry.content, 240)}`;
-        if (used + line.length + 1 > maxChars)
-            break;
-        lines.push(line);
-        used += line.length + 1;
-    }
-    const omitted = entries.length - lines.length;
-    if (omitted > 0)
-        lines.push(`- +${omitted} more entries; use memory_search with a narrower query.`);
-    return lines.join("\n");
-}
-/** Rank frozen manifest entries with CJK-aware token overlap and stable tie-breaking. */
-export function searchMemoryManifest(entries, query, maxResults = 8) {
-    const queryTokens = new Set(tokenize(query));
-    if (queryTokens.size === 0)
-        return [];
-    return entries
-        .map((entry) => {
-        const title = tokenize(entry.title);
-        const body = tokenize(`${entry.content} ${entry.path} ${String(entry.metadata[MEMORY_TYPE_KEY] ?? "")}`);
-        let score = 0;
-        for (const token of queryTokens) {
-            if (title.includes(token))
-                score += 2;
-            if (body.includes(token))
-                score += 1;
-        }
-        if (`${entry.scope}:${entry.id}`.toLowerCase() === query.trim().toLowerCase())
-            score += 100;
-        return { entry, score };
-    })
-        .filter((hit) => hit.score > 0)
-        .sort((a, b) => b.score - a.score || manifestOrder(a.entry).localeCompare(manifestOrder(b.entry), "en"))
-        .slice(0, maxResults)
-        .map((hit) => hit.entry);
-}
-/**
- * Run the dedicated loop against a frozen manifest.
- *
- * @throws On provider failure, abort, malformed tool arguments, policy denial,
- * a non-memory proposal, or exhaustion of the bounded internal turn budget.
- */
-export async function runMemoryAgent(ctx, options) {
-    const events = options.trajectoryEvents ?? [];
-    const routing = resolvePrefixCache(options.prefixCache);
-    const route = detectPlannerRoute(events, routing.mode);
-    const prefixMessages = route === "A"
-        ? buildPrefixMessages(events, { provider: options.provider, model: options.model, maxChars: routing.maxChars })
-        : [];
-    const conversation = prefixMessages.length > 0 ? "" : `<conversation>\n${options.trajectory}\n</conversation>`;
-    const prompt = [
-        `<memory_manifest>\n${formatMemoryManifest(options.manifest)}\n</memory_manifest>`,
-        conversation,
-        "Search before deciding, then call memory_propose with the complete memory-only proposal. Empty edits is a valid no-op.",
-    ]
-        .filter(Boolean)
-        .join("\n\n");
-    const messages = [
-        ...prefixMessages,
-        createUserMessage({
-            content: [{ type: "text", text: prompt }],
-            source: EVOLVE_MESSAGE_SOURCE,
-        }),
-    ];
-    let searches = 0;
-    const language = options.language ?? resolveRecordLanguage({ ctx, trajectoryText: options.trajectory });
-    const systemPrompt = `${MEMORY_AGENT_SYSTEM_PROMPT}\n\n${recordLanguageInstruction(language)}`;
-    for (let turn = 1; turn <= MEMORY_AGENT_MAX_TURNS; turn += 1) {
-        options.signal?.throwIfAborted();
-        const blocks = await streamModelTurn(ctx, {
-            provider: options.provider,
-            model: options.model,
-            ...(options.sessionId ? { sessionId: options.sessionId } : {}),
-            system: systemPrompt,
-            messages,
-            tools: MEMORY_AGENT_TOOL_SCHEMAS,
-            requireTextOrToolCall: true,
-            maxTokens: options.maxOutputTokens ?? 4096,
-            ...(options.signal ? { signal: options.signal } : {}),
-            ...(options.tokenUsage
-                ? { onUsage: createTokenUsageObserver(options.tokenUsage, "memory", options.provider, options.model) }
-                : {}),
-        });
-        const hasText = blocks.some((block) => block.type === "text" && block.text.length > 0);
-        const hasToolCall = blocks.some((block) => block.type === "tool-call");
-        if (!hasText && !hasToolCall)
-            throw new Error("memory agent produced no model output");
-        messages.push(createAssistantMessage({
-            content: blocks,
-            source: { provider: options.provider, model: options.model },
-        }));
-        const toolCalls = blocks.filter((block) => block.type === "tool-call");
-        if (toolCalls.length === 0) {
-            const text = textOf(blocks);
-            return {
-                proposal: parseMemoryExtractionProposal(extractJsonObject(text), options.manifest),
-                turns: turn,
-                searches,
-            };
-        }
-        let proposal;
-        for (const call of toolCalls) {
-            const execution = executeMemoryTool(call, options.manifest);
-            if (call.name === "memory_search")
-                searches += 1;
-            proposal ??= execution.proposal;
-            messages.push(createToolResultMessage({
-                callId: call.id,
-                content: [{ type: "text", text: execution.text }],
-                isError: execution.isError,
-            }));
-        }
-        if (proposal)
-            return { proposal, turns: turn, searches };
-    }
-    throw new Error(`memory agent exhausted ${MEMORY_AGENT_MAX_TURNS} internal turns without a valid proposal`);
-}
-/** Strictly parse and policy-check the structured `memory_propose` payload. */
-export function parseMemoryExtractionProposal(value, manifest) {
-    const record = asRecord(value);
-    if (!record)
-        throw new Error("memory proposal must be an object");
-    const summary = requiredString(record["summary"], "summary");
-    const rationale = requiredString(record["rationale"], "rationale");
-    const expectedOutcome = requiredString(record["expectedOutcome"], "expectedOutcome");
-    if (!Array.isArray(record["edits"]))
-        throw new Error("memory proposal edits must be an array");
-    if (record["edits"].length > MEMORY_AGENT_MAX_EDITS) {
-        throw new Error(`memory proposal exceeds ${MEMORY_AGENT_MAX_EDITS} edits`);
-    }
-    const byScopeId = new Map(manifest.map((entry) => [`${entry.scope}:${entry.id}`, entry]));
-    const edits = record["edits"].map((raw, index) => parseScopedMemoryEdit(raw, index, byScopeId));
-    return { summary, rationale, expectedOutcome, edits };
-}
-/**
- * Render the authoritative persistent-scope diff shown to the human. Model
- * prose is retained only as an explicitly untrusted summary; actions, targets,
- * content previews, memory types, and conflict warnings come from code.
- */
-export function renderMemoryApprovalDetails(proposal, scope, state, maxChars = 6000) {
-    const edits = proposal.edits.filter((candidate) => candidate.targetScope === scope);
-    const details = edits.map((edit) => {
-        const before = edit.id ? state.entries.memory[edit.id] : undefined;
-        const title = edit.title ?? before?.title ?? "(existing title unchanged)";
-        const path = edit.path ?? before?.path ?? "(path unchanged)";
-        const content = edit.content ?? (edit.action === "update" ? "(content unchanged)" : "(no content field)");
-        const type = edit.metadata?.[MEMORY_TYPE_KEY] ?? before?.metadata[MEMORY_TYPE_KEY] ?? "untyped";
-        const candidates = Object.values(state.entries.memory).filter((entry) => entry.id !== edit.id);
-        const hit = edit.action === "create" || edit.action === "update"
-            ? mostSimilarEntry(candidates, edit.title ?? before?.title ?? "", edit.content ?? before?.content ?? "", CONFLICT_WARN_SCORE)
-            : undefined;
-        const conflict = hit ? `; conflict: ${compactText(buildConflictNotice(hit), 120)}` : "";
-        const targetId = edit.id === undefined ? "(new)" : JSON.stringify(edit.id);
-        return {
-            target: `- ${edit.action} ${scope}:${targetId} — ${compactText(title, 80)}`,
-            detail: `  path=${compactText(path, 60)}; memoryType=${String(type)}; content=${compactText(content, 100)}${conflict}`,
-        };
-    });
-    let titleLimit = 80;
-    let targets = details.map((detail) => detail.target.replace(/ — .*$/, ` — ${compactText(detail.target.split(" — ")[1] ?? "", titleLimit)}`));
-    let base = ["edits to approve:", ...targets].join("\n");
-    while (base.length > maxChars && titleLimit > 20) {
-        titleLimit = Math.floor(titleLimit / 2);
-        targets = details.map((detail) => `- ${detail.target.split(" — ")[0]} — ${compactText(detail.target.split(" — ")[1] ?? "", titleLimit)}`);
-        base = ["edits to approve:", ...targets].join("\n");
-    }
-    if (base.length > maxChars)
-        throw new Error(`memory approval diff exceeds ${maxChars} characters`);
-    const output = [base];
-    const summary = `model summary (untrusted): ${compactText(proposal.summary, 180)}`;
-    if ([...output, summary].join("\n").length <= maxChars)
-        output.push(summary);
-    for (const detail of details) {
-        const line = detail.detail;
-        if ([...output, line].join("\n").length <= maxChars)
-            output.push(line);
-    }
-    if ([...output, "  (additional previews omitted; every target is listed above)"].join("\n").length <= maxChars) {
-        output.push("  (additional previews omitted; every target is listed above)");
-    }
-    return output.join("\n");
-}
-function memoryScopeDecisionKey(cursor, scope, edits) {
-    return `${cursor}:${scope}:${JSON.stringify(edits.map(stripTargetScope))}`;
-}
-class MemoryApplyBatchError extends Error {
-    result;
-    scope;
-    storeId;
-    constructor(message, result, scope, storeId) {
-        super(message);
-        this.result = result;
-        this.scope = scope;
-        this.storeId = storeId;
-    }
-}
-/**
- * Apply one accepted proposal through the only mutation engine. All persistent
- * approvals are resolved before the first write, so an unavailable approval
- * boundary cannot leave a partially applied batch. Explicit rejection is a
- * no-op for that scope; service/question failures remain retryable errors.
- */
-export async function applyMemoryExtractionProposal(ctx, engine, proposal, options) {
-    const scopeOrder = ["local", "project", "global"];
-    const editsByScope = new Map();
-    for (const scope of scopeOrder) {
-        const edits = proposal.edits.filter((edit) => edit.targetScope === scope);
-        if (edits.length > 0)
-            editsByScope.set(scope, edits);
-    }
-    if (editsByScope.has("project") && !options.projectKey) {
-        throw new Error("memory agent cannot target project scope without a resolved project key");
-    }
-    const approvedScopes = new Set();
-    const declinedScopes = [];
-    for (const scope of ["project", "global"]) {
-        if (!editsByScope.has(scope))
-            continue;
-        if (!options.requireApproval) {
-            approvedScopes.add(scope);
-            continue;
-        }
-        const baseline = options.baselines[scope];
-        if (!baseline)
-            throw new Error(`memory agent has no ${scope} baseline`);
-        const scopeEdits = proposal.edits.filter((edit) => edit.targetScope === scope);
-        const fingerprint = fingerprintMemoryBatch(scope, scopeEdits);
-        if (isDeclinedRepeat(loadDeclinedMemory(engine.baseDir), scope, fingerprint)) {
-            ctx.logger("continual-evolve").info(`memory ${scope} proposal repeat-suppressed (declined before, no popup)`);
-            declinedScopes.push(scope);
-            continue;
-        }
-        const decisionKey = options.decisionCursor === undefined
-            ? undefined
-            : memoryScopeDecisionKey(options.decisionCursor, scope, proposal.edits.filter((edit) => edit.targetScope === scope));
-        const previous = decisionKey === undefined ? undefined : options.scopeDecisions?.[decisionKey];
-        if (previous === "approved") {
-            approvedScopes.add(scope);
-            continue;
-        }
-        if (previous === "declined") {
-            declinedScopes.push(scope);
-            continue;
-        }
-        const approved = await requestScopeApproval(ctx, options.agent, options.signal, scope, renderMemoryApprovalDetails(proposal, scope, baseline), options.recordLanguage);
-        if (decisionKey !== undefined)
-            options.onScopeDecision?.(decisionKey, approved);
-        if (approved === "approved")
-            approvedScopes.add(scope);
-        else {
-            declinedScopes.push(scope);
-            try {
-                recordDeclinedMemory(engine.baseDir, scope, scopeEdits, compactText(scopeEdits[0]?.title ?? proposal.summary, 120));
-            }
-            catch (error) {
-                ctx.logger("continual-evolve").warn(`declined-memory ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-    }
-    const results = [];
-    const applied = [];
-    try {
-        for (const scope of scopeOrder) {
-            const edits = editsByScope.get(scope);
-            if (!edits)
-                continue;
-            if (scope !== "local" && !approvedScopes.has(scope))
-                continue;
-            options.signal?.throwIfAborted();
-            const storeId = scope === "local" ? options.agent.id : scope === "project" ? options.projectKey : undefined;
-            const baseline = options.baselines[scope];
-            if (!baseline)
-                throw new Error(`memory agent has no ${scope} baseline`);
-            const result = engine.apply(scope, storeId, {
-                summary: proposal.summary,
-                rationale: proposal.rationale,
-                expectedOutcome: proposal.expectedOutcome,
-                edits: prepareMemoryEdits(edits, baseline),
-            }, {
-                scope,
-                baselineState: baseline,
-                ...(options.source ? { source: options.source } : {}),
-            });
-            const failed = result.appliedEdits.filter((edit) => !edit.applied);
-            if (failed.length > 0) {
-                throw new MemoryApplyBatchError(`${scope} batch ${result.id} left ${failed.length} edit(s) unapplied: ${failed.map((edit) => edit.error ?? "unknown").join("; ")}`, result, scope, storeId);
-            }
-            results.push(result);
-            applied.push({ scope, storeId, result });
-        }
-        return { results, declinedScopes };
-    }
-    catch (cause) {
-        const attempted = [...applied];
-        if (cause instanceof MemoryApplyBatchError && cause.result && cause.scope) {
-            attempted.push({ scope: cause.scope, storeId: cause.storeId, result: cause.result });
-        }
-        else if (cause instanceof EvolutionApplyPostCommitError) {
-            attempted.push({ scope: cause.scope, storeId: cause.storeId, result: cause.result });
-        }
-        const rollbackErrors = [];
-        for (const item of attempted.reverse()) {
-            try {
-                const rollback = engine.rollbackResult(item.scope, item.storeId, item.result);
-                const failed = rollback.appliedEdits.filter((edit) => !edit.applied);
-                if (failed.length > 0)
-                    rollbackErrors.push(`${item.scope}:${item.result.id} left ${failed.length} rollback edit(s) unapplied`);
-            }
-            catch (rollbackCause) {
-                rollbackErrors.push(`${item.scope}:${item.result.id} rollback failed: ${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`);
-            }
-        }
-        const suffix = rollbackErrors.length > 0 ? `; compensation errors: ${rollbackErrors.join("; ")}` : "; prior memory writes were rolled back";
-        throw new Error(`memory agent apply failed: ${cause instanceof Error ? cause.message : String(cause)}${suffix}`);
-    }
-}
-function executeMemoryTool(call, manifest) {
-    if (!MEMORY_AGENT_TOOL_NAMES.includes(call.name)) {
-        return { text: `tool denied: only ${MEMORY_AGENT_TOOL_NAMES.join(" and ")} are available`, isError: true };
-    }
-    try {
-        const args = parseJsonCandidate(call.arguments.trim() || "{}");
-        if (call.name === "memory_search") {
-            const record = asRecord(args);
-            const query = record ? requiredString(record["query"], "query") : "";
-            const matches = searchMemoryManifest(manifest, query).map(manifestResult);
-            return { text: JSON.stringify({ matches }), isError: false };
-        }
-        return { proposal: parseMemoryExtractionProposal(args, manifest), text: JSON.stringify({ accepted: true }), isError: false };
-    }
-    catch (cause) {
-        return {
-            text: `tool error: ${cause instanceof Error ? cause.message : String(cause)}`,
-            isError: true,
-        };
-    }
-}
-function parseScopedMemoryEdit(raw, index, byScopeId) {
-    const record = asRecord(raw);
-    if (!record)
-        throw new Error(`memory edit ${index} must be an object`);
-    const action = requiredString(record["action"], `edits[${index}].action`);
-    if (!isOneOf(action, ["create", "update", "delete", "archive"])) {
-        throw new Error(`memory edit ${index} has unsupported action ${action}`);
-    }
-    if (record["kind"] !== "memory")
-        throw new Error(`memory edit ${index} must have kind=memory`);
-    const targetScope = requiredString(record["targetScope"], `edits[${index}].targetScope`);
-    if (!isOneOf(targetScope, ["local", "project", "global"])) {
-        throw new Error(`memory edit ${index} has unsupported targetScope ${targetScope}`);
-    }
-    const blastRadius = requiredString(record["blastRadius"], `edits[${index}].blastRadius`);
-    if (!isOneOf(blastRadius, ["general", "project", "session"])) {
-        throw new Error(`memory edit ${index} has unsupported blastRadius ${blastRadius}`);
-    }
-    const blastError = validateBlastRadiusScope(targetScope, blastRadius);
-    if (blastError)
-        throw new Error(`memory edit ${index}: ${blastError}`);
-    if (record["reference"] !== undefined || record["arguments"] !== undefined || record["skill_kind"] !== undefined) {
-        throw new Error(`memory edit ${index} cannot carry skill-only fields`);
-    }
-    const edit = {
-        action,
-        kind: "memory",
-        targetScope,
-        blastRadius,
-    };
-    for (const field of ["id", "title", "content", "path", "reason"]) {
-        const fieldValue = record[field];
-        if (fieldValue !== undefined) {
-            if (typeof fieldValue !== "string")
-                throw new Error(`memory edit ${index}.${field} must be a string`);
-            edit[field] = fieldValue;
-        }
-    }
-    if (record["metadata"] !== undefined) {
-        const metadata = asRecord(record["metadata"]);
-        if (!metadata)
-            throw new Error(`memory edit ${index}.metadata must be an object`);
-        const unexpected = Object.keys(metadata).filter((key) => key !== MEMORY_TYPE_KEY);
-        if (unexpected.length > 0) {
-            throw new Error(`memory edit ${index}.metadata contains engine-owned or unsupported keys: ${unexpected.join(", ")}`);
-        }
-        edit.metadata = { ...metadata };
-    }
-    if (action === "create" && edit.id && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(edit.id)) {
-        throw new Error(`memory edit ${index}.id contains unsupported identifier characters`);
-    }
-    const before = edit.id ? byScopeId.get(`${targetScope}:${edit.id}`) : undefined;
-    if (action !== "create" && !before) {
-        throw new Error(`memory edit ${index} ${action} target does not exist in ${targetScope}: ${edit.id ?? "(missing id)"}`);
-    }
-    if (action === "create" && edit.id && before) {
-        throw new Error(`memory edit ${index} create duplicates ${targetScope}:${edit.id}; use update instead`);
-    }
-    const validationError = validateEdit(edit, edit.id ?? slug(edit.title ?? "memory", "memory"), targetScope, before);
-    if (validationError)
-        throw new Error(`memory edit ${index}: ${validationError}`);
-    return edit;
-}
-function prepareMemoryEdits(edits, baseline) {
-    return edits.map((edit) => {
-        const plain = stripTargetScope(edit);
-        if (plain.action !== "update" || plain.metadata === undefined || plain.id === undefined)
-            return plain;
-        const before = baseline.entries.memory[plain.id];
-        return before ? { ...plain, metadata: { ...before.metadata, ...plain.metadata } } : plain;
-    });
-}
-function stripTargetScope(edit) {
-    const { targetScope: _targetScope, ...plain } = edit;
-    return plain;
-}
-function manifestResult(entry) {
-    return {
-        scope: entry.scope,
-        id: entry.id,
-        title: entry.title,
-        content: entry.content,
-        path: entry.path,
-        memoryType: entry.metadata[MEMORY_TYPE_KEY],
-        archived: isArchived(entry),
-    };
-}
-function manifestOrder(entry) {
-    const scope = entry.scope === "global" ? "0" : entry.scope === "project" ? "1" : "2";
-    return `${scope}:${entry.id}:${entry.title}`;
-}
-function textOf(blocks) {
-    return blocks
-        .filter((block) => block.type === "text")
-        .map((block) => block.text)
-        .join("\n");
-}
-function asRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    return value;
-}
-function requiredString(value, field) {
-    if (typeof value !== "string" || value.trim().length === 0)
-        throw new Error(`${field} must be a non-empty string`);
-    return value;
-}
-function isOneOf(value, values) {
-    return values.includes(value);
-}
-//# sourceMappingURL=memory-agent.js.map

package/lib/memory-benchmark.d.ts

@@ -1,76 +0,0 @@
-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