@co-engram/core 0.1.2 → 0.1.3

package/dist/concepts/dictionary.d.ts

@@ -0,0 +1,260 @@
+/**
+ * CONCEPT_DICTIONARY —— 概念字典单一真相源
+ *
+ * 所有用户可见 surface(viewer help tab、mcp instructions、prompt-builder、工具描述)
+ * 引用此处的概念解释,而不是各自维护一份(否则会出现概念漂移,见 fix-2 的
+ * help-contract 抓到的 synapse/proposal 漂移)。
+ *
+ * 默认值必须与源码一致:
+ *   - ReinforcementConfig.DEFAULT_CONFIG(ltpGain=0.02 等)
+ *   - DEFAULT_EFFECTIVENESS_WINDOWS(observation=6h 等)
+ *   - DEFAULT_VERIFICATION_CONFIG(minEvidenceForPlausible=1 等)
+ *   - DEFAULT_WEIGHTS(alpha=0.5 等)
+ *
+ * 修改默认值时,改源码同时改这里 —— fix-3 的运行时 FORBIDDEN_TERMS 校验 + fix-5 的
+ * 默认值审计会捕获不一致。
+ *
+ * @module @co-engram/core/concepts
+ */
+import type { ConceptEntry, ConceptId, ScoreBand } from "./types.js";
+/**
+ * 概念字典本体
+ *
+ * `satisfies Readonly<Record<ConceptId, ConceptEntry>>` 强制每个 ConceptId 都有 entry,
+ * 添加新 id 但忘了填字典会编译失败。
+ */
+export declare const CONCEPT_DICTIONARY: {
+    readonly engram: {
+        readonly id: "engram";
+        readonly zh: "记忆印迹";
+        readonly en: "engram";
+        readonly userExplanation: {
+            readonly zh: "一条被持久化的团队记忆。每条记忆有标题、内容、领域标签,以及随使用强度变化的『重要性』分数。一条记忆可以被多次检索、强化或反驳,状态会随使用反馈演化。";
+            readonly en: "A persistent team memory entry with a title, content, domain tags, and an \"importance\" score that evolves with use. Each memory can be retrieved, reinforced, or refuted multiple times — its state evolves with feedback.";
+        };
+        readonly internalRule: {
+            readonly zh: "存储为 markdown + frontmatter,文件路径默认 {domainTags}/{slug}.md。5 种 kind:observation / fact / pattern / procedure / hypothesis。";
+            readonly en: "Stored as markdown + frontmatter, default path {domainTags}/{slug}.md. 5 kinds: observation / fact / pattern / procedure / hypothesis.";
+        };
+        readonly refs: readonly ["synapse", "importance", "kind", "domain_tag"];
+    };
+    readonly synapse: {
+        readonly id: "synapse";
+        readonly zh: "记忆突触";
+        readonly en: "synapse";
+        readonly userExplanation: {
+            readonly zh: "两条记忆印迹之间的有类型连接(类似大脑里神经元之间的突触)。常见类型:extends(扩展)、derives_from(派生/证据)、contradicts(矛盾)、related_to(关联)。突触让记忆从孤立条目变成知识图谱。";
+            readonly en: "A typed connection between two engrams (like synapses between neurons). Common kinds: extends, derives_from (evidence), contradicts, related_to. Synapses turn isolated entries into a knowledge graph.";
+        };
+        readonly internalRule: {
+            readonly zh: "kind=\"contradicts\" 时,自动给双方 engram 写 contradicted audit 事件(可被 engram_audit_query 查到),触发矛盾解决流程。";
+            readonly en: "When kind=\"contradicts\", automatically writes contradicted audit events to both engrams (queryable via engram_audit_query), triggering the contradiction resolution flow.";
+        };
+        readonly refs: readonly ["engram", "verification_status"];
+    };
+    readonly ltp: {
+        readonly id: "ltp";
+        readonly zh: "长时程增强(LTP)";
+        readonly en: "Long-Term Potentiation (LTP)";
+        readonly userExplanation: {
+            readonly zh: "记忆被有效使用时,重要性上升的机制。每次『有效检索』(用户真的用到这条记忆解决了任务)给这条记忆的重要性 +0.02(默认)。这是大脑里『一起激活的神经元连接增强』(Hebbian)的简化模型。";
+            readonly en: "The mechanism by which a memory's importance rises on effective use. Each \"effective retrieval\" (the user actually applied the memory to solve a task) adds +0.02 (default) to its importance. This is a simplified model of Hebbian learning (\"neurons that fire together wire together\").";
+        };
+        readonly internalRule: {
+            readonly zh: "每次 effective=1 检索,importance += ltpGain(默认 0.02)。10 次有效检索约能把 0.5 提升到 0.7。";
+            readonly en: "Per effective=1 retrieval, importance += ltpGain (default 0.02). ~10 effective retrievals raise 0.5 to ~0.7.";
+        };
+        readonly refs: readonly ["importance", "observation_window", "hebbian"];
+    };
+    readonly ltd: {
+        readonly id: "ltd";
+        readonly zh: "长时程削弱(LTD)";
+        readonly en: "Long-Term Depression (LTD)";
+        readonly userExplanation: {
+            readonly zh: "记忆被错误使用时,重要性下降的机制。每次『失败使用』(用户反馈说这条记忆错了/过时)给重要性 -0.03(默认)。失败惩罚略大于成功增益,符合『失败比成功更显著』的神经科学规律。";
+            readonly en: "The mechanism by which a memory's importance falls on failed use. Each \"failed use\" (user reports the memory was wrong or stale) subtracts 0.03 (default) from importance. The penalty slightly exceeds the LTP gain, matching the neuroscience finding that failures weigh more than successes.";
+        };
+        readonly internalRule: {
+            readonly zh: "每次 failedUse,importance -= ltdPenalty(默认 0.03);累积失败超过 failureThreshold(默认 3)次后,按 failureEscalation(默认 1.5)倍率额外惩罚。";
+            readonly en: "Per failedUse, importance -= ltdPenalty (default 0.03); once cumulative failures exceed failureThreshold (default 3), an extra failureEscalation (default 1.5) multiplier applies.";
+        };
+        readonly refs: readonly ["ltp", "importance", "observation_window"];
+    };
+    readonly hebbian: {
+        readonly id: "hebbian";
+        readonly zh: "Hebbian 原则";
+        readonly en: "Hebbian principle";
+        readonly userExplanation: {
+            readonly zh: "『一起激活的神经元连接增强』。在 co-engram 里:强化一条记忆时,与它直接相连(通过突触)的邻居记忆也会得到一部分增益(默认一半,即 0.5 倍),让相关知识一起被记住。";
+            readonly en: "\"Neurons that fire together wire together.\" In co-engram: when a memory is reinforced, its direct neighbors (via synapses) also gain a fraction of the boost (default half, i.e. 0.5x) — so related knowledge gets remembered together.";
+        };
+        readonly internalRule: {
+            readonly zh: "邻居强化系数 = hebbianRatio(默认 0.5)。直接邻居得到 ltpGain × hebbianRatio 的 importance 增益。";
+            readonly en: "Neighbor reinforcement ratio = hebbianRatio (default 0.5). Direct neighbors gain ltpGain × hebbianRatio importance.";
+        };
+        readonly refs: readonly ["ltp", "synapse", "importance"];
+    };
+    readonly rpe: {
+        readonly id: "rpe";
+        readonly zh: "奖励预测误差(RPE)";
+        readonly en: "Reward Prediction Error (RPE)";
+        readonly userExplanation: {
+            readonly zh: "实际价值超出预期的程度。在大脑里,阳性 RPE(比预期好)会触发多巴胺释放,加强相关记忆。co-engram 借用这个概念驱动『候选审批』—— 系统观察到的、超出阈值的新模式会被提名为候选记忆,等用户确认后转为正式记忆。";
+            readonly en: "The gap between actual and expected value. In the brain, positive RPE (better than expected) triggers dopamine release and strengthens associated memories. co-engram borrows this for proposal capture — observed patterns exceeding a threshold are nominated as candidate memories awaiting user approval.";
+        };
+        readonly internalRule: {
+            readonly zh: "necessity-evaluator 通过 LLM 或规则评估『这条消息是否值得捕获』,必要度超阈值才进入 proposal 队列。";
+            readonly en: "The necessity-evaluator (LLM or rule-based) assesses \"is this message worth capturing\"; only those above the threshold enter the proposal queue.";
+        };
+        readonly refs: readonly ["engram", "importance"];
+    };
+    readonly verification_status: {
+        readonly id: "verification_status";
+        readonly zh: "验证状态";
+        readonly en: "verification status";
+        readonly userExplanation: {
+            readonly zh: "记忆可信度的 5 档状态:未验证 → 似合理 → 较可能 → 已验证 → 已反驳。状态随使用反馈(强化 / 失败 / 跨情境证据)演化。已反驳状态会阻止这条记忆再次被检索命中。";
+            readonly en: "5-level memory credibility: unverified → plausible → probable → verified → refuted. Evolves with use feedback (reinforcement / failure / cross-context evidence). Refuted memories are excluded from retrieval.";
+        };
+        readonly internalRule: {
+            readonly zh: "升级条件(默认):似合理需 ≥1 evidence;较可能需 ≥2 evidence 且 ≥2 个不同 domainTags;已验证需 ≥3 evidence、≥2 domains 且创建满 7 天。降级由 LTD/失败驱动。";
+            readonly en: "Default upgrade thresholds: plausible ≥1 evidence; probable ≥2 evidence AND ≥2 distinct domainTags; verified ≥3 evidence, ≥2 domains, AND 7 days since creation. Downgrade driven by LTD/failures.";
+        };
+        readonly refs: readonly ["observation_window", "provenance", "synapse"];
+    };
+    readonly observation_window: {
+        readonly id: "observation_window";
+        readonly zh: "观察窗口";
+        readonly en: "observation window";
+        readonly userExplanation: {
+            readonly zh: "记忆被检索命中后开启的一段观察期。窗口期内:用户若回来强化这条记忆 → 记为『有效检索』,触发 LTP;用户若反馈失败 → 记为『失败使用』,触发 LTD;窗口过期 → 关闭,本次命中不计入有效性。窗口长度按 kind 不同:观察类 6 小时、事实/模式/流程类 1-2 天、假设类 7 天。";
+            readonly en: "An observation period opened when a memory is retrieved. During the window: if the user returns to reinforce the memory → counted as \"effective retrieval\" (triggers LTP); if the user reports a failure → counted as \"failed use\" (triggers LTD); if the window expires → closed, this hit does not count. Length depends on kind: observation 6h, fact/pattern/procedure 1-2d, hypothesis 7d.";
+        };
+        readonly internalRule: {
+            readonly zh: "默认窗口长度:observation=6h,fact=24h,pattern=48h,procedure=48h,hypothesis=7d。多 kind engram 取最长。";
+            readonly en: "Default window lengths: observation=6h, fact=24h, pattern=48h, procedure=48h, hypothesis=7d. Multi-kind engrams use the maximum.";
+        };
+        readonly refs: readonly ["ltp", "ltd", "kind"];
+    };
+    readonly importance: {
+        readonly id: "importance";
+        readonly zh: "重要性";
+        readonly en: "importance";
+        readonly userExplanation: {
+            readonly zh: "记忆的优先级分数,取值 [0,1]。检索结果按相关性 + 时效性 + 重要性三因子加权打分排序。重要性会随 LTP 上升、LTD 下降,所以常用且有效的记忆会自然浮上来。";
+            readonly en: "Memory priority score in [0,1]. Retrieval results are ranked by a weighted three-factor score: relevance + recency + importance. Importance rises with LTP and falls with LTD, so frequently-effective memories naturally surface.";
+        };
+        readonly internalRule: {
+            readonly zh: "三因子权重(默认):relevance α=0.5,recency β=0.3,importance γ=0.2。effectiveImportance = importance × (1 + reinforcementScore),截断到 [0,1]。";
+            readonly en: "Default three-factor weights: relevance α=0.5, recency β=0.3, importance γ=0.2. effectiveImportance = importance × (1 + reinforcementScore), clamped to [0,1].";
+        };
+        readonly refs: readonly ["ltp", "ltd", "decay"];
+    };
+    readonly decay: {
+        readonly id: "decay";
+        readonly zh: "艾宾浩斯衰退";
+        readonly en: "Ebbinghaus decay";
+        readonly userExplanation: {
+            readonly zh: "记忆随时间淡化。检索打分里 recency 因子按艾宾浩斯遗忘曲线衰退:每过一个半衰期,recency 减半。半衰期由 decayHalfLifeDays 配置(若为 null 表示永不衰退,如永久性事实)。";
+            readonly en: "Memories fade over time. The \"recency\" retrieval factor follows the Ebbinghaus forgetting curve: each half-life halves the recency. The half-life is set by decayHalfLifeDays (null = never decays, e.g. permanent facts).";
+        };
+        readonly internalRule: {
+            readonly zh: "recency = 0.5^(ageDays / decayHalfLifeDays)。ageDays ≤ 0 或 decayHalfLifeDays ≤ 0 时 recency = 1(不衰退)。";
+            readonly en: "recency = 0.5^(ageDays / decayHalfLifeDays). When ageDays ≤ 0 or decayHalfLifeDays ≤ 0, recency = 1 (no decay).";
+        };
+        readonly refs: readonly ["importance"];
+    };
+    readonly provenance: {
+        readonly id: "provenance";
+        readonly zh: "溯源";
+        readonly en: "provenance";
+        readonly userExplanation: {
+            readonly zh: "每条记忆的来源信息:谁创建、何时创建、sourceType(firsthand / secondhand / inferred)。验收高可信结论前,应通过溯源信息判断原始证据是否可靠。";
+            readonly en: "Each memory carries its origin: who created it, when, and sourceType (firsthand / secondhand / inferred). Before relying on a high-confidence conclusion, check provenance to judge if the underlying evidence is trustworthy.";
+        };
+        readonly refs: readonly ["engram", "verification_status"];
+    };
+    readonly domain_tag: {
+        readonly id: "domain_tag";
+        readonly zh: "领域标签";
+        readonly en: "domain tag";
+        readonly userExplanation: {
+            readonly zh: "记忆的主题分类(如 testing、android、backend)。用于检索过滤、跨情境证据聚合(verification 升级条件需要 ≥2 个不同 domainTags)、目录组织。一条记忆可有多个领域标签。";
+            readonly en: "Memory topic (e.g. testing, android, backend). Used for retrieval filtering, cross-context evidence aggregation (verification upgrade requires ≥2 distinct domainTags), and directory layout. A memory can have multiple domain tags.";
+        };
+        readonly refs: readonly ["engram", "context_tag", "verification_status"];
+    };
+    readonly context_tag: {
+        readonly id: "context_tag";
+        readonly zh: "情境标签";
+        readonly en: "context tag";
+        readonly userExplanation: {
+            readonly zh: "比领域标签更细粒度的使用情境(如 session-id、子项目名)。用于跨情境证据聚合 —— 同样的结论在不同情境被独立验证,可信度才更高。";
+            readonly en: "Finer-grained use context than domain tags (e.g. session-id, sub-project). Used for cross-context evidence aggregation — the same conclusion independently verified across different contexts yields higher credibility.";
+        };
+        readonly refs: readonly ["domain_tag", "verification_status"];
+    };
+    readonly kind: {
+        readonly id: "kind";
+        readonly zh: "类别";
+        readonly en: "kind";
+        readonly userExplanation: {
+            readonly zh: "记忆的 5 种基础类别:观察(单次所见)、事实(多次验证)、模式(跨情境抽象)、流程(陈述性步骤)、假设(AI 推断、待验证)。类别决定观察窗口长度、检索权重等行为。";
+            readonly en: "5 base kinds: observation (single sighting), fact (verified multiple times), pattern (cross-context abstraction), procedure (declarative steps), hypothesis (AI-inferred, to be verified). The kind drives observation-window length, retrieval weights, and other behaviors.";
+        };
+        readonly internalRule: {
+            readonly zh: "observation 窗口 6h;fact 24h;pattern/procedure 48h;hypothesis 7d。多 kind 取 max。";
+            readonly en: "observation window 6h; fact 24h; pattern/procedure 48h; hypothesis 7d. Multi-kind uses max.";
+        };
+        readonly refs: readonly ["engram", "observation_window", "domain_tag"];
+    };
+};
+/**
+ * 取概念条目(便于从 id 安全访问)
+ *
+ * 直接 `CONCEPT_DICTIONARY[id]` 也行;此函数主要给宿主代码显式标注返回类型。
+ */
+export declare function getConcept(id: ConceptId): ConceptEntry;
+/**
+ * 把 [0,1] 浮点分数格式化为人类可读的『高/中/低(数值)』
+ *
+ * 用于所有用户可见的数值字段(importance / reinforcementScore / lastRetrievalScore /
+ * FTS score / effectiveness),防止浮点精度泄露(如 0.018000000000000002、
+ * 0.7719155626908514 直接 dump 给用户)。
+ *
+ * 阈值:≥0.7 高;≥0.3 中;<0.3 低。2 位小数保留可读精度。
+ *
+ * JSON-RPC 协议层(raw)与文本呈现层(band+display)并存,见 Task 1.3。
+ */
+export declare function formatScore(score: number, lang: "zh" | "en"): string;
+/**
+ * 工具返回结果里的结构化分数字段
+ *
+ * `raw` 是 2 位小数(rounded),保证 JSON 序列化不会泄露浮点噪声
+ * (如 0.018000000000000002 / 0.7719155626908514)。
+ *
+ * `band` 是语言中立的等级枚举,host adapter / viewer 用 translatePrompt
+ * 或本地 i18n 字典把它本地化为『高』/『high』等。
+ *
+ * 设计原因:不在 core 层硬编码中文,保持 host-agnostic(元2 dual-host 契约)。
+ */
+export interface ScoreField {
+    /** 2 位小数(rounded),JSON-safe */
+    readonly raw: number;
+    /** 语言中立等级:high (≥0.7) / medium (≥0.3) / low (<0.3) */
+    readonly band: ScoreBand;
+}
+/**
+ * 把裸浮点封装为 ScoreField
+ *
+ * 同时做两件事:
+ *   1. round 到 2 位小数,杀掉浮点噪声(0.018000000000000002 → 0.02)
+ *   2. 计算 band(high/medium/low),供 host adapter 渲染
+ *
+ * 单独抽出是因为多个工具(engram_get / engram_reinforce / engram_recompute_importance /
+ * engram_search)都要做同样的处理,集中一处避免漂移。
+ */
+export declare function formatScoreField(raw: number): ScoreField;
+/** 重导出类型,方便 `import { CONCEPT_DICTIONARY, type ConceptEntry } from "..."` */
+export type { ConceptEntry, ConceptId, ScoreBand } from "./types.js";
+//# sourceMappingURL=dictionary.d.ts.map

