@co-engram/core 0.1.0

package/dist/tools/engram-tools.js

@@ -0,0 +1,834 @@
+/**
+ * Engram 工具集
+ *
+ * 11 个工具（P0 六个 + P1 五个：三信号 + 生命周期）：
+ *   - engram_create / engram_get / engram_update / engram_delete
+ *   - engram_search / engram_list
+ *   - engram_reinforce / engram_report_failure（三信号）
+ *   - engram_archive / engram_restore / engram_forget（生命周期）
+ *
+ * @module @co-engram/core/tools
+ */
+import { validateInput } from "./tool.js";
+import { matchesFilter } from "../retrieval/filter.js";
+import { computeFreshness } from "../lifecycle/freshness.js";
+import { adaptiveDisclosure } from "../disclosure/adaptive.js";
+import { createBudget } from "../disclosure/budget.js";
+import { recordRetrievalSuccess, } from "../reinforcement/ltp.js";
+import { recordRetrievalFailure } from "../reinforcement/ltd.js";
+import { reinforceRelated } from "../reinforcement/related.js";
+import { DEFAULT_CONFIG as DEFAULT_REINFORCEMENT_CONFIG } from "../reinforcement/config.js";
+import { checkDuplicateSync } from "../dedup/dedupe.js";
+import { mergeEngram } from "../dedup/merge.js";
+import { recomputeImportance } from "../importance/vector.js";
+import { manualResolveContradiction } from "../contradiction/index.js";
+import { closeLearningLoop } from "../learning/loop.js";
+import { upgradeVerification } from "../verification/index.js";
+import { getEvolutionLineage } from "../lineage/index.js";
+import { restoreFromTrash } from "../dreaming/trash.js";
+import { collectDigestLines } from "../index/digest-builder.js";
+import { EngramCreateInputSchema, EngramGetInputSchema, EngramUpdateInputSchema, EngramDeleteInputSchema, EngramSearchInputSchema, EngramListInputSchema, EngramReinforceInputSchema, EngramReportFailureInputSchema, EngramArchiveInputSchema, EngramRestoreInputSchema, EngramForgetInputSchema, EngramRecomputeImportanceInputSchema, ContradictionResolveInputSchema, CloseLearningLoopInputSchema, UpgradeVerificationInputSchema, GetEvolutionLineageInputSchema, } from "./schemas.js";
+export const engramCreateTool = {
+    name: "engram_create",
+    description: '创建一个新的 Engram（记忆单元）。需要 title / content / kind / domainTags；createdBy 可选,缺省时回退到 ToolContext.defaultCreatedBy(MCP: CO_ENGRAM_DEFAULT_CREATED_BY 环境变量;OpenClaw: plugin config.defaultCreatedBy),再缺省回退到 "unknown"。默认开启智能去重（dedupe=true）：DUPLICATE 时强化原 engram 不重复创建；UPDATE 时合并；NEW 时正常创建。',
+    inputSchema: EngramCreateInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramCreateInputSchema, input);
+        const createdBy = parsed.createdBy ?? ctx.defaultCreatedBy ?? "unknown";
+        if (parsed.dedupe !== false) {
+            const dedupResult = checkDuplicateSync({ repository: ctx.repository }, {
+                title: parsed.title,
+                content: parsed.content,
+                kind: parsed.kind,
+                kinds: parsed.kinds,
+                summary: parsed.summary,
+                domainTags: parsed.domainTags,
+                contextTags: parsed.contextTags,
+                encodingContext: parsed.encodingContext,
+                importance: parsed.importance,
+                confidence: parsed.confidence,
+                emotionalValence: parsed.emotionalValence,
+                sourceType: parsed.sourceType,
+                visibility: parsed.visibility,
+                decayHalfLifeDays: parsed.decayHalfLifeDays,
+                createdBy,
+            });
+            if (dedupResult.verdict === "DUPLICATE" && dedupResult.targetId) {
+                // 强化原 engram：再次见到视为有效检索（effectiveness=1）
+                recordRetrievalSuccess(ctx.repository, dedupResult.targetId, 1);
+                return {
+                    id: dedupResult.targetId,
+                    verdict: "DUPLICATE",
+                    targetId: dedupResult.targetId,
+                    reason: dedupResult.reason,
+                    confidence: dedupResult.confidence,
+                    candidatesConsidered: dedupResult.candidatesConsidered,
+                };
+            }
+            if (dedupResult.verdict === "UPDATE" && dedupResult.targetId) {
+                mergeEngram(ctx.repository, {
+                    id: dedupResult.targetId,
+                    newTitle: parsed.title,
+                    newContent: parsed.content,
+                    newSummary: parsed.summary,
+                    newImportance: parsed.importance,
+                    mergedBy: createdBy,
+                    reason: dedupResult.reason ?? "dedup auto-merge",
+                });
+                invalidateSearchIndex(ctx);
+                return {
+                    id: dedupResult.targetId,
+                    verdict: "UPDATE",
+                    targetId: dedupResult.targetId,
+                    reason: dedupResult.reason,
+                    confidence: dedupResult.confidence,
+                    candidatesConsidered: dedupResult.candidatesConsidered,
+                };
+            }
+        }
+        const engram = ctx.repository.createEngram({
+            title: parsed.title,
+            content: parsed.content,
+            kind: parsed.kind,
+            kinds: parsed.kinds,
+            summary: parsed.summary,
+            domainTags: parsed.domainTags,
+            contextTags: parsed.contextTags,
+            encodingContext: parsed.encodingContext,
+            importance: parsed.importance,
+            confidence: parsed.confidence,
+            emotionalValence: parsed.emotionalValence,
+            sourceType: parsed.sourceType,
+            visibility: parsed.visibility,
+            decayHalfLifeDays: parsed.decayHalfLifeDays,
+            createdBy,
+        });
+        invalidateSearchIndex(ctx);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "create",
+            engramId: engram.id,
+            metadata: {
+                title: parsed.title,
+                kind: parsed.kind,
+                domainTags: parsed.domainTags,
+                createdBy,
+            },
+        });
+        return {
+            id: engram.id,
+            verdict: "NEW",
+            candidatesConsidered: 0,
+        };
+    },
+};
+// ============================================================
+// engram_get
+// ============================================================
+export const engramGetTool = {
+    name: "engram_get",
+    description: "按披露层级（catalog / digest / content / meta / synapses / auto）读取 Engram。auto 模式按 contextBudget 自动选 tier。",
+    inputSchema: EngramGetInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramGetInputSchema, input);
+        if (parsed.tier === "auto") {
+            return readEngramViewAuto(ctx.repository, parsed.id, {
+                contextBudget: parsed.contextBudget,
+                score: parsed.score,
+            });
+        }
+        return readEngramView(ctx.repository, parsed.id, parsed.tier);
+    },
+};
+/**
+ * auto 模式：调用 adaptiveDisclosure 决定 tier
+ *
+ * 把单条 engram 当作唯一的候选传入。
+ */
+function readEngramViewAuto(repo, id, options) {
+    const totalTokens = options.contextBudget?.totalTokens ?? 4096;
+    const reserved = options.contextBudget?.reserved ?? 0;
+    const budget = createBudget(totalTokens, reserved);
+    const digest = repo.readDigest(id);
+    if (!digest)
+        throw new Error(`Engram not found: ${id}`);
+    const line = {
+        id,
+        title: digest.title,
+        kind: digest.kind,
+        kinds: [digest.kind],
+        summary: digest.summary,
+        domainTags: digest.domainTags,
+        contextTags: [],
+        importance: digest.importance,
+        emotionalValence: digest.emotionalValence,
+        freshness: digest.freshness,
+        status: "active",
+        sourceType: "firsthand",
+        createdBy: "",
+        createdAt: digest.updatedAt,
+        updatedAt: digest.updatedAt,
+        lastRetrievedAt: null,
+        lastEffectiveAt: null,
+        retrievalCount: 0,
+        effectiveRetrievals: 0,
+        failedUses: 0,
+        reinforcementScore: 0,
+        decayHalfLifeDays: 90,
+        contentSize: digest.contentSize,
+        contentHash: "",
+        outgoingSynapseCount: 0,
+        incomingSynapseCount: 0,
+        activeContradictionCount: 0,
+    };
+    const result = adaptiveDisclosure({
+        repository: repo,
+        candidates: [{ id, score: options.score ?? 1 }],
+        digestLines: { [id]: line },
+        budget,
+    });
+    const entry = result.loaded[0];
+    if (!entry) {
+        // 预算极小，连 catalog 都装不下 → 降级为直接读 catalog
+        return readEngramView(repo, id, "catalog");
+    }
+    return entry.view;
+}
+/**
+ * 读取 EngramView（被工具 / adapter 共用）
+ */
+export function readEngramView(repo, id, tier) {
+    switch (tier) {
+        case "catalog": {
+            const entry = repo.readCatalogEntry(id);
+            if (!entry)
+                throw new Error(`Engram not found: ${id}`);
+            return { tier: "catalog", entry };
+        }
+        case "digest": {
+            const digest = repo.readDigest(id);
+            if (!digest)
+                throw new Error(`Engram not found: ${id}`);
+            return { tier: "digest", digest };
+        }
+        case "content": {
+            const engram = repo.readEngram(id);
+            return {
+                tier: "content",
+                entry: toCatalogEntry(engram),
+                content: engram.content,
+            };
+        }
+        case "meta": {
+            const engram = repo.readEngram(id);
+            return {
+                tier: "meta",
+                entry: toCatalogEntry(engram),
+                meta: stripContentFromMeta(engram),
+            };
+        }
+        case "synapses": {
+            const entry = repo.readCatalogEntry(id);
+            if (!entry)
+                throw new Error(`Engram not found: ${id}`);
+            const outgoingFile = repo.readSynapses(id);
+            const incoming = collectIncoming(repo, id);
+            const neighborDigests = collectNeighborDigests(repo, id, outgoingFile.outgoing, incoming);
+            const bundle = {
+                engramId: id,
+                outgoing: outgoingFile.outgoing,
+                incoming,
+                neighborDigests,
+            };
+            return { tier: "synapses", bundle };
+        }
+    }
+}
+function toCatalogEntry(engram) {
+    return {
+        id: engram.id,
+        title: engram.title,
+        kind: engram.kind,
+        domainTags: engram.domainTags,
+    };
+}
+/** meta tier 不暴露 body（避免双重传输） */
+function stripContentFromMeta(engram) {
+    const { content: _content, ...rest } = engram;
+    return rest;
+}
+/** 收集指向 id 的 incoming synapses（需要扫所有 engram） */
+function collectIncoming(repo, id) {
+    const all = repo.collectAllSynapses();
+    return all
+        .filter(({ synapse }) => synapse.to === id)
+        .map(({ synapse }) => synapse);
+}
+function collectNeighborDigests(repo, _selfId, outgoing, incoming) {
+    const neighborIds = new Set();
+    for (const s of outgoing)
+        neighborIds.add(s.to);
+    for (const s of incoming)
+        neighborIds.add(s.from);
+    const digests = [];
+    for (const nid of neighborIds) {
+        const d = repo.readDigest(nid);
+        if (d)
+            digests.push(d);
+    }
+    return digests;
+}
+// ============================================================
+// engram_update
+// ============================================================
+/**
+ * 跟踪 engram_update 的字段对比(用于 audit log)
+ *
+ * 不在表中的字段(version / updatedAt / retrievalCount 等系统字段)不算"用户修改"。
+ */
+const TRACKED_ENGRAM_FIELDS = [
+    "title",
+    "summary",
+    "content",
+    "kinds",
+    "domainTags",
+    "contextTags",
+    "encodingContext",
+    "importance",
+    "confidence",
+    "emotionalValence",
+    "decayHalfLifeDays",
+    "visibility",
+];
+/** 字段值在 audit 中的最大长度(超出截断,防 audit.jsonl 爆炸) */
+const FIELD_TRUNCATE = {
+    title: 80,
+    summary: 120,
+    content: 240,
+    encodingContext: 120,
+};
+function truncateFieldValue(field, value) {
+    if (typeof value === "string") {
+        const max = FIELD_TRUNCATE[field] ?? 0;
+        if (max > 0 && value.length > max) {
+            const head = Math.ceil(max * 0.6);
+            const tail = Math.floor(max * 0.3);
+            const omitted = value.length - head - tail;
+            return (value.slice(0, head) +
+                `…[${omitted} chars omitted]…` +
+                value.slice(-tail));
+        }
+    }
+    return value;
+}
+/**
+ * 对比 before / after,返回每个变化字段的 { from, to }
+ *
+ * 用 JSON.stringify 等价比较覆盖数组 / 对象 / 基本类型,简单稳健。
+ */
+function diffEngramFields(before, after) {
+    const changes = {};
+    for (const f of TRACKED_ENGRAM_FIELDS) {
+        const b = before[f];
+        const a = after[f];
+        if (JSON.stringify(b) === JSON.stringify(a))
+            continue;
+        changes[f] = {
+            from: truncateFieldValue(f, b),
+            to: truncateFieldValue(f, a),
+        };
+    }
+    return changes;
+}
+export const engramUpdateTool = {
+    name: "engram_update",
+    description: "更新 Engram 的字段（content / title / importance / 等）。",
+    inputSchema: EngramUpdateInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramUpdateInputSchema, input);
+        // 取 before 用于 audit diff;若 engram 不存在 updateEngram 会抛,这里 readEngram 也抛
+        const before = ctx.repository.readEngram(parsed.id);
+        const engram = ctx.repository.updateEngram(parsed.id, {
+            title: parsed.title,
+            content: parsed.content,
+            summary: parsed.summary,
+            kinds: parsed.kinds,
+            domainTags: parsed.domainTags,
+            contextTags: parsed.contextTags,
+            encodingContext: parsed.encodingContext,
+            importance: parsed.importance,
+            confidence: parsed.confidence,
+            emotionalValence: parsed.emotionalValence,
+            decayHalfLifeDays: parsed.decayHalfLifeDays,
+            visibility: parsed.visibility,
+            updatedBy: parsed.updatedBy,
+        });
+        invalidateSearchIndex(ctx);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "update",
+            engramId: engram.id,
+            metadata: {
+                updatedBy: parsed.updatedBy,
+                changes: diffEngramFields(before, engram),
+            },
+        });
+        return { id: engram.id, version: engram.version };
+    },
+};
+// ============================================================
+// engram_delete
+// ============================================================
+export const engramDeleteTool = {
+    name: "engram_delete",
+    description: "删除 Engram（content + meta + synapses 三文件一起删）。",
+    inputSchema: EngramDeleteInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramDeleteInputSchema, input);
+        if (!ctx.repository.exists(parsed.id)) {
+            throw new Error(`Engram not found: ${parsed.id}`);
+        }
+        ctx.repository.deleteEngram(parsed.id);
+        invalidateSearchIndex(ctx);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "purge",
+            engramId: parsed.id,
+        });
+        return { id: parsed.id, deleted: true };
+    },
+};
+// ============================================================
+// engram_search
+// ============================================================
+export const engramSearchTool = {
+    name: "engram_search",
+    description: "FTS 全文检索（中文 bigram + 英文 word），可选过滤器。",
+    inputSchema: EngramSearchInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramSearchInputSchema, input);
+        if (!ctx.searchOrchestrator) {
+            throw new Error("SearchOrchestrator not available in ToolContext");
+        }
+        const results = ctx.searchOrchestrator.search(parsed.query, parsed.filter, parsed.limit);
+        // P4 自动维护：命中后立即 bump retrieval stats（不触发 version++）
+        // 用于 RPE 公式的 expected 基准
+        const timestamp = new Date().toISOString();
+        for (const r of results) {
+            try {
+                ctx.repository.bumpRetrievalStats(r.id, {
+                    retrievedDelta: 1,
+                    lastRetrievalScore: r.score,
+                    lastRetrievedAt: timestamp,
+                });
+            }
+            catch {
+                // bump 失败不阻塞 search 结果（可能 engram 已被并发删除）
+            }
+            // M1: 为每个 hit 开观察窗口（如果配置了 effectivenessTracker）
+            const engram = safeReadEngram(ctx, r.id);
+            if (engram) {
+                ctx.effectivenessTracker?.openWindow({
+                    engramId: r.id,
+                    query: parsed.query,
+                    score: r.score,
+                    kinds: engram.kinds ?? [engram.kind],
+                    sessionId: ctx.sessionId,
+                });
+            }
+        }
+        return {
+            // title/kind/domainTags 让 LLM 不必再 engram_get 才知道每条结果是啥。
+            // orchestrator 已经从 DigestLine 带出了 entry 字段,直接展开。
+            results: results.map((r) => ({
+                id: r.id,
+                score: r.score,
+                title: r.entry.title,
+                kind: r.entry.kind,
+                domainTags: r.entry.domainTags,
+            })),
+            total: results.length,
+        };
+    },
+};
+// ============================================================
+// engram_list
+// ============================================================
+export const engramListTool = {
+    name: "engram_list",
+    description: "按过滤器列出 Engram（无查询，按元数据过滤，直接读最新数据）。",
+    inputSchema: EngramListInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramListInputSchema, input);
+        const entries = ctx.repository.listEngrams();
+        const lines = [];
+        for (const entry of entries) {
+            const engram = ctx.repository.readEngram(entry.id);
+            lines.push(engramToDigestLine(engram));
+        }
+        const filtered = lines.filter((line) => matchesFilter(line, parsed.filter));
+        const limited = filtered.slice(0, parsed.limit);
+        return {
+            results: limited.map((line) => ({
+                id: line.id,
+                title: line.title,
+                kind: line.kind,
+                domainTags: line.domainTags,
+            })),
+            total: filtered.length,
+        };
+    },
+};
+/** Engram → DigestLine（用于过滤） */
+function engramToDigestLine(engram) {
+    return {
+        id: engram.id,
+        title: engram.title,
+        kind: engram.kind,
+        kinds: engram.kinds,
+        summary: engram.summary,
+        domainTags: engram.domainTags,
+        contextTags: engram.contextTags,
+        importance: engram.importance,
+        emotionalValence: engram.emotionalValence,
+        freshness: engram.freshness,
+        status: engram.status,
+        sourceType: engram.sourceType,
+        createdBy: engram.createdBy,
+        createdAt: engram.createdAt,
+        updatedAt: engram.updatedAt,
+        lastRetrievedAt: engram.lastRetrievedAt ?? null,
+        lastEffectiveAt: engram.lastEffectiveAt ?? null,
+        retrievalCount: engram.retrievalCount,
+        effectiveRetrievals: engram.effectiveRetrievals,
+        failedUses: engram.failedUses,
+        reinforcementScore: engram.reinforcementScore,
+        decayHalfLifeDays: engram.decayHalfLifeDays,
+        contentSize: engram.contentSize,
+        contentHash: engram.contentHash,
+        outgoingSynapseCount: engram.outgoingSynapseCount,
+        incomingSynapseCount: engram.incomingSynapseCount,
+        activeContradictionCount: engram.activeContradictionCount,
+    };
+}
+/**
+ * 写入操作后失效搜索索引,并立即从 repository 重建
+ *
+ * 之前的实现是 no-op,依赖 host adapter 手动 rebuild,但 host 无从得知何时该 rebuild,
+ * 导致用户新建 engram 后立即 engram_search 搜不到（索引是启动时的快照）。
+ *
+ * 当前实现:用 collectDigestLines(repo) 拉取真实 DigestLine[](含真实 importance /
+ * decayHalfLifeDays / retrievalCount / reinforcementScore 等),让三因子打分能正常工作。
+ *
+ * 代价是每次写入都做一次 O(N) rebuild；N 通常 < 10k,可接受。
+ * 后续 P1 改为增量更新（只插入/更新被改动的 engram）。
+ */
+function invalidateSearchIndex(ctx) {
+    if (!ctx.searchOrchestrator)
+        return;
+    ctx.searchOrchestrator.build(collectDigestLines(ctx.repository));
+}
+/** 读取 engram,失败时返回 null（不抛） */
+function safeReadEngram(ctx, id) {
+    try {
+        return ctx.repository.readEngram(id);
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================
+// engram_reinforce（P1：三信号追踪 - 有效检索 LTP）
+// ============================================================
+export const engramReinforceTool = {
+    name: "engram_reinforce",
+    description: "上报一次有效检索（LTP 强化 + Hebbian 关联强化）。更新 effectiveRetrievals / reinforcementScore / importance（每次 += effectiveness × 0.02，clamp [0,1]）；邻居 engram 得到 50% 增益（contradicts 除外）。",
+    inputSchema: EngramReinforceInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramReinforceInputSchema, input);
+        if (!ctx.repository.exists(parsed.id)) {
+            throw new Error(`Engram not found: ${parsed.id}`);
+        }
+        const nowIso = new Date().toISOString();
+        const direct = recordRetrievalSuccess(ctx.repository, parsed.id, parsed.effectiveness, DEFAULT_REINFORCEMENT_CONFIG, nowIso);
+        const related = reinforceRelated(ctx.repository, parsed.id, direct.importanceDelta, DEFAULT_REINFORCEMENT_CONFIG, nowIso);
+        // M1: 关闭观察窗口并标记为 effective（有效性信号）
+        ctx.effectivenessTracker?.closeAsEffective(parsed.id);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "reinforce",
+            engramId: parsed.id,
+            metadata: { effectiveness: parsed.effectiveness, note: parsed.note },
+        });
+        return {
+            id: parsed.id,
+            retrievalCount: direct.retrievalCount,
+            effectiveRetrievals: direct.effectiveRetrievals,
+            reinforcementScore: direct.reinforcementScore,
+            importance: direct.importance,
+            importanceDelta: direct.importanceDelta,
+            lastEffectiveAt: direct.lastEffectiveAt,
+            reinforcedNeighborIds: related.reinforcedNeighborIds,
+        };
+    },
+};
+// ============================================================
+// engram_report_failure（P1：三信号追踪 - 失败使用 LTD）
+// ============================================================
+export const engramReportFailureTool = {
+    name: "engram_report_failure",
+    description: "上报一次失败使用（LTD 削弱）。更新 failedUses / retrievalCount / importance（单次 -0.03，超阈值后 ×1.5 升级）。failedUses≥3 建议 archive，≥5 建议 forget。",
+    inputSchema: EngramReportFailureInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramReportFailureInputSchema, input);
+        if (!ctx.repository.exists(parsed.id)) {
+            throw new Error(`Engram not found: ${parsed.id}`);
+        }
+        const result = recordRetrievalFailure(ctx.repository, parsed.id, DEFAULT_REINFORCEMENT_CONFIG);
+        // M1: 关闭观察窗口（标记为 failure,不再触发 inconclusive）
+        ctx.effectivenessTracker?.closeAsFailure(parsed.id);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "report_failure",
+            engramId: parsed.id,
+            metadata: { reason: parsed.reason, context: parsed.context },
+        });
+        return {
+            id: parsed.id,
+            failedUses: result.failedUses,
+            retrievalCount: result.retrievalCount,
+            importance: result.importance,
+            importanceDelta: result.importanceDelta,
+            shouldArchive: result.shouldArchive,
+            shouldForget: result.shouldForget,
+        };
+    },
+};
+// ============================================================
+// engram_archive / restore / forget（P1：生命周期管理）
+// ============================================================
+export const engramArchiveTool = {
+    name: "engram_archive",
+    description: "归档 engram（移出默认检索，但保留数据可恢复）。检索默认排除 archived，可用 filter 包含。",
+    inputSchema: EngramArchiveInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramArchiveInputSchema, input);
+        if (!ctx.repository.exists(parsed.id)) {
+            throw new Error(`Engram not found: ${parsed.id}`);
+        }
+        ctx.repository.updateLifecycle(parsed.id, "archived", undefined);
+        const updated = ctx.repository.readEngram(parsed.id);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "update_lifecycle",
+            engramId: parsed.id,
+            metadata: { to: "archived", reason: parsed.reason },
+        });
+        return {
+            id: parsed.id,
+            status: "archived",
+            freshness: computeFreshness(updated.lastEffectiveAt, updated.decayHalfLifeDays),
+        };
+    },
+};
+export const engramRestoreTool = {
+    name: "engram_restore",
+    description: "从 archived/forgotten 恢复为 active，重新进入默认检索。若 engram 已被 sweep 到 .trash/,会先从回收站移回再恢复。",
+    inputSchema: EngramRestoreInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramRestoreInputSchema, input);
+        // 双路径查找：先查 active 区,再查 trash
+        let restoredFromTrash = false;
+        if (!ctx.repository.exists(parsed.id)) {
+            const trashResult = restoreFromTrash(ctx.repository, parsed.id, {
+                auditLog: ctx.auditLog,
+            });
+            if (!trashResult.ok) {
+                throw new Error(`Engram not found: ${parsed.id} (${trashResult.reason})`);
+            }
+            restoredFromTrash = true;
+        }
+        ctx.repository.updateLifecycle(parsed.id, "active", undefined);
+        const updated = ctx.repository.readEngram(parsed.id);
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "restore",
+            engramId: parsed.id,
+            metadata: { reason: parsed.reason },
+        });
+        return {
+            id: parsed.id,
+            status: "active",
+            freshness: computeFreshness(updated.lastEffectiveAt, updated.decayHalfLifeDays),
+            ...(restoredFromTrash ? { restoredFromTrash: true } : {}),
+        };
+    },
+};
+export const engramForgetTool = {
+    name: "engram_forget",
+    description: "主动遗忘 engram（RIF 检索诱导遗忘）。文件保留（Git 可追溯）但移出所有默认检索。需要 reason。",
+    inputSchema: EngramForgetInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramForgetInputSchema, input);
+        if (!ctx.repository.exists(parsed.id)) {
+            throw new Error(`Engram not found: ${parsed.id}`);
+        }
+        ctx.repository.updateLifecycle(parsed.id, "forgotten", "forgotten");
+        ctx.auditLog?.append({
+            actor: "user",
+            action: "forget",
+            engramId: parsed.id,
+            metadata: { reason: parsed.reason },
+        });
+        return { id: parsed.id, status: "forgotten", freshness: "forgotten" };
+    },
+};
+// ============================================================
+// engram_recompute_importance（P2：多维重要性）
+// ============================================================
+export const engramRecomputeImportanceTool = {
+    name: "engram_recompute_importance",
+    description: "重新计算 engram 的多维重要性（personal/team/project/network/temporal）。network 和 temporal 由系统派生（incomingSynapseCount + 艾宾浩斯衰退），其余可通过 overrides 手动设置。结果 composite 写回 engram.importance。",
+    inputSchema: EngramRecomputeImportanceInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(EngramRecomputeImportanceInputSchema, input);
+        const result = recomputeImportance(ctx.repository, parsed.id, {
+            overrides: parsed.overrides,
+            persist: parsed.persist,
+            updatedBy: parsed.updatedBy,
+        });
+        return {
+            id: result.id,
+            previous: result.previous,
+            next: result.next,
+            persisted: result.persisted,
+        };
+    },
+};
+// ============================================================
+// contradiction_resolve（P2：spec §3.9 人工裁决）
+// ============================================================
+export const contradictionResolveTool = {
+    name: "contradiction_resolve",
+    description: "人工裁决一个 contradicts synapse（spec §3.9 阶段 2 人工介入）。必须给 verdict + rationale + resolvedBy。系统会自动把 synapse.resolutionState 标记为 resolved 并记录到 evidence 数组。",
+    inputSchema: ContradictionResolveInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(ContradictionResolveInputSchema, input);
+        const result = manualResolveContradiction(ctx.repository, {
+            fromId: parsed.fromId,
+            synapseId: parsed.synapseId,
+            verdict: parsed.verdict,
+            rationale: parsed.rationale,
+            resolvedBy: parsed.resolvedBy,
+        });
+        return {
+            fromId: parsed.fromId,
+            synapseId: parsed.synapseId,
+            status: result.finalStatus,
+            resolved: true,
+        };
+    },
+};
+// ============================================================
+// close_learning_loop（P2：闭合学习回路，spec §5.3.5）
+// ============================================================
+export const closeLearningLoopTool = {
+    name: "close_learning_loop",
+    description: "闭合学习回路（多巴胺闭环）：把使用结果反馈到系统。success/partial → LTP 强化 + Hebbian 邻居强化；failure → LTD 削弱 + 触发降级阈值检查。同步触发 Provenance 奖惩回路（如已配置）。",
+    inputSchema: CloseLearningLoopInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(CloseLearningLoopInputSchema, input);
+        const result = closeLearningLoop(ctx.repository, {
+            engramId: parsed.engramId,
+            outcome: parsed.outcome,
+            effectiveness: parsed.effectiveness,
+            reason: parsed.reason,
+            reportedBy: parsed.reportedBy,
+        });
+        return {
+            engramId: result.engramId,
+            outcome: result.outcome,
+            importance: result.importance,
+            importanceDelta: result.importanceDelta,
+            hebbianTriggered: result.hebbianReinforcement.triggered,
+            provenanceTriggered: result.provenanceUpdate.triggered,
+            shouldArchive: result.shouldArchive,
+            shouldForget: result.shouldForget,
+        };
+    },
+};
+// ============================================================
+// upgrade_verification（P3 4.5.3：验证状态升级）
+// ============================================================
+export const upgradeVerificationTool = {
+    name: "upgrade_verification",
+    description: "升级 engram 的验证状态（unverified → plausible → probable → verified → refuted）。必须给出证据说明 + 验证人。系统会校验状态机（不允许跳级）+ 三维证据条件（evidenceCount + 跨情境 domainTags + 时间稳定天数）。force=true 可跳过条件检查但保留状态机校验（人工裁决场景）。",
+    inputSchema: UpgradeVerificationInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(UpgradeVerificationInputSchema, input);
+        const result = upgradeVerification(ctx.repository, parsed.engramId, parsed.newStatus, {
+            description: parsed.evidenceDescription,
+            verifiedBy: parsed.verifiedBy,
+            confidence: parsed.confidence,
+            domainTags: parsed.evidenceDomainTags,
+        }, {
+            force: parsed.force,
+        });
+        return {
+            engramId: result.engramId,
+            previousStatus: result.previousStatus,
+            newStatus: result.newStatus,
+            eligible: result.eligible,
+            applied: result.applied,
+            evidenceAppended: result.evidenceAppended,
+            synapseIds: result.synapseIds,
+            reason: result.reason,
+            checks: result.checks,
+        };
+    },
+};
+// ============================================================
+// get_evolution_lineage（P3 4.6.3：进化血统追溯）
+// ============================================================
+export const getEvolutionLineageTool = {
+    name: "get_evolution_lineage",
+    description: "追溯 engram 的进化血统（spec §12.7 场景 6）。沿 derives_from / consolidates / supersedes synapse 双向追溯：ancestors = 来源（observation 等），descendants = 演化结果（pattern/procedure 等）。返回 DAG 节点和边，可用于 Graph View 可视化。spec §4.6 验收：从 Skill 可反向追溯到原 observation 的完整链路。",
+    inputSchema: GetEvolutionLineageInputSchema,
+    execute(input, ctx) {
+        const parsed = validateInput(GetEvolutionLineageInputSchema, input);
+        const lineage = getEvolutionLineage(ctx.repository, parsed.engramId, {
+            direction: parsed.direction,
+            maxDepth: parsed.maxDepth,
+            kinds: parsed.kinds,
+        });
+        return {
+            rootId: lineage.rootId,
+            nodes: lineage.nodes,
+            edges: lineage.edges,
+            maxDepth: lineage.maxDepth,
+            totalNodes: lineage.totalNodes,
+            origins: lineage.origins,
+            terminals: lineage.terminals,
+            hasCycle: lineage.hasCycle,
+        };
+    },
+};
+export const ALL_ENGRAM_TOOLS = [
+    engramCreateTool,
+    engramGetTool,
+    engramUpdateTool,
+    engramDeleteTool,
+    engramSearchTool,
+    engramListTool,
+    engramReinforceTool,
+    engramReportFailureTool,
+    engramArchiveTool,
+    engramRestoreTool,
+    engramForgetTool,
+    engramRecomputeImportanceTool,
+    contradictionResolveTool,
+    closeLearningLoopTool,
+    upgradeVerificationTool,
+    getEvolutionLineageTool,
+];
+//# sourceMappingURL=engram-tools.js.map