@co-engram/core 0.1.0

package/dist/provenance/reliability.js

@@ -0,0 +1,213 @@
+/**
+ * Provenance 奖惩回路（spec §3.8 核心创新）
+ *
+ * 把单条 engram 的三信号追踪聚合到来源（createdBy）级别，形成信用系统：
+ *
+ *   sourceReliability = Σ effectiveRetrievals / (Σ effectiveRetrievals + Σ failedUses)
+ *
+ * 关键设计：派生而非存储（零额外字段）。每次需要时从所有 engram 的统计派生。
+ *
+ * 副作用（落盘时）：
+ *   - 低 reliability 来源旗下 engram 的 verificationStatus 降级（默认 → plausible）
+ *   - 高 reliability 来源的新 engram 初始 confidence 加成（默认 +0.1）
+ *
+ * 与 closeLearningLoop 集成：上层在 onProvenanceUpdate 回调中调用 applyProvenanceSignal，
+ * 或显式调用本模块独立 API。
+ *
+ * @module @co-engram/core/provenance
+ */
+export const DEFAULT_PROVENANCE_CONFIG = {
+    lowReliabilityThreshold: 0.4,
+    highReliabilityThreshold: 0.8,
+    confidenceBoost: 0.1,
+    minSampleSize: 3,
+    flaggedVerificationStatus: "plausible",
+};
+/**
+ * 派生单个来源的 reliability
+ *
+ * 实现细节：扫描所有 engram，过滤 createdBy 匹配的，累加三信号。
+ * 无样本时 reliability = 0.5（中性，避免一上来就被标记为低信用）。
+ */
+export function deriveSourceReliability(repo, createdBy) {
+    const entries = repo.listEngrams();
+    let totalEffective = 0;
+    let totalFailed = 0;
+    let totalRetrievals = 0;
+    let engramCount = 0;
+    for (const entry of entries) {
+        const engram = repo.readEngram(entry.id);
+        if (engram.createdBy !== createdBy)
+            continue;
+        totalEffective += engram.effectiveRetrievals;
+        totalFailed += engram.failedUses;
+        totalRetrievals += engram.retrievalCount;
+        engramCount += 1;
+    }
+    if (engramCount === 0)
+        return null;
+    const sampleSize = totalEffective + totalFailed;
+    const reliability = sampleSize === 0 ? 0.5 : totalEffective / sampleSize;
+    return {
+        createdBy,
+        totalEffective,
+        totalFailed,
+        totalRetrievals,
+        engramCount,
+        reliability,
+    };
+}
+/**
+ * 派生所有来源的 reliability
+ *
+ * 返回按 reliability 升序排序（最低信用在前，便于优先标记）。
+ */
+export function deriveAllSourceReliability(repo) {
+    const creators = new Set();
+    for (const entry of repo.listEngrams()) {
+        const engram = repo.readEngram(entry.id);
+        creators.add(engram.createdBy);
+    }
+    const result = [];
+    for (const createdBy of creators) {
+        const r = deriveSourceReliability(repo, createdBy);
+        if (r)
+            result.push(r);
+    }
+    result.sort((a, b) => {
+        if (a.reliability !== b.reliability)
+            return a.reliability - b.reliability;
+        return a.createdBy < b.createdBy ? -1 : 1;
+    });
+    return result;
+}
+/**
+ * 判定 reliability 是否为低/高信用
+ *
+ * 样本不足时一律不评判（避免新来源被误判）。
+ */
+export function classifyReliability(reliability, config = DEFAULT_PROVENANCE_CONFIG) {
+    const sample = reliability.totalEffective + reliability.totalFailed;
+    if (sample < config.minSampleSize) {
+        return { isLow: false, isHigh: false, insufficient: true };
+    }
+    return {
+        isLow: reliability.reliability < config.lowReliabilityThreshold,
+        isHigh: reliability.reliability >= config.highReliabilityThreshold,
+        insufficient: false,
+    };
+}
+/**
+ * Provenance 奖惩钩子
+ *
+ * 从 engramId 解析 createdBy，派生当前 reliability，返回信号快照。
+ *
+ * 注意：reliability 本身是派生的，三信号已经在 closeLearningLoop 的 LTP/LTD 阶段
+ * 更新到 engram 上，所以本函数只做"读取 + 分类"，不写盘。
+ *
+ * 副作用（如 verificationStatus 降级）通过 flagLowReliabilitySources 显式触发。
+ */
+export function applyProvenanceSignal(repo, engramId, outcome, effectiveness, options = {}) {
+    if (!repo.exists(engramId)) {
+        throw new Error(`Engram not found: ${engramId}`);
+    }
+    const cfg = {
+        ...DEFAULT_PROVENANCE_CONFIG,
+        ...options.config,
+    };
+    const engram = repo.readEngram(engramId);
+    const reliability = deriveSourceReliability(repo, engram.createdBy);
+    const cls = classifyReliability(reliability, cfg);
+    return {
+        engramId,
+        createdBy: engram.createdBy,
+        outcome,
+        effectiveness,
+        reliability,
+        isLowReliability: cls.isLow,
+        isHighReliability: cls.isHigh,
+        insufficientSamples: cls.insufficient,
+    };
+}
+/**
+ * 扫描所有来源，把低 reliability 来源旗下 engram 的 verificationStatus 降级
+ *
+ * 默认目标状态：plausible（spec §3.8：触发反思或标记为"不可信来源"）。
+ * 已是 refuted 的不升回 plausible（避免覆盖人工裁决）。
+ *
+ * @param persist true 则写盘 verificationStatus；false 只返回计算结果
+ */
+export function flagLowReliabilitySources(repo, options = {}) {
+    const cfg = {
+        ...DEFAULT_PROVENANCE_CONFIG,
+        ...options.config,
+    };
+    const persist = options.persist ?? true;
+    const all = deriveAllSourceReliability(repo);
+    const flagged = [];
+    for (const source of all) {
+        const cls = classifyReliability(source, cfg);
+        if (!cls.isLow)
+            continue;
+        const engramIds = [];
+        for (const entry of repo.listEngrams()) {
+            const engram = repo.readEngram(entry.id);
+            if (engram.createdBy !== source.createdBy)
+                continue;
+            // 已 refuted 的不覆盖（保留人工裁决）
+            if (engram.verificationStatus === "refuted") {
+                engramIds.push(entry.id);
+                continue;
+            }
+            // 已是目标状态的不重复写盘
+            if (engram.verificationStatus === cfg.flaggedVerificationStatus) {
+                engramIds.push(entry.id);
+                continue;
+            }
+            if (persist) {
+                repo.updateVerificationStatus(entry.id, cfg.flaggedVerificationStatus);
+            }
+            engramIds.push(entry.id);
+        }
+        if (engramIds.length > 0) {
+            flagged.push({
+                createdBy: source.createdBy,
+                reliability: source.reliability,
+                engramIds,
+            });
+        }
+    }
+    return { flagged, persisted: persist };
+}
+/**
+ * 计算高 reliability 来源新 engram 的初始 confidence 加成
+ *
+ * 用法：engram_create 时，先按 sourceType 默认 confidence 生成 base，
+ * 再调用本函数：如果 createdBy reliability 高，返回 min(1.0, base + boost)。
+ *
+ * @returns 调整后的 confidence ∈ [0,1]
+ */
+export function computeInitialConfidence(repo, createdBy, baseConfidence, options = {}) {
+    const cfg = {
+        ...DEFAULT_PROVENANCE_CONFIG,
+        ...options.config,
+    };
+    const reliability = deriveSourceReliability(repo, createdBy);
+    if (!reliability)
+        return clamp01(baseConfidence);
+    const cls = classifyReliability(reliability, cfg);
+    if (!cls.isHigh)
+        return clamp01(baseConfidence);
+    return clamp01(baseConfidence + cfg.confidenceBoost);
+}
+/** 数值截断到 [0,1] */
+function clamp01(x) {
+    if (Number.isNaN(x))
+        return 0;
+    if (x < 0)
+        return 0;
+    if (x > 1)
+        return 1;
+    return x;
+}
+//# sourceMappingURL=reliability.js.map