package/dist/concepts/dictionary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictionary.d.ts","sourceRoot":"","sources":["../../src/concepts/dictionary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsM+B,CAAC;AAE/D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,SAAS,GAAG,YAAY,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAQpE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKxD;AAED,6EAA6E;AAC7E,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/concepts/dictionary.js

@@ -0,0 +1,253 @@
+/**
+ * CONCEPT_DICTIONARY —— 概念字典单一真相源
+ *
+ * 所有用户可见 surface(viewer help tab、mcp instructions、prompt-builder、工具描述)
+ * 引用此处的概念解释,而不是各自维护一份(否则会出现概念漂移,见 fix-2 的
+ * help-contract 抓到的 synapse/proposal 漂移)。
+ *
+ * 默认值必须与源码一致:
+ *   - ReinforcementConfig.DEFAULT_CONFIG(ltpGain=0.02 等)
+ *   - DEFAULT_EFFECTIVENESS_WINDOWS(observation=6h 等)
+ *   - DEFAULT_VERIFICATION_CONFIG(minEvidenceForPlausible=1 等)
+ *   - DEFAULT_WEIGHTS(alpha=0.5 等)
+ *
+ * 修改默认值时,改源码同时改这里 —— fix-3 的运行时 FORBIDDEN_TERMS 校验 + fix-5 的
+ * 默认值审计会捕获不一致。
+ *
+ * @module @co-engram/core/concepts
+ */
+/**
+ * 概念字典本体
+ *
+ * `satisfies Readonly<Record<ConceptId, ConceptEntry>>` 强制每个 ConceptId 都有 entry,
+ * 添加新 id 但忘了填字典会编译失败。
+ */
+export const CONCEPT_DICTIONARY = {
+    engram: {
+        id: "engram",
+        zh: "记忆印迹",
+        en: "engram",
+        userExplanation: {
+            zh: "一条被持久化的团队记忆。每条记忆有标题、内容、领域标签,以及随使用强度变化的『重要性』分数。一条记忆可以被多次检索、强化或反驳,状态会随使用反馈演化。",
+            en: 'A persistent team memory entry with a title, content, domain tags, and an "importance" score that evolves with use. Each memory can be retrieved, reinforced, or refuted multiple times — its state evolves with feedback.',
+        },
+        internalRule: {
+            zh: "存储为 markdown + frontmatter,文件路径默认 {domainTags}/{slug}.md。5 种 kind:observation / fact / pattern / procedure / hypothesis。",
+            en: "Stored as markdown + frontmatter, default path {domainTags}/{slug}.md. 5 kinds: observation / fact / pattern / procedure / hypothesis.",
+        },
+        refs: ["synapse", "importance", "kind", "domain_tag"],
+    },
+    synapse: {
+        id: "synapse",
+        zh: "记忆突触",
+        en: "synapse",
+        userExplanation: {
+            zh: "两条记忆印迹之间的有类型连接(类似大脑里神经元之间的突触)。常见类型:extends(扩展)、derives_from(派生/证据)、contradicts(矛盾)、related_to(关联)。突触让记忆从孤立条目变成知识图谱。",
+            en: "A typed connection between two engrams (like synapses between neurons). Common kinds: extends, derives_from (evidence), contradicts, related_to. Synapses turn isolated entries into a knowledge graph.",
+        },
+        internalRule: {
+            zh: 'kind="contradicts" 时,自动给双方 engram 写 contradicted audit 事件(可被 engram_audit_query 查到),触发矛盾解决流程。',
+            en: 'When kind="contradicts", automatically writes contradicted audit events to both engrams (queryable via engram_audit_query), triggering the contradiction resolution flow.',
+        },
+        refs: ["engram", "verification_status"],
+    },
+    ltp: {
+        id: "ltp",
+        zh: "长时程增强(LTP)",
+        en: "Long-Term Potentiation (LTP)",
+        userExplanation: {
+            zh: "记忆被有效使用时,重要性上升的机制。每次『有效检索』(用户真的用到这条记忆解决了任务)给这条记忆的重要性 +0.02(默认)。这是大脑里『一起激活的神经元连接增强』(Hebbian)的简化模型。",
+            en: 'The mechanism by which a memory\'s importance rises on effective use. Each "effective retrieval" (the user actually applied the memory to solve a task) adds +0.02 (default) to its importance. This is a simplified model of Hebbian learning ("neurons that fire together wire together").',
+        },
+        internalRule: {
+            zh: "每次 effective=1 检索,importance += ltpGain(默认 0.02)。10 次有效检索约能把 0.5 提升到 0.7。",
+            en: "Per effective=1 retrieval, importance += ltpGain (default 0.02). ~10 effective retrievals raise 0.5 to ~0.7.",
+        },
+        refs: ["importance", "observation_window", "hebbian"],
+    },
+    ltd: {
+        id: "ltd",
+        zh: "长时程削弱(LTD)",
+        en: "Long-Term Depression (LTD)",
+        userExplanation: {
+            zh: "记忆被错误使用时,重要性下降的机制。每次『失败使用』(用户反馈说这条记忆错了/过时)给重要性 -0.03(默认)。失败惩罚略大于成功增益,符合『失败比成功更显著』的神经科学规律。",
+            en: 'The mechanism by which a memory\'s importance falls on failed use. Each "failed use" (user reports the memory was wrong or stale) subtracts 0.03 (default) from importance. The penalty slightly exceeds the LTP gain, matching the neuroscience finding that failures weigh more than successes.',
+        },
+        internalRule: {
+            zh: "每次 failedUse,importance -= ltdPenalty(默认 0.03);累积失败超过 failureThreshold(默认 3)次后,按 failureEscalation(默认 1.5)倍率额外惩罚。",
+            en: "Per failedUse, importance -= ltdPenalty (default 0.03); once cumulative failures exceed failureThreshold (default 3), an extra failureEscalation (default 1.5) multiplier applies.",
+        },
+        refs: ["ltp", "importance", "observation_window"],
+    },
+    hebbian: {
+        id: "hebbian",
+        zh: "Hebbian 原则",
+        en: "Hebbian principle",
+        userExplanation: {
+            zh: "『一起激活的神经元连接增强』。在 co-engram 里:强化一条记忆时,与它直接相连(通过突触)的邻居记忆也会得到一部分增益(默认一半,即 0.5 倍),让相关知识一起被记住。",
+            en: '"Neurons that fire together wire together." In co-engram: when a memory is reinforced, its direct neighbors (via synapses) also gain a fraction of the boost (default half, i.e. 0.5x) — so related knowledge gets remembered together.',
+        },
+        internalRule: {
+            zh: "邻居强化系数 = hebbianRatio(默认 0.5)。直接邻居得到 ltpGain × hebbianRatio 的 importance 增益。",
+            en: "Neighbor reinforcement ratio = hebbianRatio (default 0.5). Direct neighbors gain ltpGain × hebbianRatio importance.",
+        },
+        refs: ["ltp", "synapse", "importance"],
+    },
+    rpe: {
+        id: "rpe",
+        zh: "奖励预测误差(RPE)",
+        en: "Reward Prediction Error (RPE)",
+        userExplanation: {
+            zh: "实际价值超出预期的程度。在大脑里,阳性 RPE(比预期好)会触发多巴胺释放,加强相关记忆。co-engram 借用这个概念驱动『候选审批』—— 系统观察到的、超出阈值的新模式会被提名为候选记忆,等用户确认后转为正式记忆。",
+            en: "The gap between actual and expected value. In the brain, positive RPE (better than expected) triggers dopamine release and strengthens associated memories. co-engram borrows this for proposal capture — observed patterns exceeding a threshold are nominated as candidate memories awaiting user approval.",
+        },
+        internalRule: {
+            zh: 'necessity-evaluator 通过 LLM 或规则评估『这条消息是否值得捕获』,必要度超阈值才进入 proposal 队列。',
+            en: 'The necessity-evaluator (LLM or rule-based) assesses "is this message worth capturing"; only those above the threshold enter the proposal queue.',
+        },
+        refs: ["engram", "importance"],
+    },
+    verification_status: {
+        id: "verification_status",
+        zh: "验证状态",
+        en: "verification status",
+        userExplanation: {
+            zh: "记忆可信度的 5 档状态:未验证 → 似合理 → 较可能 → 已验证 → 已反驳。状态随使用反馈(强化 / 失败 / 跨情境证据)演化。已反驳状态会阻止这条记忆再次被检索命中。",
+            en: "5-level memory credibility: unverified → plausible → probable → verified → refuted. Evolves with use feedback (reinforcement / failure / cross-context evidence). Refuted memories are excluded from retrieval.",
+        },
+        internalRule: {
+            zh: "升级条件(默认):似合理需 ≥1 evidence;较可能需 ≥2 evidence 且 ≥2 个不同 domainTags;已验证需 ≥3 evidence、≥2 domains 且创建满 7 天。降级由 LTD/失败驱动。",
+            en: "Default upgrade thresholds: plausible ≥1 evidence; probable ≥2 evidence AND ≥2 distinct domainTags; verified ≥3 evidence, ≥2 domains, AND 7 days since creation. Downgrade driven by LTD/failures.",
+        },
+        refs: ["observation_window", "provenance", "synapse"],
+    },
+    observation_window: {
+        id: "observation_window",
+        zh: "观察窗口",
+        en: "observation window",
+        userExplanation: {
+            zh: "记忆被检索命中后开启的一段观察期。窗口期内:用户若回来强化这条记忆 → 记为『有效检索』,触发 LTP;用户若反馈失败 → 记为『失败使用』,触发 LTD;窗口过期 → 关闭,本次命中不计入有效性。窗口长度按 kind 不同:观察类 6 小时、事实/模式/流程类 1-2 天、假设类 7 天。",
+            en: 'An observation period opened when a memory is retrieved. During the window: if the user returns to reinforce the memory → counted as "effective retrieval" (triggers LTP); if the user reports a failure → counted as "failed use" (triggers LTD); if the window expires → closed, this hit does not count. Length depends on kind: observation 6h, fact/pattern/procedure 1-2d, hypothesis 7d.',
+        },
+        internalRule: {
+            zh: "默认窗口长度:observation=6h,fact=24h,pattern=48h,procedure=48h,hypothesis=7d。多 kind engram 取最长。",
+            en: "Default window lengths: observation=6h, fact=24h, pattern=48h, procedure=48h, hypothesis=7d. Multi-kind engrams use the maximum.",
+        },
+        refs: ["ltp", "ltd", "kind"],
+    },
+    importance: {
+        id: "importance",
+        zh: "重要性",
+        en: "importance",
+        userExplanation: {
+            zh: "记忆的优先级分数,取值 [0,1]。检索结果按相关性 + 时效性 + 重要性三因子加权打分排序。重要性会随 LTP 上升、LTD 下降,所以常用且有效的记忆会自然浮上来。",
+            en: "Memory priority score in [0,1]. Retrieval results are ranked by a weighted three-factor score: relevance + recency + importance. Importance rises with LTP and falls with LTD, so frequently-effective memories naturally surface.",
+        },
+        internalRule: {
+            zh: "三因子权重(默认):relevance α=0.5,recency β=0.3,importance γ=0.2。effectiveImportance = importance × (1 + reinforcementScore),截断到 [0,1]。",
+            en: "Default three-factor weights: relevance α=0.5, recency β=0.3, importance γ=0.2. effectiveImportance = importance × (1 + reinforcementScore), clamped to [0,1].",
+        },
+        refs: ["ltp", "ltd", "decay"],
+    },
+    decay: {
+        id: "decay",
+        zh: "艾宾浩斯衰退",
+        en: "Ebbinghaus decay",
+        userExplanation: {
+            zh: "记忆随时间淡化。检索打分里 recency 因子按艾宾浩斯遗忘曲线衰退:每过一个半衰期,recency 减半。半衰期由 decayHalfLifeDays 配置(若为 null 表示永不衰退,如永久性事实)。",
+            en: 'Memories fade over time. The "recency" retrieval factor follows the Ebbinghaus forgetting curve: each half-life halves the recency. The half-life is set by decayHalfLifeDays (null = never decays, e.g. permanent facts).',
+        },
+        internalRule: {
+            zh: "recency = 0.5^(ageDays / decayHalfLifeDays)。ageDays ≤ 0 或 decayHalfLifeDays ≤ 0 时 recency = 1(不衰退)。",
+            en: "recency = 0.5^(ageDays / decayHalfLifeDays). When ageDays ≤ 0 or decayHalfLifeDays ≤ 0, recency = 1 (no decay).",
+        },
+        refs: ["importance"],
+    },
+    provenance: {
+        id: "provenance",
+        zh: "溯源",
+        en: "provenance",
+        userExplanation: {
+            zh: "每条记忆的来源信息:谁创建、何时创建、sourceType(firsthand / secondhand / inferred)。验收高可信结论前,应通过溯源信息判断原始证据是否可靠。",
+            en: "Each memory carries its origin: who created it, when, and sourceType (firsthand / secondhand / inferred). Before relying on a high-confidence conclusion, check provenance to judge if the underlying evidence is trustworthy.",
+        },
+        refs: ["engram", "verification_status"],
+    },
+    domain_tag: {
+        id: "domain_tag",
+        zh: "领域标签",
+        en: "domain tag",
+        userExplanation: {
+            zh: "记忆的主题分类(如 testing、android、backend)。用于检索过滤、跨情境证据聚合(verification 升级条件需要 ≥2 个不同 domainTags)、目录组织。一条记忆可有多个领域标签。",
+            en: "Memory topic (e.g. testing, android, backend). Used for retrieval filtering, cross-context evidence aggregation (verification upgrade requires ≥2 distinct domainTags), and directory layout. A memory can have multiple domain tags.",
+        },
+        refs: ["engram", "context_tag", "verification_status"],
+    },
+    context_tag: {
+        id: "context_tag",
+        zh: "情境标签",
+        en: "context tag",
+        userExplanation: {
+            zh: "比领域标签更细粒度的使用情境(如 session-id、子项目名)。用于跨情境证据聚合 —— 同样的结论在不同情境被独立验证,可信度才更高。",
+            en: "Finer-grained use context than domain tags (e.g. session-id, sub-project). Used for cross-context evidence aggregation — the same conclusion independently verified across different contexts yields higher credibility.",
+        },
+        refs: ["domain_tag", "verification_status"],
+    },
+    kind: {
+        id: "kind",
+        zh: "类别",
+        en: "kind",
+        userExplanation: {
+            zh: "记忆的 5 种基础类别:观察(单次所见)、事实(多次验证)、模式(跨情境抽象)、流程(陈述性步骤)、假设(AI 推断、待验证)。类别决定观察窗口长度、检索权重等行为。",
+            en: "5 base kinds: observation (single sighting), fact (verified multiple times), pattern (cross-context abstraction), procedure (declarative steps), hypothesis (AI-inferred, to be verified). The kind drives observation-window length, retrieval weights, and other behaviors.",
+        },
+        internalRule: {
+            zh: "observation 窗口 6h;fact 24h;pattern/procedure 48h;hypothesis 7d。多 kind 取 max。",
+            en: "observation window 6h; fact 24h; pattern/procedure 48h; hypothesis 7d. Multi-kind uses max.",
+        },
+        refs: ["engram", "observation_window", "domain_tag"],
+    },
+};
+/**
+ * 取概念条目(便于从 id 安全访问)
+ *
+ * 直接 `CONCEPT_DICTIONARY[id]` 也行;此函数主要给宿主代码显式标注返回类型。
+ */
+export function getConcept(id) {
+    return CONCEPT_DICTIONARY[id];
+}
+/**
+ * 把 [0,1] 浮点分数格式化为人类可读的『高/中/低(数值)』
+ *
+ * 用于所有用户可见的数值字段(importance / reinforcementScore / lastRetrievalScore /
+ * FTS score / effectiveness),防止浮点精度泄露(如 0.018000000000000002、
+ * 0.7719155626908514 直接 dump 给用户)。
+ *
+ * 阈值:≥0.7 高;≥0.3 中;<0.3 低。2 位小数保留可读精度。
+ *
+ * JSON-RPC 协议层(raw)与文本呈现层(band+display)并存,见 Task 1.3。
+ */
+export function formatScore(score, lang) {
+    const band = score >= 0.7 ? "high" : score >= 0.3 ? "medium" : "low";
+    const labels = {
+        zh: { high: "高", medium: "中", low: "低" },
+        en: { high: "high", medium: "medium", low: "low" },
+    };
+    return `${labels[lang][band]}(${score.toFixed(2)})`;
+}
+/**
+ * 把裸浮点封装为 ScoreField
+ *
+ * 同时做两件事:
+ *   1. round 到 2 位小数,杀掉浮点噪声(0.018000000000000002 → 0.02)
+ *   2. 计算 band(high/medium/low),供 host adapter 渲染
+ *
+ * 单独抽出是因为多个工具(engram_get / engram_reinforce / engram_recompute_importance /
+ * engram_search)都要做同样的处理,集中一处避免漂移。
+ */
+export function formatScoreField(raw) {
+    const rounded = Math.round(raw * 100) / 100;
+    const band = rounded >= 0.7 ? "high" : rounded >= 0.3 ? "medium" : "low";
+    return { raw: rounded, band };
+}
+//# sourceMappingURL=dictionary.js.map

