dsh-engram 0.3.3 → 0.3.5

package/docs/PROPOSAL-hindsight.zh.md

@@ -0,0 +1,156 @@
+# dsh-engram 改进方案 · 借自 Hindsight（三个概念，不引重路线）
+
+> 依据：[vectorize-io/hindsight](https://github.com/vectorize-io/hindsight) 深度研究（2026 春季快照）。
+> 原则：三条全部**纯规则 / 无向量 / 无 LLM 蒸馏 / 确定性可单测**，符合既有约束
+> （不引重路线、中文、host 改动等自然重启、dock 极简）。
+> 真实基线：Kototoro memories 71（扁平）/ tasks 1 / links 4 / nodes 3；toolstats 近 14 天
+> todo 48 · ESR ~6 · esr_node/esr_link 接近零。
+
+---
+
+## 总览
+
+| # | 概念（来源） | 解决什么 | 落点 | 成本 | 依赖 |
+|---|---|---|---|---|---|
+| A | **Observation 范式**：证据引用 + proof_count + refine-not-overwrite（consolidator.py） | 71 条扁平记忆无从浓缩；失败/成功经验被覆盖不保留证据链 | `lib/store.js` 写入侧 + `lib/obs.js` 新模块 + board 观测区 | host ~250 行 | 无 |
+| B | **Mental model 预计算**：常驻答案读零计算 + 水印刷新（mental_models + last_memory_seen_at） | 每次会话现查照样费 tokens；dock/board 每次重算 | `lib/mental.js` + 新工具 `esr_model` + board 常驻条 | host ~200 行 | 依赖 A 提供的 observation 汇总 |
+| C | **召回重排信号**：proof_count boost × recency 半衰期（reranking.py） | 现行排序只有 recency+精确匹配；失败复活性差 | `lib/rerank.js` 纯函数 + bm25Rank 接入 | host ~80 行 | 无 |
+
+状态：C ✅（7093fb5）/ A ✅（7103a22）/ B ✅。建议实施顺序：**C → A → B**。
+B 落地要点：`models` 表注册（ws/content/generated_at/dirty/sources_hash）；
+`lib/mental.js` 纯函数 compileSummary（任务/实体/观测/记忆种类聚合 → markdown）、
+computeSourcesHash、modelStale（dirty ∨ 超 10min ∨ 输入 hash 变）、getModel（冷缓存重算并持久化）；
+esr_* 六个写工具成功路径统一 `markModelDirty`；agent 工具 `esr_model`（返回常驻摘要+生成分钟数）
+与 `/model` 端点；board 顶部可折叠「常驻摘要 · 生成于 N 分钟前」。新测试 6 个（宿主 67/67）。
+C/A/B 的 host 部分（rerank、/observations、/model、esr_model、dirty 钩子）随下次 `dsh web` 重启生效；
+board 观测条/常驻条 client-hmr 即时生效。
+A 落地要点（相对本稿）：`observations` 表注册进 `engramDomainSpec`；
+`storeMemory` 三路（新建/exact-dup/失败复活）均触发 `integrateObservation`，其中
+**失败复活（revive）是「新发生」→ forceEvidence 爬 proof**，exact-dup（同源）只刷
+span；`engram_recall` 尾部注入 proof≥2 的观测段；board 加可折叠「观测 · 信念 N」条；
+`/observations` 端点与 /toolstats 同批等重启；新测试 12 个（宿主 61/61）。
+
+---
+
+## A. Observation：证据浓缩 + 证据计数 + 增强而非覆盖
+
+### 问题
+- 记忆是扁平列表；同一主题的多次失败/多次成功没有聚合，`esr_recall` 返回的是散点。
+- D1/D3 的「失败记忆复活」只恢复了单条，没有形成「这个模式被证明 N 次」的信念。
+
+### 数据模型（新增 `tables.observations`，存 storages/dsh_engram.json）
+```jsonc
+{
+  "id": "obs_<8>",
+  "ws": "/ws/A",                 // "" = 全局
+  "text": "浓缩后的信念语句（初始 = 触发记忆文本）",
+  "kind": "belief",              // belief | pattern | risk（由触发记忆 tags 推导，不引 LLM）
+  "proof": { "count": 3, "sources": ["mem_<8>", ...] },
+  "span": { "first_seen_at": 1, "last_seen_at": 2 },
+  "negations": 0,                // 反证计数 → 触发 weaken/stale
+  "trend": "stable",             // new|strengthening|stable|weakening|stale（算法计算）
+  "tags": ["fail"],
+  "updated_at": 3
+}
+```
+
+### 算法（`lib/obs.js`，全部纯函数 + 一个写入钩子）
+1. **`concentrate(ws, memText, memId, tags)`** —— host 写入记忆（esr_store_memory / 失败复活 / engram 自动捕获）后调用：
+   - 桶化：按 `(entity 锚点 或 tags) + 字符 n-gram Jaccard ≥ 阈值(0.45)` 找既有 observation（中文无需向量）。
+   - 命中 → **merge 而非覆盖**：`proof.count+1`、`sources.push(memId)`、`span.last_seen_at = now`、`updated_at=now`；`text` 仅在新增细节时 append（简单规则：新文本含旧文本不存在的 token 段则并句）。
+   - 命中且可判定为**反证**（tags 含 `error`+当前 text 与旧 text 出现否定词对）→ `negations+1`，`proof.count` 不变。
+   - 未命中 → 新建 observation（`proof.count=1`）。
+2. **`computeTrend(span, now, recentDays=30, oldDays=90)`** —— 借鉴 observations.py 的 `Trend`：
+   - last_seen 在 30 天内且 first_seen 更早 → `strengthening`
+   - 全部证据在 30 天内 → `new`
+   - 90 天内有证据 → `stable`
+   - 90 天内无新证据但有历史 → `weakening`；无证据 → 不存在的桶自清（GC 归入 esr_gc）。
+3. **读取注入**：`esr_recall` 把 `proof.count ≥ 2` 的 observations 作为高权重候选混入返回（标记 `source: observation`），证据门语义不变。
+
+### Web 展示
+- 只进 **board**（dock 保持极简）：columns 上方一行可折叠「观测 · N 条信念」条，展示 `text · ✓×count · 趋势图标`，展开可看 sources 列表。
+- KPI 行（toolstats 那行）旁加 `观测 N`。
+
+### 测试
+`test/obs.test.mjs`（node:test 直接 import）：
+- 首次写入建桶 / 二次相同语义 merge（count 2 且 sources 追加）/ 反证 negations+1 /
+  trend 四种时间窗 / 阈值下不误并 / Jaccard 中文样例。
+
+---
+
+## B. Mental model：常驻摘要 + 水印刷新
+
+### 问题
+- agent 每轮现查「这个工作区现在什么状态」要花多次 recall；看板每次挂载重算 overview + tasks + links。
+- 产出一个可被反复读取、只在数据变化时才重算的「常驻答案」→ 读零计算。
+
+### 数据模型（新增 `tables.models`）
+```jsonc
+{
+  "ws": "/ws/A",
+  "content": "## /ws/A 常驻摘要\n- 任务：2 active（1 就绪）/ 1 stable\n- 实体 3 · 链接 4\n- 观测 6 条信念（2 失败模式已重复 3 次）\n- 近 14 天：todo 48 · ESR 6\n- 生成于 N 分钟前",
+  "generated_at": 1,
+  "dirty": true,           // 任何 esr_* 写操作后置 true
+  "sources_hash": "sha256 摘要（惰性校验可跳过重算）"
+}
+```
+
+### 算法（`lib/mental.js`）
+- **`bumpDirty(ws)`** —— host 工具写钩子（esr_task/esr_close/esr_node/esr_link/esr_store_memory/todo 沉淀）之后调用。
+- **`getModel(ws)`** —— 读缓存；`dirty` 或过期（>10min）则**纯聚合重算**（无 LLM）：复用 `domain` API 的 tasks/entities/links 计数 + `collectToolCounts` 的近况 + `tables.observations` 的 top 信念 → 拼 markdown；重算后 `dirty=false`。
+- **暴露**：
+  - agent 工具 `esr_model(ws?)` —— 返回常驻摘要 markdown（**零 LLM、一次 DB 读**）放在工具说明顶部「先看 model 再 recall」；response 带 `modeling:` 行同款风格。
+  - web endpoint `/model?ws=`（route 注册随下次重启，与 /toolstats 同批）。
+
+### Web 展示
+- board 顶部「常驻摘要 · 生成于 N 分钟前」可折叠条（可复制、可下载为 md——复用自己的 buildTasksMarkdown 思路，纯 client 无依赖）。
+
+### 测试
+`test/mental.test.mjs`：dirty→重算 / 未 dirty→命中缓存（generated_at 不变）/ 写操作触发 bump（route 注入假 service）/ 空工作区占位内容。
+
+---
+
+## C. 召回重排：proof_count × recency 半衰期
+
+### 问题与现状核实
+- 现行 `util.js bm25Rank` **已含** recency 半衰期因子 `1 + 0.5·exp(-ageDays/14)`（14 天、最多 +50%，
+  不覆盖强词法相关），也有 tag-exact/fuzzy/phrase/BM25 权重——真正缺失的是**证据强度信号**：
+  同样词频的记忆，被证明过 N 次的（hits）没有被排序优待。
+- D2 失败复活已在 error 记忆重复时递增 `hits`；它就是现成的 proof 计数。
+
+### 实现（已落地：`lib/rerank.js` + `util.js bm25Rank` 接线）
+```
+score_final = score_lexical                     // BM25 + tag/phrase boost（既有）
+            × (1 + 0.5·exp(-ageDays/14))        // recency 半衰期（既有）
+            × evidenceBoost(hits)               // 新增：1 + 0.1·min(max(0,hits), 5)，饱和 ±5%
+```
+- `evidenceBoost(hits, {alpha=0.1, cap=5})`：0→1.0、5→1.5（封顶），保守不喧宾夺主（借鉴 reranking.py 的 proof alpha）。
+- `scoreCandidate(matchScore, hits)`、`sortByEvidence(list, opts)`（稳定、可注入 tiebreak）。
+- 接入点：`bm25Rank` 词法分后乘 `evidenceBoost(r.hits ?? 0)`——encerence recall/searchMemories 全走这里，零额外改动。
+- 「失败复活」天然增强：高 hits 的失败记忆在同词频下与新鲜记忆竞争更接近。
+
+### 测试
+`test/rerank.test.mjs`：三种 matchKind 基准 / 半衰期形状（t=0, halflife, 2*halflife 分别为 1, 0.5, 0.25）/ proof cap / 稳定排序（同分保序）/ 未来时间戳钳制。
+
+---
+
+## 分阶段计划（每阶段：代码 + 测试 + client-hmr 即时 / host 待重启 + 中文总结）
+
+| 阶段 | 内容 | 交付物 | 生效 |
+|---|---|---|---|
+| C | rerank 纯函数 + 接入 esr_recall | `lib/rerank.js` + `test/rerank.test.mjs` | 等自然重启 |
+| A | observations 表 + concentrate/trend + recall 注入 + board 观测条 | `lib/obs.js` + `lib/store.js` 钩子 + `test/obs.test.mjs` + board | host 待重启；board 即时 |
+| B | mental 缓存 + esr_model 工具 + /model 端点 + board 常驻条 | `lib/mental.js` + `test/mental.test.mjs` + board | host 待重启；board 即时 |
+
+每阶段与既有实现正交：不动 dock 交互（除可选 KPI 一列）、不动证据门、不动 esr_close 语义。
+
+## 明确不做（保留约束）
+- 不做 LLM 抽取/浓缩（Hindsight retain 管线）——成本与我们的形态不匹配。
+- 不做向量/图库/交叉编码器重排。
+- 不做 mental model 的「用户定义问题」自由文本——用固定模板，纯聚合。
+- observations 的「来源逐 quote 引用」简化为 sources 列表（证据门已足够）。
+
+## 风险
+- 浓缩误并（Jaccard 阈值误命中）→ 反证机制 + GC 可兜；阈值可配。
+- observation 桶增长失控 → 每 ws 上限（默认 50 条），超出按 proof 降序逐出（保留计数进 audit），归入 esr_gc。
+- mental 缓存脏标记漏置 → `bumpDirty` 挂全量写钩子 + 过期兜底（10min 强制重算）。

package/lib/api.js

@@ -157,6 +157,7 @@ export function makeEngramRoutes(service) {
       indexes,
       captures: service.captureStats ?? { total: 0, git: 0, file: 0, error: 0 },
       gc: service.gcStats ?? { lastRun: 0, archivedMemories: 0, archivedTasks: 0, removedLinks: 0 },
+      compaction: service.compactionStatus ?? { host: "unknown", web: { action: "unknown", presets: [] } },
       config: service.config ?? {},
       anonymous: {
         version: 2,
@@ -180,6 +181,23 @@ export function makeEngramRoutes(service) {
     writeJson(res, 200, { items });
   };
 
+  // Goal-domain sediment: memories auto-captured from `goal/change` events
+  // (tag "goal"). A compact read surface for the GUI, backed by the same
+  // searchMemory view as /memories.
+  const goals = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const params = readQuery(req);
+    const limit = Number(params.get("limit") ?? 50);
+    const items = domain.searchMemories({
+      workspace: params.get("workspace") || void 0,
+      tag: "goal",
+      status: "active",
+      limit,
+    }).map((m) => ({ id: m.id, kind: m.kind, text: m.text, createdAt: m.createdAt, workspace: m.workspace }));
+    writeJson(res, 200, { items });
+  };
+
   const tasks = async (req, res) => {
     const domain = await withDomain(res);
     if (domain === void 0) return;
@@ -503,6 +521,7 @@ export function makeEngramRoutes(service) {
   return [
     make("GET", "/overview", overview),
     make("GET", "/memories", memories),
+    make("GET", "/goals", goals),
     makeUnion("/tasks", { GET: tasks, POST: createTask }),
     make("GET", "/links", links),
     make("GET", "/nodes", entities),

package/lib/capture.js

@@ -11,6 +11,8 @@
  *     branch / tag / cherry-pick). Pure plumbing (`push`, `stash`, `status`)
  *     is deliberately NOT captured: those are operational echoes, not lasting
  *     decisions, and would only drown the memory pool and the [ENGRAM] index.
+ *   - failing test runs (`npm test` / `node --test` / vitest / jest / pytest)
+ *     as high-signal error memories tagged `test`.
  *   - writes/edits to significant config & doc paths
  *   - repeated tool errors (error signal, deduped by message)
  * symbolic-index's own insight: one file edit is noise; accumulated edits and rare
@@ -22,6 +24,56 @@ import { workspaceKey as workspaceKeyOf } from "./util.js";
 
 const GIT_MILESTONE_SIGNAL = 0.5;
 const GIT_COMMIT_SIGNAL = 0.55;
+const TEST_FAILURE_SIGNAL = 0.35;
+const FIX_CLOSURE_SIGNAL = 0.45;
+
+/** Concrete text: a test-run command (npm/pnpm/yarn/bun/npx/node --test/…). */
+const TEST_RUN_RE = /\b(npm|pnpm|yarn|bun|npx|corepack)\s+(?:run\s+)?test\b|\bnode\s+--test\b|\bvitest\b|\bpytest\b|\bjest\b/;
+/** A result line that reads as a failure point (deterministic keyword scan). */
+const FAILURE_LINE_RE = /(assertionerror|#\s*fail(?:ed)?|not\s+ok|✗|✖|✘|\bFAIL(?:ED)?\b|tests?\s+failed|failed\s+tests?\b|\d+\s+failed|non-zero exit|exception|traceback|error:\s)/i;
+
+/**
+ * Normalize a command to a stable short signature tag (first two tokens,
+ * spaces → underscores, ≤48 chars) used to pair a failure with its later
+ * successful run. Returns null for empty commands.
+ */
+export function cmdTag(command) {
+  const tokens = String(command ?? "").trim().split(/\s+/).filter(Boolean).slice(0, 2);
+  if (tokens.length === 0) return null;
+  return `cmd:${tokens.join("_").slice(0, 48)}`;
+}
+
+/**
+ * Failure→fix closure (zero LLM): when a command that previously failed (an
+ * ACTIVE kind:error memory tagged with the same `cmd:` signature) now runs
+ * successfully, produce a `procedure` memory plus the ids of the resolved
+ * error rows. Deterministic; fires only on genuine same-command
+ * success-after-failure.
+ */
+export function fixClosureEntry(name, command, result, previousErrors) {
+  if (!["bash", "shell", "exec"].includes(name)) return null;
+  if (result?.isError === true) return null; // not a success
+  if (typeof command !== "string" || command.trim().length === 0) return null;
+  const tag = cmdTag(command);
+  if (tag === null) return null;
+  const failing = (previousErrors ?? []).filter(
+    (m) => m.kind === "error" && m.status === "active" && (m.tags ?? []).includes(tag),
+  );
+  if (failing.length === 0) return null;
+  const head = command.trim().split(/\s+/).slice(0, 2).join(" ");
+  const isTest = TEST_RUN_RE.test(command);
+  const plural = failing.length > 1 ? "s" : "";
+  return {
+    entry: {
+      kind: "procedure",
+      text: `fixed: ${head} — ${failing.length} earlier failing run${plural} now succeed`,
+      signal: FIX_CLOSURE_SIGNAL,
+      tags: ["procedure", "auto-captured", "fix", tag, ...(isTest ? ["test"] : [])],
+      filePath: null,
+    },
+    resolvedIds: failing.map((m) => m.id),
+  };
+}
 
 /** Git operations that carry lasting meaning (milestones). */
 const GIT_OPS = [
@@ -109,9 +161,30 @@ export function makeCaptureHandler(store, config, log, stats) {
         // Errors take precedence over tool-name classification: a failed edit
         // tool is a FAILURE of that file, not an "Edited" event (filePath anchor).
         const errPath = String(args.path ?? args.file_path ?? args.filePath ?? "");
-        const msg = errorHead(result);
-        if (msg !== null) {
-          entry = { kind: "error", text: `${name} failed: ${msg}`, signal: 0.25, tags: ["error", "auto-captured"], filePath: errPath || null };
+        const cmd = cmdTag(args.command); // pairs this failure with a later success
+        // A failing test run is the highest-value coding signal: name it
+        // explicitly and surface the concrete failure point.
+        const testFail = extractTestFailure(name, args.command, result);
+        if (testFail !== null) {
+          entry = { kind: "error", text: testFail, signal: TEST_FAILURE_SIGNAL, tags: ["error", "test", "auto-captured", cmd].filter(Boolean), filePath: null };
+        } else {
+          const msg = errorHead(result);
+          if (msg !== null) {
+            entry = { kind: "error", text: `${name} failed: ${msg}`, signal: 0.25, tags: ["error", "auto-captured", cmd].filter(Boolean), filePath: errPath || null };
+          }
+        }
+      } else if (isCommandRun(name) && typeof args.command === "string" && store.listMemories !== void 0) {
+        // Failure→fix closure: the same command that once failed now succeeds —
+        // sediment a `procedure` and resolve the earlier error rows.
+        const fix = fixClosureEntry(
+          name,
+          args.command,
+          result,
+          store.listMemories(workspaceKeyOf(cwd), 200),
+        );
+        if (fix !== null) {
+          entry = fix.entry;
+          entry._resolvedIds = fix.resolvedIds;
         }
       } else if (EDIT_TOOLS.has(name)) {
         const path = String(args.path ?? args.file_path ?? args.filePath ?? "");
@@ -142,6 +215,7 @@ export function makeCaptureHandler(store, config, log, stats) {
         recent.delete(first);
       }
 
+      const resolvedIds = entry._resolvedIds ?? [];
       void store
         .storeMemory(
           {
@@ -156,7 +230,13 @@ export function makeCaptureHandler(store, config, log, stats) {
           },
           config,
         )
-        .then(() => {})
+        .then(() => {
+          // Failure→fix closure: mark the earlier error rows resolved (tag
+          // append only — never re-ranks them, per store.tagMemory's contract).
+          for (const id of resolvedIds) {
+            void store.tagMemory?.(workspaceKeyOf(cwd), id, "resolved")?.catch?.(() => null);
+          }
+        })
         .catch((error) => log?.warn?.(`engram auto-capture failed: ${String(error)}`));
     } catch (error) {
       // fully contained — a capture bug must never disturb the tool pipeline
@@ -187,6 +267,11 @@ function extractGit(name, command) {
   return null;
 }
 
+/** Shell-run tool names whose failures/successes carry a command signature. */
+function isCommandRun(name) {
+  return name === "bash" || name === "shell" || name === "exec";
+}
+
 function errorHead(result) {
   // canonical value or rendered content
   const value = result?.value;
@@ -206,6 +291,49 @@ function errorHead(result) {
   return null;
 }
 
+/**
+ * When a bash/shell run of a test command exits non-zero, produce a
+ * deterministic failure memory: `tests failed (<cmd>): <failure line>`.
+ * Returns null for non-test commands, successful runs, or when no failure
+ * line can be pinned down (generic error extraction then applies).
+ */
+function extractTestFailure(name, command, result) {
+  if (name !== "bash" && name !== "shell" && name !== "exec") return null;
+  if (typeof command !== "string" || !TEST_RUN_RE.test(command)) return null;
+  if (result?.isError !== true) return null;
+  const line = failureLine(result);
+  if (line === null) return null;
+  const head = command.trim().split(/\s+/).slice(0, 2).join(" ");
+  return `tests failed (${head}): ${line}`;
+}
+
+/** First failure-flavoured line of a result (≤120 chars), else its head. */
+function failureLine(result) {
+  const blocks = [];
+  const value = result?.value;
+  if (typeof value === "string" && value.length > 0) blocks.push(value);
+  if (value !== null && typeof value === "object") {
+    for (const k of ["error", "stderr", "message", "stdout"]) {
+      if (typeof value[k] === "string" && value[k].length > 0) blocks.push(value[k]);
+    }
+  }
+  const content = result?.content;
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block?.type === "text" && typeof block.text === "string") blocks.push(block.text);
+    }
+  }
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim().replace(/\s+/g, " ").slice(0, 120);
+      if (FAILURE_LINE_RE.test(trimmed)) return trimmed;
+    }
+  }
+  const first = blocks[0];
+  return typeof first === "string" && first.length > 0 ? first.split("\n")[0].trim().slice(0, 120) : null;
+}
+
 function dirOf(path) {
   const i = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
   return i > 0 ? path.slice(0, i) : ".";