dsh-loci 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0.0.
 
+## [2.4.0] — 2026-11-15
+
+Three items from `docs/PRIOR-ART.md` — the systematic pass over what the field does
+better, judged against this plugin's four invariants rather than by popularity.
+
+### Added
+
+- **Lesson shape (`pattern` / `fix` / `prevents` / `whenCondition`)**, schema v3. A
+  lesson stored as free text is unreadable six months later: you remember the rule but
+  not why it exists. `prevents` is where that answer lives, and it is the one clause
+  appended to the index line for `procedural` entries — a rule without its consequence
+  gets ignored. Ordinary facts render byte-identically to before, and the fields never
+  raise trust.
+
+- **`conflicts` / `extends` relations.** `memory_edge` has always had a `relation`
+  column but only ever held `supersedes`, so every correction was a full replacement.
+  Real corrections are partial — "the rollback window is 45 minutes now, but database
+  changes still get 30" contradicts one clause and confirms another. Now a caller can
+  declare a weaker relation, both entries stay readable, and `loci_get` shows the link.
+
+- **Touched files in the episodic summary.** "Where were we last time" was a question
+  this project had to answer by hand. File paths are now extracted from tool-call
+  arguments and recorded on the session summary, which is never injected — so it costs
+  the prompt nothing and only helps `loci_search`.
+
+### Migration
+
+Schema v2 → v3 adds four nullable columns; no row can be lost and every existing entry
+simply has no lesson shape yet. The integration test now walks the whole shipped chain
+v1 → v3 rather than a single step.
+
+### Not done, on purpose
+
+Auto-triggered injection (`when` matching decides what gets injected) stays rejected:
+it breaks prefix stability and lets memory content decide its own admission. The
+condition is **stored and shown, never used to select**. Recorded with the rest of the
+rejections in `docs/PRIOR-ART.md` §2.
+
 ## [2.3.1] — 2026-11-15
 
 ### Fixed

package/client.js