package/dist/concepts/dictionary.js.map

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

package/dist/concepts/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 概念字典 —— co-engram 神经科学概念的单一真相源
+ *
+ * 详见 {@link dictionary.ts} 的 docstring。
+ *
+ * @module @co-engram/core/concepts
+ */
+export * from "./types.js";
+export { CONCEPT_DICTIONARY, getConcept, formatScore, formatScoreField, } from "./dictionary.js";
+export type { ScoreField } from "./dictionary.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/concepts/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/concepts/index.js

@@ -0,0 +1,10 @@
+/**
+ * 概念字典 —— co-engram 神经科学概念的单一真相源
+ *
+ * 详见 {@link dictionary.ts} 的 docstring。
+ *
+ * @module @co-engram/core/concepts
+ */
+export * from "./types.js";
+export { CONCEPT_DICTIONARY, getConcept, formatScore, formatScoreField, } from "./dictionary.js";
+//# sourceMappingURL=index.js.map

package/dist/concepts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/concepts/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/concepts/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 概念字典类型定义
+ *
+ * co-engram 引入大量神经科学概念(engram / synapse / LTP / LTD / Hebbian / RPE /
+ * verification state machine / observation window / multi-dim importance 等)。
+ * 元3「神经科学墙」的核心症状是:这些概念对挑剔用户完全不可见,规则藏在源码里。
+ *
+ * CONCEPT_DICTIONARY 是这些概念的单一真相源,所有面向用户的 surface
+ * (viewer help tab / mcp instructions / prompt-builder / 工具描述)都必须引用它,
+ * 不允许在别处重新定义。
+ *
+ * @module @co-engram/core/concepts
+ */
+/**
+ * 概念 ID(全部小写下划线,稳定标识)
+ *
+ * 添加新概念时:
+ *   1. 在此 union 加 id
+ *   2. 在 dictionary.ts 填 ConceptEntry(必填 zh / en / userExplanation)
+ *   3. 若有内部规则,补 internalRule(人类可读描述,引用真实默认值)
+ *   4. 通过 `satisfies Readonly<Record<ConceptId, ConceptEntry>>` 让编译器强制全覆盖
+ */
+export type ConceptId = "engram" | "synapse" | "ltp" | "ltd" | "hebbian" | "rpe" | "verification_status" | "observation_window" | "importance" | "decay" | "provenance" | "domain_tag" | "context_tag" | "kind";
+/**
+ * 概念字典条目
+ *
+ * 设计原则:
+ *   - zh / en 是内部术语(可保留专业用词,允许"LTP"、"Hebbian"等缩写)
+ *   - userExplanation 是面向挑剔用户的解释(避免术语堆砌,讲清楚是什么、为什么有用)
+ *   - internalRule 引用真实源码默认值(不写"约 0.02",写"0.02"),便于用户验证
+ *   - refs 把相关概念串起来,viewer help tab 可据此渲染图
+ */
+export interface ConceptEntry {
+    /** 稳定 id(等于 CONCEPT_DICTIONARY 里的 key) */
+    readonly id: ConceptId;
+    /** 内部中文术语(可保留专业缩写) */
+    readonly zh: string;
+    /** 内部英文术语 */
+    readonly en: string;
+    /** 用户层解释 */
+    readonly userExplanation: {
+        /** 中文用户解释(挑剔用户能懂,不堆砌术语) */
+        readonly zh: string;
+        /** 英文用户解释 */
+        readonly en: string;
+    };
+    /** 内部规则(引用真实默认值,如"每次 effective 检索 importance += 0.02") */
+    readonly internalRule?: {
+        /** 中文规则描述 */
+        readonly zh: string;
+        /** 英文规则描述 */
+        readonly en: string;
+    };
+    /** 相关概念 id 列表(用于 viewer help 渲染关系图) */
+    readonly refs?: readonly ConceptId[];
+}
+/**
+ * 重要性 / 强化分数的可读分级
+ *
+ * 用于把 [0,1] 区间的浮点(importance / reinforcementScore / lastRetrievalScore /
+ * FTS score)映射为"高/中/低"用户可读形式,防止浮点精度泄露
+ * (如 0.018000000000000002 直接 dump 给用户)。
+ */
+export type ScoreBand = "high" | "medium" | "low";
+//# sourceMappingURL=types.d.ts.map

package/dist/concepts/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/concepts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,KAAK,GACL,KAAK,GACL,SAAS,GACT,KAAK,GACL,qBAAqB,GACrB,oBAAoB,GACpB,YAAY,GACZ,OAAO,GACP,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,MAAM,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,aAAa;IACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,YAAY;IACZ,QAAQ,CAAC,eAAe,EAAE;QACxB,2BAA2B;QAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,aAAa;QACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,aAAa;QACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,aAAa;QACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,uCAAuC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC"}