package/dist/provenance/reliability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliability.js","sourceRoot":"","sources":["../../src/provenance/reliability.ts"],"names":[],"mappings":"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"}

package/dist/reinforcement/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * LTP/LTD 强化机制配置
+ *
+ * Hebbian 原则："一起激活的神经元连接增强"
+ * LTP（Long-Term Potentiation）：有效检索 → importance 增强
+ * LTD（Long-Term Depression）：失败使用 → importance 削弱
+ *
+ * spec 6.2 默认值：
+ *   - 每次 effective=1 的检索 → importance += 0.02（10 次从 0.5 → 0.7）
+ *   - 邻居强化系数：0.5（直接邻居得到一半增益）
+ *   - LTD 单次惩罚：0.03（略大于 LTP 增益，符合"失败比成功更显著"的神经科学规律）
+ *
+ * @module @co-engram/core/reinforcement
+ */
+/** LTP/LTD 参数 */
+export interface ReinforcementConfig {
+    /** 每次 effective=1 检索的 importance 增益 */
+    readonly ltpGain: number;
+    /** 每次失败使用的 importance 削弱（绝对值） */
+    readonly ltdPenalty: number;
+    /** Hebbian 邻居强化系数 ∈ [0,1] */
+    readonly hebbianRatio: number;
+    /** 失败累积阈值：超过此值后额外惩罚 */
+    readonly failureThreshold: number;
+    /** 阈值之上的额外惩罚倍率 */
+    readonly failureEscalation: number;
+}
+/** 默认配置（spec 6.2） */
+export declare const DEFAULT_CONFIG: ReinforcementConfig;
+/**
+ * 校验配置合法性
+ */
+export declare function validateConfig(config: ReinforcementConfig): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/reinforcement/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/reinforcement/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,iBAAiB;AACjB,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uBAAuB;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kBAAkB;IAClB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,qBAAqB;AACrB,eAAO,MAAM,cAAc,EAAE,mBAM5B,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAsBhE"}