@@ -131,6 +131,12 @@ window.__ModuleLoader__.load({
       'panel.history': 'History',
       'panel.evidence': 'Evidence',
       'panel.source': 'Source',
+      'panel.lesson': 'Lesson',
+      'panel.lesson.pattern': 'pattern',
+      'panel.lesson.fix': 'fix',
+      'panel.lesson.prevents': 'prevents',
+      'panel.lesson.when': 'when',
+      'panel.relations': 'Relations',
       'panel.candidates': 'Candidates',
       'panel.disputed': 'Disputed',
       'panel.noCandidates': 'Nothing waiting for review.',
@@ -254,6 +260,12 @@ window.__ModuleLoader__.load({
       'panel.history': '历史',
       'panel.evidence': '证据',
       'panel.source': '出处',
+      'panel.lesson': '教训',
+      'panel.lesson.pattern': '问题形态',
+      'panel.lesson.fix': '做法',
+      'panel.lesson.prevents': '不做会怎样',
+      'panel.lesson.when': '适用场景',
+      'panel.relations': '关联',
       'panel.candidates': '候选',
       'panel.disputed': '争议',
       'panel.noCandidates': '没有待审条目。',
@@ -742,7 +754,7 @@ window.__ModuleLoader__.load({
 
     function Detail({ id, t, onBack, onChange }) {
       const { data, error, loading, reload } = useJson(`/item?id=${encodeURIComponent(id)}&history=1`);
-      const entry = data?.entry;
+      // \edges\ is a sibling of \entry\ in the API payload; fold it in so the detail view\n      // can show declared relations without a second request.\n      const entry = data?.entry === undefined ? undefined : { ...data.entry, edges: data.edges ?? [] };
       const act = async (path, body) => {
         try {
           await apiFetch(path, { method: 'POST', body: JSON.stringify(body) });
@@ -810,6 +822,43 @@ window.__ModuleLoader__.load({
               ),
               h('div', { className: 'loci-section' }, 'Body'),
               h('pre', { className: 'loci-pre' }, entry.body),
+              // A lesson's shape, and the relations that record a partial correction.
+              // Both are read-only here: they come from the write that created the entry.
+              ['pattern', 'fix', 'prevents', 'when'].some((key) => typeof entry[key === 'when' ? 'whenCondition' : key] === 'string')
+                ? h(
+                    'div',
+                    null,
+                    h('div', { className: 'loci-section' }, t('panel.lesson')),
+                    h(
+                      'dl',
+                      { className: 'loci-kv' },
+                      ...['pattern', 'fix', 'prevents', 'when'].flatMap((key) => {
+                        const value = entry[key === 'when' ? 'whenCondition' : key];
+                        return typeof value === 'string' && value.length > 0
+                          ? [h('dt', { key: `${key}-k` }, t(`panel.lesson.${key}`)), h('dd', { key: `${key}-v` }, value)]
+                          : [];
+                      }),
+                    ),
+                  )
+                : null,
+              (entry.edges ?? []).some((edge) => edge.relation === 'conflicts' || edge.relation === 'extends')
+                ? h(
+                    'div',
+                    null,
+                    h('div', { className: 'loci-section' }, t('panel.relations')),
+                    ...(entry.edges ?? [])
+                      .filter((edge) => edge.relation === 'conflicts' || edge.relation === 'extends')
+                      .map((edge) => {
+                        const other = edge.src_id === entry.id ? edge.dst_id : edge.src_id;
+                        return h(
+                          'div',
+                          { key: `${edge.relation}-${other}`, className: 'loci-meta' },
+                          h('span', null, edge.relation),
+                          h('code', { className: 'loci-id' }, other),
+                        );
+                      }),
+                  )
+                : null,
               entry.sourceRef
                 ? h(
                     'div',

package/docs/PRIOR-ART.md

@@ -0,0 +1,121 @@
+# PRIOR ART — 我们从别人那里借鉴什么、拒绝什么，以及为什么
+
+- 状态：living（每次评估新插件后更新）
+- 读者：本项目维护者与后续 agent（内部设计文档）
+- 用途：把「看过哪些实现、为什么采纳/拒绝」记在一处，避免重复调研，也避免我凭印象做决定。
+
+> 这份文档的存在原因：本项目一度是"用户提一个、我做一个"的反应式开发。
+> 2026-11-15 的一次反问（"不要我说一个你就搞一个"）之后补上系统性盘点。
+
+## 0. 评估基准（loci 的四条硬不变量）
+
+一条设计值不值得抄，先过这四关。违反任何一条的，无论多流行，都不抄：
+
+| # | 不变量 | 含义 |
+|---|---|---|
+| **I1** | 注入闸门 | 只有 `verified` 进提示词；candidate 必须经人核实 |
+| **I2** | 前缀稳定 | 无写入时，注入段字节级不变（保 KV/prefix cache） |
+| **I3** | 默认零网络 | 除两条可选出网路径外不发请求 |
+| **I4** | 作用域显式 | 读永不越界；不存在"猜出来的"作用域 |
+
+## 1. 已采纳（2026-11 三次发布）
+
+| 来源 | 借鉴点 | 我们怎么落地 | 版本 |
+|---|---|---|---|
+| Claude Code memory | 索引 + 主题文件两层；正文永不入提示词 | 索引段只放 id/kind/日期/标题，正文靠 `loci_get` | 1.0 |
+| mem0 | 注入字节数作为一等指标 | `request_stat.section_bytes` + 面板注入记录 | 1.0 |
+| mem0 | 截断要吵，不能静默 | `total`/`hasMore`/`cursor` + "还有 N 条" | 1.x |
+| supermemory | 推断事实要人审（approve/decline） | 待审队列 + `verified` 只能人工授予 | 1.3 |
+| dsh-auto-memory | 4 态信任机 + 逐字证据 | candidate/verified/disputed/superseded + quote 闸门 | 1.3 |
+| dsh-ltm | 修订 CAS、迁移前快照 | `expectedRevision` + `VACUUM INTO` | 1.x |
+| Letta / mem0 | 用量是一等事实（不是装饰） | `memory_usage` 表：inject/read 计数 | 2.1 |
+| Claude Code memory | 索引超限要显式告知 | 待审提示行（"N 条待审，故意不在此处"） | 2.1 |
+| mem0 | 抽取异步、不占用户延迟 | 会话结束一次性 digest，仅写候选 | 2.3 |
+
+## 2. 值得借鉴、尚未做（按性价比排序）
+
+### A 级 — 建议下一版做
+
+**A1. 教训的结构化形态（`pattern` / `fix` / `prevents`）**
+- 来源：`dsh-project-memory` 的 `save_lesson`
+- 问题：loci 的 `procedural` 是自由文本。半年后只看到一句话，看不出"不做会怎样"。
+- 落地：schema v3 加可空列 `pattern`/`fix`/`prevents`/`when_condition`；索引行对 procedural 追加 `— prevents: …`（受 `indexLineMaxChars` 约束，默认 120）。
+- 风险：索引行变长 → 触发 I2 退化？不会：只在写入时改变一次，之后字节稳定。
+- 成本：低（一次迁移 + 一处渲染）。
+
+**A2. 按活跃度淘汰"注入了但从未读"的条目**
+- 来源：`dsh-memory-tiers`（六层 + "忘"是流程的一步）、`mem0`（decay 只在检索时生效）、`dsh-fish-memory`（逐条衰减）
+- 问题：我们 2.1 装了电表（inject/read 计数），却没有任何策略消费它。
+- 落地：`procedural` 类中 `read_count = 0 且 inject_count ≥ N` 者从索引段降级（仍可 `loci_search`），`doctor` 单列一行。
+- 风险：误伤"读了但没 `loci_get`（索引行已够用）"的条目 → 用 `read_count + 被引用次数` 双阈值，并先只影响 procedural。
+- 成本：中（策略 + 统计口径）。
+
+**A3. 冲突的显式表达（而不只是 supersede）**
+- 来源：`memory-eternal` / `supermemory`（`updates`/`extends`/`derives` 边 + `isLatest`）
+- 问题：我们现在**只能**"新条目取代旧条目"。真实场景常是"这条改了一半"——例如"回滚窗口 30 分钟"→"回滚窗口 45 分钟，但数据库变更仍是 30 分钟"。
+- 落地：`memory_edge` 表已有 `relation` 字段，但**全库只用了一个取值** `supersedes`（`store.js:405`）；补 `conflicts`/`extends` 两种即可复用现有表与索引，无需迁移。`loci_get` 显示"与 m_yyy 冲突/延伸"；注入段不改（仍旧一条），冲突在面板里呈现。
+- 风险：低（只增边，不改注入）。
+- 成本：中。
+
+**A4. 会话工作状态的"最小接续面"（TaskBridge 的可借部分）**
+- 来源：`dsh-project-memory` 的 **TaskBridge**（跨会话任务 + 触碰过的文件，切走再续接）
+- 问题：这次会话里我反复手工重建"改过哪些文件、下一步是什么"。loci 现在的 episodic 摘要只存会话文字片段（`capture.js:373-389`），**不记录触碰过的文件**，所以下个会话搜不到"上次改到哪"。
+- 落地（最小版，不引入任务面板）：在 episodic 摘要里增加一个结构化字段 `filesTouched`（从本会话工具调用的路径参数提取，去重、限量 30 条），并把它写进摘要正文的一个短列表。episodic **本来就不注入**（`capture.js` 注释：历史不是主张），所以对 **I1/I2 零影响**——只改善"按需检索"。
+- 明确不做：任务面板、todo 同步、跨会话绑定（那是 `dsh-project-memory` 的完整产品面）。
+- 成本：低（一次提取 + 一处写入）。价值：高（解决"接续要重新问一遍"）。
+
+### B 级 — 有价值，但需要先想清楚
+
+**B1. 报告"记忆缺失"的能力**
+- 来源：`dsh-auto-memory` 的 recall funnel（注入了但从没被读）、`mem0` 的 mean tokens/query
+- 想法：区分"没有这条记忆"和"有但没召回"。我们已经有 `loci_search` 的 `matchedTotal: null`，但没有"这次会话模型查了什么、没查到什么"的视图。
+- 需要想清楚：这属于诊断还是产品？会不会变成又一个用户不看的统计页？
+
+**B2. 导入/导出与跨工具互通**
+- 来源：`dsh-cross-memory`（一个库接 DSH/Claude/Codex/Cursor）、Claude Code 的 `@path` 导入
+- 现状：我们只做了 auto-memory 与 Claude memory 的**单向导入**。
+- 需要想清楚：双向同步会引入冲突解决，而冲突解决正是 A3 还没做的。→ 先做 A3，再谈互通。
+
+**B3. 常驻"画像"层（persona）**
+- 来源：`dsh-cross-memory` 的 `persona/human.md`（会话开始注入快照，可锁定防后台改写）
+- 想法：把我们散在 `global` scope 的偏好收敛成一个可锁定的小块。
+- 顾虑：与索引段功能重叠；且"画像被改写"是用户最敏感的失败。**倾向不做**，除非有真实需求。
+
+### C 级 — 明确拒绝（并记录理由）
+
+| 拒绝项 | 来源 | 理由 |
+|---|---|---|
+| 条件注入（`when`/`guard` 自动触发） | `dsh-project-memory`、`supermemory` | 违反 **I2**：每步都可能改段内容，KV 前缀失效；也违反"可预测"的产品承诺。可选折中：`when_condition` 只存不判，供检索与面板显示 |
+| 写入时自动 cosine 合并（0.9 覆盖） | `dsh-project-memory` | 0.9 相似也可能语义相反（"必须做 X" vs "不许做 X"）。我们保留手动 `merge` + 乐观锁 |
+| 空闲"做梦"式整合 | `meow-memory`、Letta `dreaming`、`zzerx` | 后台无监督改写记忆，是"我明明没改它却变了"的来源。**必须有人在场** |
+| 自动 scope 晋升（task→project→global） | `dsh-project-memory` 的两/三次晋升 | 违反 **I4**：作用域由使用次数漂移，跨项目泄漏风险不可接受 |
+| 每轮全量抽取 | `zzerx`、`dsh-cross-memory` 后台抽取 | 每轮一次模型调用 + 每轮一条待审，实测会让人放弃审阅（2.3 的 digest 就是为此而生） |
+| 把语料正文当注入触发源 | 多家 | 正文可被污染 → 等于让记忆内容决定自己是否入提示词 |
+| 外部记忆服务（Hindsight / Honcho / supermemory 云） | `dsh-hindsight`、mnemon providers | 违反 **I3**；且我们权衡过：一次网络往返换来的召回提升不值得把记忆送出去 |
+| 常驻大块（resident USER.md/MEMORY.md 全文注入） | `dsh-mnemon` | 提示词成本不可控；索引 + 按需取正文是更省的形状 |
+| **代码/文档索引（"读到即索引"）** | `dsh-project-memory`、`basic-memory` | 那是**对仓库内容的 RAG**，不是记忆。加进来会多一条检索通道、一套过期语义和一份"代码的第二份副本"；代码与 AGENTS.md 已是 SSOT，`grep` 比索引更可信 |
+| **自动触发式注入（`when` 命中即注入）** | `dsh-project-memory`、`supermemory` | 只保留"存条件"（见 A1 的 `when_condition`），**不保留"由条件决定是否注入"**；理由同样是 **I2** |
+
+## 3. 口径变更记录（为什么不一致，而不是假装一致）
+
+这份文档的第一版与我会话里的口头建议**不一致**，此处记录差异与裁决：
+
+| 我先前口头说的 | 文档最初的处置 | 现在的裁决 |
+|---|---|---|
+| 触发式注入"值得借鉴" | 直接进了 C 级拒绝 | **改判为部分采纳**：`when_condition` 存而不判（A1）。口头说"值得借鉴"时我只想到"条件命中更准"，没想到它会破坏 I2 与"正文不能决定自己是否注入"这条安全线 |
+| TaskBridge"值得借鉴" | **漏写**（文档里根本没有） | **补为 A4**：只借"会话工作状态的最小接续面"（episodic 里记 `filesTouched`），不做任务面板 |
+| 读到即索引"值得借鉴" | **漏写** | **补为 C 级拒绝**：它是 RAG，不是记忆；与 loci 的产品边界冲突 |
+
+教训：口头列"值得借鉴"很容易把三个不同性质的层次（结构化字段 / 工作状态 / 检索架构）混成一类。
+**判据必须写在前面（本文 §0 的四条不变量），否则"值得"只是感觉。**
+
+## 4. 一条元教训（比上面任何功能都重要）
+
+看过的 8 个 DSH 记忆插件里，**只有 2 个把"未核实不进提示词"做成代码级不变量**（loci 与 auto-memory），其余的都靠 prompt 里的劝说或干脆没有这层。
+也就是说：这个品类里"功能更多"几乎总是意味着"闸门更松"。**我们不追功能数量，追的是"它出错时最坏能坏到什么程度"。**
+
+## 5. 未覆盖的部分（诚实边界）
+
+- 只用第一手材料评估了 7 个 DSH 插件（本地有 README/源码）+ 5 个成熟产品（文档级）。
+- DSH 目录里 memory 类约 473 条，其中 `meow-memory`(~36k 下载)、`dsh-plugin-memory`(~41k)、`dsh-memento`、`dsh-prime-memory`、`dsh-fish-memory` 只从二手报告里见过描述，**未读源码**。
+- 因此本表是"有依据的取舍"，不是"穷尽式技术扫描"。新插件出现后按同一张不变量表复评。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-loci",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Layered long-term memory for DeepSeek Harness: the prompt sees only a stable index, full text is one lookup away. Bi-temporal facts, strict scope isolation, verified-only injection.",
   "type": "module",
   "license": "MIT",

package/src/host/capture/capture.js

@@ -118,6 +118,9 @@ export class Capture {
     if (buffer === undefined) {
       buffer = {
         messages: [],
+      // Paths this session actually touched, most recent last. A tool call is the only
+      // honest source: it is what the model asked to do, not what it said it did.
+      files: [],
         bytes: 0,
         captures: 0,
         timer: undefined,
@@ -141,6 +144,35 @@ export class Capture {
     }
   }
 
+  /**
+   * Pull file paths out of one tool call.
+   *
+   * Deliberately narrow: only the argument names that actually carry paths, and only
+   * values that still look like a path after trimming. A false positive here would put
+   * a sentence into the resumption list, which is worse than missing a file.
+   *
+   * @param buffer - the session buffer.
+   * @param name - tool name (kept for the debug trail).
+   * @param rawArguments - the JSON argument string.
+   */
+  #noteFiles(buffer, name, rawArguments) {
+    const KEYS = /"(path|file|file_path|filePath|dir|directory|cwd|target|pattern|notebook_path)"\s*:\s*"([^"]{1,300})"/g;
+    let match;
+    let added = 0;
+    while ((match = KEYS.exec(rawArguments)) !== null && added < 8) {
+      const value = match[2].replace(/\\/g, '/').trim();
+      if (value.length < 2 || value.length > 300) continue;
+      // A glob is not a path someone can open; keep the directory part when it has one.
+      const cleaned = value.replace(/\*\*?.*$/, '').replace(/\/$/, '');
+      if (cleaned.length < 2) continue;
+      if (buffer.files.includes(cleaned)) continue;
+      buffer.files.push(cleaned);
+      added += 1;
+      if (buffer.files.length > 40) buffer.files.shift();
+    }
+    if (added > 0) this.log?.debug?.(`loci: ${name} touched ${added} path(s)`);
+  }
+
   /** Record one event; never throws into the session commit path. */
   onSessionEvent(session, event) {
     try {
@@ -164,6 +196,14 @@ export class Capture {
         this.#trim(buffer);
         return;
       }
+      if (event.type === 'tool/call') {
+        const name = String(event.data?.name ?? '');
+        const args = event.data?.arguments;
+        if (typeof args === 'string' && Buffer.byteLength(args, 'utf8') <= 8192) {
+          this.#noteFiles(buffer, name, args);
+        }
+        return;
+      }
       if (event.type === 'turn/end') {
         buffer.turn = Number(event.data?.turn ?? buffer.turn);
         if (event.data?.reason?.kind === 'completed') {
@@ -382,7 +422,11 @@ export class Capture {
         scopeKey: this.#workspaceKey(buffer.cwd, sessionId),
         scopeLabel: this.#workspaceLabel(buffer.cwd),
         title,
-        body,
+        body: buffer.files.length > 0
+          // The episodic entry is history: it is never injected, so this list costs the
+          // prompt nothing and only helps `loci_search` answer "where were we".
+          ? `${body}\n\nFiles touched this session:\n${buffer.files.slice(-20).map((file) => `- ${file}`).join('\n')}`
+          : body,
         trustSource: 'summary',
         sourceSession: sessionId,
         sourceEvent: buffer.messages.at(-1)?.seq,

package/src/host/index.js

@@ -23,7 +23,7 @@ import { registerCommands } from './commands.js';
 import { runDoctor } from './doctor.js';
 
 /** Version stamped into the database and diagnostics. */
-export const VERSION = '2.3.1';
+export const VERSION = '2.4.0';
 
 /** Optional collaborators; without them the plugin still serves tools. */
 export const inject = ['systemPrompt', 'tools'];

package/src/host/inject/index-section.js

@@ -108,7 +108,16 @@ export function renderIndexBody(options) {
   // candidates used to render an empty "Index —" heading, which reads as "memory is
   // empty" right next to the line saying something is waiting.
   const indexHeader = visible.length > 0 ? `Index — ${renderSafe(indexTitle(scopeLabel, 120))}` : '';
-  const entryLine = (entry) => `- ${entry.id} · ${entry.kind} · ${formatDate(entry.validFrom)} · ${renderSafe(indexTitle(entry.title, lineChars))}`;
+  // A lesson's one-line summary carries what it prevents, because that is the part a
+  // reader needs to act on it: the rule without the consequence gets ignored. Only for
+  // `procedural` entries that actually have the field, so ordinary facts are byte-identical
+  // to before.
+  const PREVENTS_CHARS = 60;
+  const entryLine = (entry) => {
+    const head = `- ${entry.id} · ${entry.kind} · ${formatDate(entry.validFrom)} · ${renderSafe(indexTitle(entry.title, lineChars))}`;
+    if (entry.kind !== 'procedural' || typeof entry.prevents !== 'string' || entry.prevents.length === 0) return head;
+    return `${head} — prevents: ${renderSafe(indexTitle(entry.prevents, PREVENTS_CHARS))}`;
+  };
 
   const footerFor = (listed) => {
     const hidden = Math.max(0, total - listed);

package/src/host/store/migrate.js

@@ -12,7 +12,7 @@
 import { copyFileSync, existsSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { backupTo, tableCounts, withTransaction } from './db.js';
-import { MEMORY_USAGE_DDL } from './schema.js';
+import { MEMORY_LESSON_DDL, MEMORY_USAGE_DDL } from './schema.js';
 import {
   META_KEYS,
   SCHEMA_VERSION,
@@ -40,6 +40,15 @@ export const SHIPPED_MIGRATIONS = [
       db.exec(MEMORY_USAGE_DDL);
     },
   },
+  {
+    from: 2,
+    to: 3,
+    // Four nullable columns: no row can be lost, and every existing entry simply has
+    // no lesson shape yet.
+    up(db) {
+      db.exec(MEMORY_LESSON_DDL);
+    },
+  },
 ];
 
 /**

package/src/host/store/schema.js

@@ -8,7 +8,7 @@
  */
 
 /** Schema version this build writes and expects. */
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 /**
  * DDL for the v2 per-entry usage table.
@@ -18,6 +18,21 @@ export const SCHEMA_VERSION = 2;
  * that only exists on new installs is the classic way a feature "works on my
  * machine".
  */
+/**
+ * DDL for the v3 lesson fields.
+ *
+ * A lesson stored as free text is unreadable six months later: you remember the rule
+ * but not why it exists. `prevents` is the field that answer lives in, `pattern` and
+ * `fix` split the problem from the remedy, and `when_condition` records the situation
+ * the lesson was written for — stored, shown, never used to decide injection.
+ */
+export const MEMORY_LESSON_DDL = `
+ALTER TABLE memory ADD COLUMN pattern TEXT;
+ALTER TABLE memory ADD COLUMN fix TEXT;
+ALTER TABLE memory ADD COLUMN prevents TEXT;
+ALTER TABLE memory ADD COLUMN when_condition TEXT;
+`;
+
 export const MEMORY_USAGE_DDL = `
 CREATE TABLE IF NOT EXISTS memory_usage (
   id               TEXT PRIMARY KEY,
@@ -67,6 +82,11 @@ CREATE TABLE IF NOT EXISTS memory (
   tier           INTEGER NOT NULL DEFAULT 2,
   importance     INTEGER NOT NULL DEFAULT 3,
   content_hash   TEXT NOT NULL,
+  -- v3: a lesson's shape. All nullable; ordinary facts leave them empty.
+  pattern        TEXT,
+  fix            TEXT,
+  prevents       TEXT,
+  when_condition TEXT,
   created_at     INTEGER NOT NULL,
   updated_at     INTEGER NOT NULL,
   deleted_at     INTEGER,

package/src/host/store/store.js

@@ -22,7 +22,17 @@ import { migrate } from './migrate.js';
 import { EmbeddingChannel, vectorToBlob } from './embedding.js';
 import { META_KEYS, SCHEMA_VERSION, databaseVersion, readMeta, writeMeta } from './schema.js';
 import { normalizeText, tokenStream, tokenize, buildQueryPlan } from './tokenize.js';
-import { normalizeTitle, prepareForStorage } from '../inject/sanitize.js';
+import { cleanText, normalizeTitle, prepareForStorage } from '../inject/sanitize.js';
+
+/**
+ * Relations a caller may declare between two facts.
+ *
+ * `supersedes` is written by the store itself (a revision replaces its predecessor).
+ * The other two exist because real corrections are partial: `conflicts` says "these
+ * disagree and a person must decide", `extends` says "this adds to that and both
+ * hold". Neither changes what is injected — an entry still needs its own verification.
+ */
+export const RELATIONS = Object.freeze(new Set(['conflicts', 'extends']));
 
 /** Ids that were revoked or never existed. */
 export class MemoryNotFoundError extends Error {
@@ -76,6 +86,11 @@ function mapRow(row) {
     supersedes: row.supersedes ?? null,
     supersededBy: row.superseded_by ?? null,
     evidence: JSON.parse(row.evidence ?? '{}'),
+    /** The lesson shape, when this entry is one. Null for ordinary facts. */
+    pattern: row.pattern ?? null,
+    fix: row.fix ?? null,
+    prevents: row.prevents ?? null,
+    whenCondition: row.when_condition ?? null,
     /** Citation back to the code or document the fact came from. */
     sourceRef: JSON.parse(row.evidence ?? '{}').ref ?? null,
     sourceSession: row.source_session ?? null,
@@ -211,6 +226,7 @@ export class Store {
     const evidence = prepared.evidence ?? {};
     const status = this.#resolveStatus({ input, prepared, evidence, trustSource });
 
+    const lesson = this.#lessonFields(input);
     const contentHash = createHash('sha256')
       .update(`${normalizeTitle(prepared.title)}\n${normalizeText(prepared.body)}`, 'utf8')
       .digest('hex');
@@ -299,7 +315,9 @@ export class Store {
         now,
         verifiedBy: status === 'verified' ? (input.verifiedBy ?? trustSource) : null,
         verifiedAt: status === 'verified' ? now : null,
+        ...lesson,
       });
+      this.#linkRelations(id, 1, input.relations, now);
       this.bumpIndexRev();
       return inserted;
     });
@@ -344,6 +362,7 @@ export class Store {
       throw new RevisionConflictError(id, input.expectedRevision, Number(head.row.revision));
     }
     const prepared = input.preparedOverride ?? prepareForStorage(input, { secretPolicy: this.live('secretPolicy') });
+    const lesson = this.#lessonFields(input);
     if (prepared.rejected) {
       throw new MemoryRejectedError(`memory contains a high-confidence secret (${prepared.redactions.join(', ')})`);
     }
@@ -394,6 +413,12 @@ export class Store {
         pinned: input.pinned === true ? 1 : Number(head.row.pinned),
         importance: Number.isInteger(input.importance) ? input.importance : Number(head.row.importance),
         contentHash,
+        // A revision that does not restate the lesson keeps the previous shape: fixing a
+        // typo in the title must not silently erase why the lesson exists.
+        pattern: lesson.pattern ?? head.row.pattern ?? null,
+        fix: lesson.fix ?? head.row.fix ?? null,
+        prevents: lesson.prevents ?? head.row.prevents ?? null,
+        whenCondition: lesson.whenCondition ?? head.row.when_condition ?? null,
         createdAt: Number(head.row.created_at),
         now,
         verifiedBy: status === 'verified' ? (input.verifiedBy ?? 'tool') : null,
@@ -405,6 +430,11 @@ export class Store {
            VALUES (?, ?, ?, ?, 'supersedes', ?)`,
         )
         .run(id, revision, id, Number(head.row.revision), now);
+      // A revision is not always a full replacement. "The rollback window is 45 minutes
+      // now, but database changes still get 30" contradicts the old entry on one clause
+      // and agrees on another; superseding it would destroy the part that is still true.
+      // Callers can therefore declare a weaker relation and both facts stay readable.
+      this.#linkRelations(id, revision, input.relations, now);
       this.bumpIndexRev();
       return inserted;
     });
@@ -789,7 +819,8 @@ export class Store {
     const placeholders = keys.map(() => '?').join(', ');
     const rows = this.db
       .prepare(
-        `SELECT m.id, m.revision, m.kind, m.scope, m.title, m.valid_from, m.updated_at, m.pinned, m.created_at, m.tier
+        `SELECT m.id, m.revision, m.kind, m.scope, m.title, m.valid_from, m.updated_at, m.pinned, m.created_at, m.tier,
+                m.prevents
          FROM memory m
          WHERE m.status = 'verified'
            AND m.deleted_at IS NULL
@@ -808,6 +839,8 @@ export class Store {
       validFrom: Number(row.valid_from),
       updatedAt: Number(row.updated_at),
       pinned: Number(row.pinned) === 1,
+      // The index needs one clause of context for a lesson; everything else stays out.
+      prevents: row.prevents ?? null,
     }));
   }
 
@@ -1525,6 +1558,59 @@ export class Store {
     return verified;
   }
 
+  /**
+   * Sanitize the optional lesson shape.
+   *
+   * These are free text from a model, so they get the same treatment as a title: control
+   * characters and bidi overrides stripped, length capped. Empty input stays null rather
+   * than an empty string, so "no lesson shape" is one value and not two.
+   *
+   * @param input - caller input.
+   * @returns the four fields, all nullable.
+   */
+  #lessonFields(input) {
+    const clean = (value, maxChars) => {
+      const text = cleanText(typeof value === 'string' ? value : '', maxChars);
+      return text.length === 0 ? null : text;
+    };
+    return {
+      pattern: clean(input?.pattern, 400),
+      fix: clean(input?.fix, 800),
+      prevents: clean(input?.prevents, 300),
+      whenCondition: clean(input?.whenCondition, 300),
+    };
+  }
+
+  /**
+   * Record the relations a caller declared for one revision.
+   *
+   * Silently skips anything unusable — an unknown relation name, a self reference, a
+   * target that does not exist or was deleted. A bad link must never fail the write:
+   * the fact itself is still worth keeping, and a missing edge is recoverable while a
+   * lost fact is not.
+   *
+   * @param id - this entry.
+   * @param revision - the revision the relation was declared on.
+   * @param relations - caller-supplied `[{id, relation}]`.
+   * @param now - timestamp.
+   */
+  #linkRelations(id, revision, relations, now) {
+    if (!Array.isArray(relations) || relations.length === 0) return;
+    const link = this.db.prepare(
+      `INSERT OR IGNORE INTO memory_edge (src_id, src_rev, dst_id, dst_rev, relation, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    );
+    for (const relation of relations) {
+      if (relation === null || typeof relation !== 'object') continue;
+      const target = typeof relation.id === 'string' ? relation.id : '';
+      const kind = relation.relation;
+      if (target.length === 0 || !RELATIONS.has(kind) || target === id) continue;
+      const other = this.#headRow(target);
+      if (other === undefined || other.status === 'deleted') continue;
+      link.run(id, revision, target, Number(other.row.revision), kind, now);
+    }
+  }
+
   #insertRevision(row) {
     const result = this.db
       .prepare(
@@ -1532,8 +1618,9 @@ export class Store {
            id, revision, kind, scope, scope_key, scope_label, title, title_norm, body, tags, entities,
            status, trust_source, flags, valid_from, valid_to, recorded_at, supersedes, superseded_by,
            evidence, source_session, source_event, verified_at, verified_by, pinned, importance, tier,
-           content_hash, created_at, updated_at, deleted_at
-         ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,NULL)`,
+           content_hash, created_at, updated_at, deleted_at,
+           pattern, fix, prevents, when_condition
+         ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,NULL,?,?,?,?)`,
       )
       .run(
         row.id,
@@ -1566,6 +1653,12 @@ export class Store {
         row.contentHash,
         row.createdAt,
         row.now,
+        // The four lesson columns sit after `deleted_at` in the column list, which is
+        // bound as a literal NULL, so they come last in this argument list.
+        row.pattern ?? null,
+        row.fix ?? null,
+        row.prevents ?? null,
+        row.whenCondition ?? null,
       );
     const ord = Number(result.lastInsertRowid);
     const text = `${row.title} ${row.body} ${(row.tags ?? []).join(' ')}`;

package/src/host/tools/tools.js

@@ -131,6 +131,38 @@ export function createTools(deps) {
           type: 'string',
           description: 'Where this fact lives in the repository, e.g. "src/host/store.js:120". Shown by loci_get so a reader can check it.',
         },
+        pattern: {
+          type: 'string',
+          description: 'For kind "procedural": the reusable shape of the problem, e.g. "a script edits a file and the quoting silently mangles it".',
+        },
+        fix: {
+          type: 'string',
+          description: 'For kind "procedural": what actually worked, concretely enough to repeat.',
+        },
+        prevents: {
+          type: 'string',
+          description:
+            'For kind "procedural": what breaks without this lesson. Shown on the index line, because a rule without its consequence gets ignored.',
+        },
+        whenCondition: {
+          type: 'string',
+          description:
+            'For kind "procedural": the situation this lesson was written for. Stored and shown, never used to decide whether the entry is injected.',
+        },
+        relations: {
+          type: 'array',
+          description:
+            'Other entries this one touches. "conflicts" records that they disagree and a person must decide; "extends" records that this adds to that and both still hold. Neither replaces the other entry the way an update does.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              relation: { type: 'string', enum: ['conflicts', 'extends'] },
+            },
+            required: ['id', 'relation'],
+            additionalProperties: false,
+          },
+        },
         evidenceNote: { type: 'string' },
         validFrom: { type: 'string', description: 'ISO time the fact became true (default: now).' },
         ttlDays: { type: 'integer', description: 'Close the fact after N days (default: no expiry).' },
@@ -205,6 +237,11 @@ export function createTools(deps) {
         sourceSession: context.sessionId ?? null,
         sourceEvent: Number.isSafeInteger(lastUserSeq) ? lastUserSeq : undefined,
         sourceRef: str(args, 'sourceRef', { fallback: undefined }),
+        relations: Array.isArray(args?.relations) ? args.relations : undefined,
+        pattern: str(args, 'pattern', { fallback: undefined }),
+        fix: str(args, 'fix', { fallback: undefined }),
+        prevents: str(args, 'prevents', { fallback: undefined }),
+        whenCondition: str(args, 'whenCondition', { fallback: undefined }),
         evidence: {
           ...(evidenceQuote === undefined ? {} : { quote: evidenceQuote }),
           ...(str(args, 'evidenceNote', { fallback: undefined }) === undefined
@@ -514,10 +551,33 @@ function renderGet(value) {
     lines.push(`source: ${renderSafe(entry.sourceRef)}`);
   }
   lines.push('', renderSafe(entry.body));
+  // A lesson reads as four labelled lines rather than one paragraph: the problem, the
+  // remedy, the consequence, and the situation it was written for.
+  for (const [label, value] of [
+    ['pattern', entry.pattern],
+    ['fix', entry.fix],
+    ['prevents', entry.prevents],
+    ['when', entry.whenCondition],
+  ]) {
+    if (typeof value === 'string' && value.length > 0) lines.push(`${label}: ${renderSafe(value)}`);
+  }
   const quote = entry.evidence?.quote;
   if (typeof quote === 'string' && quote.length > 0) {
     lines.push('', `evidence: “${renderSafe(quote)}”${entry.sourceSession ? ` (session ${entry.sourceSession})` : ''}`);
   }
+  // Declared relations are the only place a partial correction is visible: the entry
+  // itself reads as one fact, and "this disagrees with m_yyy on one clause" lives here.
+  const relations = (Array.isArray(value.edges) ? value.edges : []).filter(
+    (edge) => edge.relation === 'conflicts' || edge.relation === 'extends',
+  );
+  if (relations.length > 0) {
+    lines.push('', 'relations:');
+    for (const edge of relations) {
+      const other = edge.src_id === entry.id ? edge.dst_id : edge.src_id;
+      const direction = edge.src_id === entry.id ? '→' : '←';
+      lines.push(`- ${edge.relation} ${direction} ${other}`);
+    }
+  }
   const history = Array.isArray(value.history) ? value.history : [];
   if (history.length > 1) {
     lines.push('', `history: ${history.length} revisions`);

package/src/mcp/store-facade.js

@@ -36,7 +36,7 @@ export function openFacadeStore(options = {}) {
     memoryRoot: root,
     paths,
     config,
-    pluginVersion: '2.3.1',
+    pluginVersion: '2.4.0',
     readOnly: options.readOnly === true,
   });
   return { store, paths };