package/dist/reinforcement/config.js

@@ -0,0 +1,43 @@
+/**
+ * LTP/LTD 强化机制配置
+ *
+ * Hebbian 原则："一起激活的神经元连接增强"
+ * LTP（Long-Term Potentiation）：有效检索 → importance 增强
+ * LTD（Long-Term Depression）：失败使用 → importance 削弱
+ *
+ * spec 6.2 默认值：
+ *   - 每次 effective=1 的检索 → importance += 0.02（10 次从 0.5 → 0.7）
+ *   - 邻居强化系数：0.5（直接邻居得到一半增益）
+ *   - LTD 单次惩罚：0.03（略大于 LTP 增益，符合"失败比成功更显著"的神经科学规律）
+ *
+ * @module @co-engram/core/reinforcement
+ */
+/** 默认配置（spec 6.2） */
+export const DEFAULT_CONFIG = {
+    ltpGain: 0.02,
+    ltdPenalty: 0.03,
+    hebbianRatio: 0.5,
+    failureThreshold: 3,
+    failureEscalation: 1.5,
+};
+/**
+ * 校验配置合法性
+ */
+export function validateConfig(config) {
+    if (config.ltpGain <= 0 || config.ltpGain > 1) {
+        throw new Error(`ltpGain must be in (0,1], got ${config.ltpGain}`);
+    }
+    if (config.ltdPenalty <= 0 || config.ltdPenalty > 1) {
+        throw new Error(`ltdPenalty must be in (0,1], got ${config.ltdPenalty}`);
+    }
+    if (config.hebbianRatio < 0 || config.hebbianRatio > 1) {
+        throw new Error(`hebbianRatio must be in [0,1], got ${config.hebbianRatio}`);
+    }
+    if (config.failureThreshold < 1) {
+        throw new Error(`failureThreshold must be >= 1, got ${config.failureThreshold}`);
+    }
+    if (config.failureEscalation < 1) {
+        throw new Error(`failureEscalation must be >= 1, got ${config.failureEscalation}`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/reinforcement/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/reinforcement/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgBH,qBAAqB;AACrB,MAAM,CAAC,MAAM,cAAc,GAAwB;IACjD,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,GAAG;IACjB,gBAAgB,EAAE,CAAC;IACnB,iBAAiB,EAAE,GAAG;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAA2B;IACxD,IAAI,MAAM,CAAC,OAAO,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,iCAAiC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,sCAAsC,MAAM,CAAC,YAAY,EAAE,CAC5D,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,sCAAsC,MAAM,CAAC,gBAAgB,EAAE,CAChE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,uCAAuC,MAAM,CAAC,iBAAiB,EAAE,CAClE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/reinforcement/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reinforcement 模块 barrel
+ *
+ * LTP/LTD + Hebbian 关联强化
+ *
+ * @module @co-engram/core/reinforcement
+ */
+export * from "./config.js";
+export * from "./ltp.js";
+export * from "./ltd.js";
+export * from "./related.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/reinforcement/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reinforcement/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}

package/dist/reinforcement/index.js

@@ -0,0 +1,12 @@
+/**
+ * Reinforcement 模块 barrel
+ *
+ * LTP/LTD + Hebbian 关联强化
+ *
+ * @module @co-engram/core/reinforcement
+ */
+export * from "./config.js";
+export * from "./ltp.js";
+export * from "./ltd.js";
+export * from "./related.js";
+//# sourceMappingURL=index.js.map

package/dist/reinforcement/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reinforcement/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}

package/dist/reinforcement/ltd.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LTD（Long-Term Depression）- 失败使用削弱
+ *
+ * 神经科学依据：海马 LTD，长期不被激活或激活后失败的突触削弱。
+ * 业务含义：engram 被使用但失败 → importance 削弱。
+ *
+ * 触发场景：
+ *   - 工具调用基于该 engram 后出错
+ *   - LLM 引用后被指正
+ *   - engram 内容与实际情况冲突
+ *
+ * 实现：
+ *   - failedUses += 1
+ *   - retrievalCount += 1
+ *   - importance -= ltdPenalty × escalationFactor
+ *     · escalationFactor：失败累积 ≥ failureThreshold 后按 failureEscalation 倍增
+ *
+ * 触发降级条件（外层调用方判断）：
+ *   - failedUses >= 阈值（如 3）→ 自动 archive
+ *   - failedUses >= 高阈值（如 5）→ 自动 forget
+ *
+ * @module @co-engram/core/reinforcement
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { Engram } from "../types/engram.js";
+import { type ReinforcementConfig } from "./config.js";
+export interface LtdResult {
+    readonly id: string;
+    readonly importanceDelta: number;
+    readonly importance: number;
+    readonly failedUses: number;
+    readonly retrievalCount: number;
+    /** 是否触发降级建议（failedUses 达到阈值） */
+    readonly shouldArchive: boolean;
+    readonly shouldForget: boolean;
+}
+/** 默认降级阈值（失败次数达到即触发） */
+export declare const DEFAULT_ARCHIVE_THRESHOLD = 3;
+export declare const DEFAULT_FORGET_THRESHOLD = 5;
+/**
+ * 记录一次失败使用（LTD 削弱）
+ *
+ * importance 削弱规则：
+ *   - failedUses < failureThreshold：penalty = ltdPenalty
+ *   - failedUses >= failureThreshold：penalty = ltdPenalty × failureEscalation
+ *
+ * @param repo - 仓库
+ * @param id - 目标 engram id
+ * @param config - 配置（可选）
+ * @param archiveThreshold - 触发 archive 的 failedUses 阈值（默认 3）
+ * @param forgetThreshold - 触发 forget 的 failedUses 阈值（默认 5）
+ * @param nowIso - 当前时间
+ */
+export declare function recordRetrievalFailure(repo: EngramRepository, id: string, config?: ReinforcementConfig, archiveThreshold?: number, forgetThreshold?: number, nowIso?: string): LtdResult;
+/**
+ * 计算失败 N 次后的预期 importance（不写盘）
+ */
+export declare function projectImportanceAfterFailures(engram: Engram, times: number, config?: ReinforcementConfig): number;
+//# sourceMappingURL=ltd.d.ts.map

package/dist/reinforcement/ltd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ltd.d.ts","sourceRoot":"","sources":["../../src/reinforcement/ltd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,wBAAwB;AACxB,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,MAAM,GAAE,mBAAoC,EAC5C,gBAAgB,GAAE,MAAkC,EACpD,eAAe,GAAE,MAAiC,EAClD,MAAM,GAAE,MAAiC,GACxC,SAAS,CAkCX;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,mBAAoC,GAC3C,MAAM,CAaR"}

package/dist/reinforcement/ltd.js

@@ -0,0 +1,90 @@
+/**
+ * LTD（Long-Term Depression）- 失败使用削弱
+ *
+ * 神经科学依据：海马 LTD，长期不被激活或激活后失败的突触削弱。
+ * 业务含义：engram 被使用但失败 → importance 削弱。
+ *
+ * 触发场景：
+ *   - 工具调用基于该 engram 后出错
+ *   - LLM 引用后被指正
+ *   - engram 内容与实际情况冲突
+ *
+ * 实现：
+ *   - failedUses += 1
+ *   - retrievalCount += 1
+ *   - importance -= ltdPenalty × escalationFactor
+ *     · escalationFactor：失败累积 ≥ failureThreshold 后按 failureEscalation 倍增
+ *
+ * 触发降级条件（外层调用方判断）：
+ *   - failedUses >= 阈值（如 3）→ 自动 archive
+ *   - failedUses >= 高阈值（如 5）→ 自动 forget
+ *
+ * @module @co-engram/core/reinforcement
+ */
+import { DEFAULT_CONFIG } from "./config.js";
+/** 默认降级阈值（失败次数达到即触发） */
+export const DEFAULT_ARCHIVE_THRESHOLD = 3;
+export const DEFAULT_FORGET_THRESHOLD = 5;
+/**
+ * 记录一次失败使用（LTD 削弱）
+ *
+ * importance 削弱规则：
+ *   - failedUses < failureThreshold：penalty = ltdPenalty
+ *   - failedUses >= failureThreshold：penalty = ltdPenalty × failureEscalation
+ *
+ * @param repo - 仓库
+ * @param id - 目标 engram id
+ * @param config - 配置（可选）
+ * @param archiveThreshold - 触发 archive 的 failedUses 阈值（默认 3）
+ * @param forgetThreshold - 触发 forget 的 failedUses 阈值（默认 5）
+ * @param nowIso - 当前时间
+ */
+export function recordRetrievalFailure(repo, id, config = DEFAULT_CONFIG, archiveThreshold = DEFAULT_ARCHIVE_THRESHOLD, forgetThreshold = DEFAULT_FORGET_THRESHOLD, nowIso = new Date().toISOString()) {
+    if (!repo.exists(id)) {
+        throw new Error(`Engram not found: ${id}`);
+    }
+    if (archiveThreshold < 1 || forgetThreshold < archiveThreshold) {
+        throw new Error(`thresholds invalid: archive=${archiveThreshold}, forget=${forgetThreshold}`);
+    }
+    const before = repo.readEngram(id);
+    const newFailedUses = before.failedUses + 1;
+    const isEscalated = newFailedUses >= config.failureThreshold;
+    const penalty = isEscalated
+        ? config.ltdPenalty * config.failureEscalation
+        : config.ltdPenalty;
+    repo.bumpRetrievalStats(id, {
+        retrievedDelta: 1,
+        failedDelta: 1,
+        importanceDelta: -penalty,
+        lastRetrievedAt: nowIso,
+    });
+    const updated = repo.readEngram(id);
+    return {
+        id,
+        importanceDelta: -penalty,
+        importance: updated.importance,
+        failedUses: updated.failedUses,
+        retrievalCount: updated.retrievalCount,
+        shouldArchive: updated.failedUses >= archiveThreshold,
+        shouldForget: updated.failedUses >= forgetThreshold,
+    };
+}
+/**
+ * 计算失败 N 次后的预期 importance（不写盘）
+ */
+export function projectImportanceAfterFailures(engram, times, config = DEFAULT_CONFIG) {
+    let importance = engram.importance;
+    let failedUses = engram.failedUses;
+    for (let i = 0; i < times; i++) {
+        failedUses += 1;
+        const isEscalated = failedUses >= config.failureThreshold;
+        const penalty = isEscalated
+            ? config.ltdPenalty * config.failureEscalation
+            : config.ltdPenalty;
+        importance -= penalty;
+        if (importance <= 0)
+            return 0;
+    }
+    return Math.max(0, importance);
+}
+//# sourceMappingURL=ltd.js.map

package/dist/reinforcement/ltd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ltd.js","sourceRoot":"","sources":["../../src/reinforcement/ltd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,cAAc,EAA4B,MAAM,aAAa,CAAC;AAavE,wBAAwB;AACxB,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAsB,EACtB,EAAU,EACV,SAA8B,cAAc,EAC5C,mBAA2B,yBAAyB,EACpD,kBAA0B,wBAAwB,EAClD,SAAiB,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAEzC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,gBAAgB,GAAG,CAAC,IAAI,eAAe,GAAG,gBAAgB,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CACb,+BAA+B,gBAAgB,YAAY,eAAe,EAAE,CAC7E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACnC,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,aAAa,IAAI,MAAM,CAAC,gBAAgB,CAAC;IAC7D,MAAM,OAAO,GAAG,WAAW;QACzB,CAAC,CAAC,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,iBAAiB;QAC9C,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;IAEtB,IAAI,CAAC,kBAAkB,CAAC,EAAE,EAAE;QAC1B,cAAc,EAAE,CAAC;QACjB,WAAW,EAAE,CAAC;QACd,eAAe,EAAE,CAAC,OAAO;QACzB,eAAe,EAAE,MAAM;KACxB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACpC,OAAO;QACL,EAAE;QACF,eAAe,EAAE,CAAC,OAAO;QACzB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,aAAa,EAAE,OAAO,CAAC,UAAU,IAAI,gBAAgB;QACrD,YAAY,EAAE,OAAO,CAAC,UAAU,IAAI,eAAe;KACpD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAc,EACd,KAAa,EACb,SAA8B,cAAc;IAE5C,IAAI,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACnC,IAAI,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,UAAU,IAAI,CAAC,CAAC;QAChB,MAAM,WAAW,GAAG,UAAU,IAAI,MAAM,CAAC,gBAAgB,CAAC;QAC1D,MAAM,OAAO,GAAG,WAAW;YACzB,CAAC,CAAC,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,iBAAiB;YAC9C,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;QACtB,UAAU,IAAI,OAAO,CAAC;QACtB,IAAI,UAAU,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC"}

package/dist/reinforcement/ltp.d.ts

@@ -0,0 +1,63 @@
+/**
+ * LTP（Long-Term Potentiation）- 有效检索强化
+ *
+ * 神经科学依据：海马 LTP，重复激活的突触连接增强。
+ * 业务含义：engram 被实际使用并证明有效 → importance 提升。
+ *
+ * 触发场景：
+ *   - 工具调用结果被用户采纳
+ *   - LLM 引用后给出正面反馈
+ *   - 同样的 engram 被多次有效检索
+ *
+ * 实现：
+ *   - effectiveRetrievals += 1
+ *   - retrievalCount += 1
+ *   - reinforcementScore += effectiveness
+ *   - importance += effectiveness × ltpGain（clamp [0,1]）
+ *   - lastEffectiveAt = now
+ *
+ * @module @co-engram/core/reinforcement
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { Engram } from "../types/engram.js";
+import { type ReinforcementConfig } from "./config.js";
+export interface LtpResult {
+    readonly id: string;
+    readonly importanceDelta: number;
+    readonly importance: number;
+    readonly retrievalCount: number;
+    readonly effectiveRetrievals: number;
+    readonly reinforcementScore: number;
+    readonly lastEffectiveAt: string;
+}
+/**
+ * 记录一次有效检索（LTP 强化）
+ *
+ * 注意：本函数只更新统计 + importance，
+ * Hebbian 邻居强化请用 reinforceRelated()（related.ts）。
+ *
+ * @param repo - 仓库
+ * @param id - 目标 engram id
+ * @param effectiveness - 有效性 [0,1]，1=完全有效
+ * @param config - 配置（可选，默认 DEFAULT_CONFIG）
+ * @param nowIso - 当前时间（测试用，默认 new Date()）
+ */
+export declare function recordRetrievalSuccess(repo: EngramRepository, id: string, effectiveness: number, config?: ReinforcementConfig, nowIso?: string): LtpResult;
+/**
+ * 强化 engram（不更新 retrieval 统计，只提升 importance）
+ *
+ * 用于 Hebbian 间接强化（邻居得到增益时），
+ * 或外部队列触发的批量强化（如 Dreaming 周期）。
+ */
+export declare function reinforceEngram(repo: EngramRepository, id: string, amount: number, nowIso?: string): {
+    id: string;
+    importanceDelta: number;
+    importance: number;
+};
+/**
+ * 计算强化 N 次后的预期 importance（不写盘）
+ *
+ * 用于规划/模拟：例如想知道"再强化 5 次 importance 会到多少"。
+ */
+export declare function projectImportance(engram: Engram, times: number, effectivenessPerUse?: number, config?: ReinforcementConfig): number;
+//# sourceMappingURL=ltp.d.ts.map

package/dist/reinforcement/ltp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ltp.d.ts","sourceRoot":"","sources":["../../src/reinforcement/ltp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,mBAAoC,EAC5C,MAAM,GAAE,MAAiC,GACxC,SAAS,CA0BX;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAiC,GACxC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAiB7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,mBAAmB,SAAI,EACvB,MAAM,GAAE,mBAAoC,GAC3C,MAAM,CAOR"}

package/dist/reinforcement/ltp.js

@@ -0,0 +1,99 @@
+/**
+ * LTP（Long-Term Potentiation）- 有效检索强化
+ *
+ * 神经科学依据：海马 LTP，重复激活的突触连接增强。
+ * 业务含义：engram 被实际使用并证明有效 → importance 提升。
+ *
+ * 触发场景：
+ *   - 工具调用结果被用户采纳
+ *   - LLM 引用后给出正面反馈
+ *   - 同样的 engram 被多次有效检索
+ *
+ * 实现：
+ *   - effectiveRetrievals += 1
+ *   - retrievalCount += 1
+ *   - reinforcementScore += effectiveness
+ *   - importance += effectiveness × ltpGain（clamp [0,1]）
+ *   - lastEffectiveAt = now
+ *
+ * @module @co-engram/core/reinforcement
+ */
+import { DEFAULT_CONFIG } from "./config.js";
+/**
+ * 记录一次有效检索（LTP 强化）
+ *
+ * 注意：本函数只更新统计 + importance，
+ * Hebbian 邻居强化请用 reinforceRelated()（related.ts）。
+ *
+ * @param repo - 仓库
+ * @param id - 目标 engram id
+ * @param effectiveness - 有效性 [0,1]，1=完全有效
+ * @param config - 配置（可选，默认 DEFAULT_CONFIG）
+ * @param nowIso - 当前时间（测试用，默认 new Date()）
+ */
+export function recordRetrievalSuccess(repo, id, effectiveness, config = DEFAULT_CONFIG, nowIso = new Date().toISOString()) {
+    if (effectiveness < 0 || effectiveness > 1) {
+        throw new Error(`effectiveness must be in [0,1], got ${effectiveness}`);
+    }
+    if (!repo.exists(id)) {
+        throw new Error(`Engram not found: ${id}`);
+    }
+    const importanceDelta = effectiveness * config.ltpGain;
+    repo.bumpRetrievalStats(id, {
+        retrievedDelta: 1,
+        effectiveDelta: 1,
+        reinforcementDelta: effectiveness,
+        importanceDelta,
+        lastRetrievedAt: nowIso,
+        lastEffectiveAt: nowIso,
+    });
+    const updated = repo.readEngram(id);
+    return {
+        id,
+        importanceDelta,
+        importance: updated.importance,
+        retrievalCount: updated.retrievalCount,
+        effectiveRetrievals: updated.effectiveRetrievals,
+        reinforcementScore: updated.reinforcementScore,
+        lastEffectiveAt: updated.lastEffectiveAt ?? nowIso,
+    };
+}
+/**
+ * 强化 engram（不更新 retrieval 统计，只提升 importance）
+ *
+ * 用于 Hebbian 间接强化（邻居得到增益时），
+ * 或外部队列触发的批量强化（如 Dreaming 周期）。
+ */
+export function reinforceEngram(repo, id, amount, nowIso = new Date().toISOString()) {
+    if (!repo.exists(id)) {
+        throw new Error(`Engram not found: ${id}`);
+    }
+    if (amount < 0) {
+        throw new Error(`amount must be >= 0, got ${amount}`);
+    }
+    repo.bumpRetrievalStats(id, {
+        importanceDelta: amount,
+        lastEffectiveAt: nowIso,
+    });
+    const updated = repo.readEngram(id);
+    return {
+        id,
+        importanceDelta: amount,
+        importance: updated.importance,
+    };
+}
+/**
+ * 计算强化 N 次后的预期 importance（不写盘）
+ *
+ * 用于规划/模拟：例如想知道"再强化 5 次 importance 会到多少"。
+ */
+export function projectImportance(engram, times, effectivenessPerUse = 1, config = DEFAULT_CONFIG) {
+    let importance = engram.importance;
+    for (let i = 0; i < times; i++) {
+        importance += effectivenessPerUse * config.ltpGain;
+        if (importance >= 1)
+            return 1;
+    }
+    return Math.min(1, importance);
+}
+//# sourceMappingURL=ltp.js.map