npm - pi-okf-memory - Versions diffs - 0.1.0 - Mend

pi-okf-memory 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/LICENSE +21 -0
package/README.en.md +204 -0
package/README.md +265 -0
package/cordis.patch.yml +6 -0
package/docs/graph-demo.png +0 -0
package/lib/capture.js +53 -0
package/lib/client.js +417 -0
package/lib/client.js.map +1 -0
package/lib/concept.js +264 -0
package/lib/dedupe.js +149 -0
package/lib/graph.js +95 -0
package/lib/index.js +381 -0
package/lib/learning.js +185 -0
package/lib/memory.js +135 -0
package/lib/recall.js +47 -0
package/lib/store.js +217 -0
package/package.json +89 -0
package/src/client/index.tsx +232 -0
package/src/pi/graph-html.ts +300 -0
package/src/pi/index.ts +383 -0
package/src/server/capture.ts +52 -0
package/src/server/concept.ts +302 -0
package/src/server/dedupe.ts +164 -0
package/src/server/dsh-tools.d.ts +11 -0
package/src/server/graph.ts +135 -0
package/src/server/index.ts +376 -0
package/src/server/learning.ts +219 -0
package/src/server/memory.ts +157 -0
package/src/server/recall.ts +58 -0
package/src/server/store.ts +255 -0

package/src/pi/graph-html.ts ADDED Viewed

@@ -0,0 +1,300 @@
+/**
+ * graph-html.ts — 把记忆图谱渲染成自包含交互式 HTML。
+ *
+ * 为什么不用 web 面板:pi 是 TUI/RPC 运行时,没有 dsh 的 webServer 注入点,
+ * 因此把 src/client/index.tsx 的 canvas 图谱逻辑(环形布局 / 滚轮缩放 / 拖拽平移与拖节点 /
+ * 悬停详情 / 搜索命中脉冲 + BFS 神经传导)平移为无依赖的独立页面,
+ * 由 /memory-graph 命令生成到临时目录并用系统浏览器打开。
+ *
+ * 输出不依赖任何 CDN 或构建产物,单文件可离线打开、可分享。
+ */
+import type { GraphData } from '../server/graph.js'
+/** 类型配色(与 dsh client 保持一致) */
+const TYPE_COLORS: Record<string, string> = {
+  Fact: '#2f7bff', Preference: '#ffd400', Decision: '#ff2d55', Method: '#00e66e',
+  Insight: '#c04dff', Idea: '#ff7a00', Lesson: '#c8d1dd', TechChoice: '#00e5ff', Other: '#9aa7b8',
+}
+/** JSON 内联进 <script> 时的转义(防 `</script>` 提前闭合) */
+function inlineJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c').replace(/\u2028|\u2029/g, (m) => (m === '\u2028' ? '\\u2028' : '\\u2029'))
+}
+function escapeHtml(s: unknown): string {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c] as string
+  ))
+}
+/**
+ * 生成图谱 HTML。
+ * @param g buildGraph() 的输出
+ */
+export function renderGraphHtml(g: GraphData): string {
+  const canvasData = { nodes: g.nodes, edges: g.edges.map((e) => ({ source: e.source, target: e.target })) }
+  // 顶部统计(服务端渲染,便于无 JS 时也能读)
+  const byType = new Map<string, number>()
+  for (const n of g.nodes) byType.set(n.type, (byType.get(n.type) || 0) + 1)
+  const typeRows = [...byType.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([t, c]) => `<span class="chip"><i style="background:${TYPE_COLORS[t] || TYPE_COLORS.Other}"></i>${escapeHtml(t)} <b>${c}</b></span>`)
+    .join('')
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>OKF 记忆图谱 · ${g.meta.totalConcepts} 节点</title>
+<style>
+  * { box-sizing: border-box; }
+  html, body { margin: 0; height: 100%; background: #0d1725; color: #dbe7f3;
+    font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Helvetica Neue", sans-serif; }
+  header { padding: 14px 18px 10px; border-bottom: 1px solid rgba(120,160,200,.14); }
+  h1 { margin: 0 0 8px; font-size: 15px; font-weight: 600; letter-spacing: .2px; }
+  h1 small { font-weight: 400; color: #7d97b0; margin-left: 8px; font-size: 12px; }
+  .meta { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; font-size: 11px; color: #8aa4bd; }
+  .chip { display: inline-flex; align-items: center; gap: 5px; padding: 2px 8px;
+    border-radius: 20px; background: rgba(255,255,255,.05); }
+  .chip i { width: 7px; height: 7px; border-radius: 50%; display: inline-block; }
+  .chip b { color: #dbe7f3; font-weight: 600; }
+  .bar { display: flex; gap: 10px; align-items: center; padding: 10px 18px; }
+  #q { flex: 1; padding: 9px 12px; border-radius: 8px; border: 1px solid rgba(120,160,200,.3);
+    background: rgba(20,32,46,.8); color: #dbe7f3; font-size: 13px; outline: none; }
+  #q:focus { border-color: rgba(126,195,255,.55); }
+  #hint { font-size: 11px; color: #6f8ba5; white-space: nowrap; }
+  .stage { position: relative; padding: 0 18px 18px; }
+  canvas { width: 100%; height: calc(100vh - 190px); display: block; border-radius: 10px; cursor: crosshair; }
+  #tip { position: absolute; top: 10px; right: 30px; max-width: 340px; padding: 10px 13px;
+    border-radius: 9px; background: rgba(10,18,28,.97); font-size: 12px; line-height: 1.5;
+    box-shadow: 0 8px 26px rgba(0,0,0,.55); display: none; }
+  #tip .t { font-weight: 600; font-size: 13px; }
+  #tip .ty { font-size: 10px; padding: 1px 7px; border-radius: 8px; margin-left: 6px; color: #fff; }
+  #tip .dim { color: #8aa4bd; margin-top: 4px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>OKF 记忆图谱<small>${escapeHtml(g.meta.root)}</small></h1>
+  <div class="meta">
+    <span class="chip">节点 <b>${g.nodes.length}</b></span>
+    <span class="chip">边 <b>${g.edges.length}</b></span>
+    <span class="chip">生成于 <b>${escapeHtml(String(g.meta.generatedAt).slice(0, 19).replace('T', ' '))}</b></span>
+    ${typeRows}
+  </div>
+</header>
+<div class="bar">
+  <input id="q" placeholder="🔍 命中记忆(搜标题 / 类型 / 标签)…" autocomplete="off">
+  <span id="hint">滚轮缩放 · 拖拽平移 · 拖节点 · 悬停详情</span>
+</div>
+<div class="stage">
+  <canvas id="c"></canvas>
+  <div id="tip"></div>
+</div>
+<script>
+const GRAPH = ${inlineJson(canvasData)};
+const TYPE_COLORS = ${inlineJson(TYPE_COLORS)};
+const canvas = document.getElementById('c');
+const ctx = canvas.getContext('2d');
+const tip = document.getElementById('tip');
+const qInput = document.getElementById('q');
+const view = { zoom: 1, panX: 0, panY: 0 };
+let drag = { id: null, offX: 0, offY: 0, panning: false, lastX: 0, lastY: 0 };
+let hoverId = null;
+let query = '';
+function hash(s) { let h = 0; for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0; return h; }
+function hexToRgba(hex, a) {
+  const c = hex.replace('#', '');
+  return 'rgba(' + parseInt(c.slice(0,2),16) + ',' + parseInt(c.slice(2,4),16) + ',' + parseInt(c.slice(4,6),16) + ',' + a + ')';
+}
+// ── 环形初始布局(与 dsh client 一致;拖拽后不再自动回弹) ──
+const maxW = Math.max(...GRAPH.nodes.map(n => n.weight), 1);
+const N = GRAPH.nodes.length || 1;
+const R = Math.max(120, Math.min(300, 60 + N * 30));
+const layout = GRAPH.nodes.map((node, i) => {
+  const h = hash(node.id);
+  const ang = (i / N) * Math.PI * 2;
+  const r = R * (0.6 + ((h % 100) / 100) * 0.5);
+  return Object.assign({}, node, {
+    x: Math.cos(ang) * r, y: Math.sin(ang) * r,
+    r: 8 + Math.sqrt(node.weight / maxW) * 20,
+  });
+});
+const byId = new Map(layout.map(n => [n.id, n]));
+function matches(n, q) {
+  const t = q.trim().toLowerCase();
+  if (!t) return false;
+  return (n.title + ' ' + n.type + ' ' + (n.tags || []).join(' ')).toLowerCase().includes(t);
+}
+// BFS 神经传导:命中节点的关联节点逐级激活
+function activateHits(hits) {
+  const act = new Set(hits);
+  const adj = new Map();
+  GRAPH.edges.forEach(e => {
+    if (!adj.has(e.source)) adj.set(e.source, []);
+    if (!adj.has(e.target)) adj.set(e.target, []);
+    adj.get(e.source).push(e.target);
+    adj.get(e.target).push(e.source);
+  });
+  const queue = [...hits];
+  while (queue.length) {
+    const cur = queue.shift();
+    (adj.get(cur) || []).forEach(nb => { if (!act.has(nb)) { act.add(nb); queue.push(nb); } });
+  }
+  return act;
+}
+function hitTest(px, py, cw, ch) {
+  const wx = (px - cw / 2 - view.panX) / view.zoom;
+  const wy = (py - ch / 2 - view.panY) / view.zoom;
+  for (let i = layout.length - 1; i >= 0; i--) {
+    const n = layout[i];
+    const dx = n.x - wx, dy = n.y - wy;
+    if (dx * dx + dy * dy < (n.r + 6) * (n.r + 6)) return n;
+  }
+  return null;
+}
+function draw() {
+  const dpr = window.devicePixelRatio || 1;
+  const W = canvas.clientWidth || 800, H = canvas.clientHeight || 500;
+  canvas.width = W * dpr; canvas.height = H * dpr;
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  const tx = x => W / 2 + x * view.zoom + view.panX;
+  const ty = y => H / 2 + y * view.zoom + view.panY;
+  ctx.fillStyle = '#13233a'; ctx.fillRect(0, 0, W, H);
+  const hits = new Set();
+  if (query.trim()) GRAPH.nodes.forEach(n => { if (matches(n, query)) hits.add(n.id); });
+  const active = activateHits(hits);
+  // 边
+  GRAPH.edges.forEach(e => {
+    const a = byId.get(e.source), b = byId.get(e.target);
+    if (!a || !b) return;
+    const isActive = active.has(e.source) || active.has(e.target);
+    ctx.beginPath(); ctx.moveTo(tx(a.x), ty(a.y)); ctx.lineTo(tx(b.x), ty(b.y));
+    ctx.strokeStyle = isActive ? 'rgba(126,195,255,.5)' : 'rgba(120,160,200,.18)';
+    ctx.lineWidth = 1 / view.zoom; ctx.stroke();
+  });
+  const t = performance.now() / 700;
+  layout.forEach(n => {
+    const c = TYPE_COLORS[n.type] || TYPE_COLORS.Other;
+    const isHit = hits.has(n.id), isActive = active.has(n.id);
+    const rr = n.r * view.zoom;
+    const x = tx(n.x), y = ty(n.y);
+    // 命中脉冲光环
+    if (isHit) {
+      const tp = (t + (hash(n.id) % 10) / 10) % 1;
+      ctx.beginPath(); ctx.arc(x, y, rr * (1.5 + tp * 1.8), 0, Math.PI * 2);
+      ctx.strokeStyle = hexToRgba(c, 0.8 * (1 - tp)); ctx.lineWidth = 2.5 / view.zoom; ctx.stroke();
+    }
+    // 激活辉光
+    if (isHit || isActive) {
+      const rad = rr * (isHit ? 2.9 : 2.1);
+      const rg = ctx.createRadialGradient(x, y, rr * 0.2, x, y, rad);
+      rg.addColorStop(0, hexToRgba(c, isHit ? 0.8 : 0.45));
+      rg.addColorStop(1, 'transparent');
+      ctx.beginPath(); ctx.arc(x, y, rad, 0, Math.PI * 2); ctx.fillStyle = rg; ctx.fill();
+    }
+    // 节点本体
+    ctx.beginPath(); ctx.arc(x, y, rr, 0, Math.PI * 2);
+    ctx.fillStyle = isActive ? (isHit ? '#fff' : c) : '#13233a';
+    ctx.globalAlpha = isActive ? 0.95 : 1; ctx.fill(); ctx.globalAlpha = 1;
+    ctx.beginPath(); ctx.arc(x, y, rr, 0, Math.PI * 2);
+    ctx.strokeStyle = isHit ? '#fff' : (isActive ? c : '#33506a');
+    ctx.lineWidth = (isHit ? 3.2 : 1.2) / view.zoom; ctx.stroke();
+    // archived 虚线描边(状态可见)
+    if (n.state === 'inactive') {
+      ctx.setLineDash([3 / view.zoom, 3 / view.zoom]);
+      ctx.beginPath(); ctx.arc(x, y, rr + 3, 0, Math.PI * 2);
+      ctx.strokeStyle = 'rgba(200,209,221,.5)'; ctx.lineWidth = 1 / view.zoom; ctx.stroke();
+      ctx.setLineDash([]);
+    }
+    // 标签
+    ctx.fillStyle = isActive ? '#fff' : '#5f7d97';
+    ctx.font = (11 * Math.min(1.4, Math.max(0.8, view.zoom))) + 'px sans-serif';
+    ctx.textAlign = 'center';
+    ctx.fillText(String(n.title).slice(0, 10), x, y + rr + 12);
+    if (isHit) {
+      ctx.fillStyle = '#fff';
+      ctx.font = '700 ' + (11 * Math.max(0.8, view.zoom)) + 'px sans-serif';
+      ctx.fillText('⚡命中', x, y - rr - 9);
+    }
+  });
+  if (query.trim()) {
+    document.getElementById('hint').textContent =
+      '命中 ' + hits.size + ' · 传导激活 ' + active.size + ' / ' + layout.length;
+  } else {
+    document.getElementById('hint').textContent = '滚轮缩放 · 拖拽平移 · 拖节点 · 悬停详情';
+  }
+}
+function renderTip(n) {
+  if (!n) { tip.style.display = 'none'; return; }
+  const c = TYPE_COLORS[n.type] || TYPE_COLORS.Other;
+  tip.style.display = 'block';
+  tip.style.border = '1px solid ' + c;
+  tip.innerHTML =
+    '<div><span class="t">' + n.title + '</span>' +
+    '<span class="ty" style="background:' + c + '66">' + n.type + '</span></div>' +
+    '<div class="dim">权重 ' + n.weight + ' · ' + n.state +
+    (n.lastAccessed ? ' · 最近 ' + String(n.lastAccessed).slice(0, 10) : '') + '</div>' +
+    (n.description ? '<div class="dim">' + n.description + '</div>' : '') +
+    ((n.tags && n.tags.length) ? '<div class="dim">' + n.tags.map(x => '#' + x).join(' ') + '</div>' : '');
+}
+// ── 交互 ──
+qInput.addEventListener('input', e => { query = e.target.value; });
+canvas.addEventListener('wheel', e => {
+  e.preventDefault();
+  view.zoom = Math.min(4, Math.max(0.3, view.zoom * (e.deltaY < 0 ? 1.1 : 0.9)));
+}, { passive: false });
+canvas.addEventListener('mousedown', e => {
+  const rect = canvas.getBoundingClientRect();
+  const px = e.clientX - rect.left, py = e.clientY - rect.top;
+  const cw = canvas.clientWidth || rect.width, ch = canvas.clientHeight || rect.height;
+  const hit = hitTest(px, py, cw, ch);
+  if (hit) drag = { id: hit.id, offX: hit.x - px, offY: hit.y - py, panning: false, lastX: px, lastY: py };
+  else drag = { id: null, offX: 0, offY: 0, panning: true, lastX: px, lastY: py };
+});
+canvas.addEventListener('mousemove', e => {
+  const rect = canvas.getBoundingClientRect();
+  const px = e.clientX - rect.left, py = e.clientY - rect.top;
+  const cw = canvas.clientWidth || rect.width, ch = canvas.clientHeight || rect.height;
+  if (drag.id) {
+    const n = byId.get(drag.id);
+    if (n) {
+      n.x = (px - cw / 2 - view.panX) / view.zoom + drag.offX;
+      n.y = (py - ch / 2 - view.panY) / view.zoom + drag.offY;
+    }
+  } else if (drag.panning) {
+    view.panX += px - drag.lastX; view.panY += py - drag.lastY;
+    drag.lastX = px; drag.lastY = py;
+  }
+  const h = hitTest(px, py, cw, ch);
+  const id = h ? h.id : null;
+  if (id !== hoverId) { hoverId = id; renderTip(h); canvas.style.cursor = h ? 'grab' : 'crosshair'; }
+});
+window.addEventListener('mouseup', () => { drag = { id: null, offX: 0, offY: 0, panning: false, lastX: 0, lastY: 0 }; });
+canvas.addEventListener('mouseleave', () => { hoverId = null; renderTip(null); });
+window.addEventListener('resize', () => { view.zoom = 1; view.panX = 0; view.panY = 0; });
+(function loop() { draw(); requestAnimationFrame(loop); })();
+</script>
+</body>
+</html>`
+}

package/src/pi/index.ts ADDED Viewed

@@ -0,0 +1,383 @@
+/**
+ * pi 适配层 — okf-memory 的 pi 扩展入口(src/pi/index.ts)。
+ *
+ * 与 src/server/index.ts(dsh 适配层)平级:两者共用 src/server/* 的运行时无关核心,
+ * 本文件只做「pi API ↔ 核心逻辑」的翻译。
+ *
+ * 映射关系:
+ *   dsh ctx.tools.register(defineTool({parameters})) → pi.registerTool({parameters: Type.Object})
+ *   dsh ctx.systemPrompt.section({name,order})        → pi.on("before_agent_start") 返回 systemPrompt
+ *   dsh ctx.provide('okfMemory')                      → 删除(工具即 API)
+ *   dsh ctx.inject(['webServer']) + /okf-graph 路由   → /memory-graph 命令导出静态 HTML
+ *
+ * 记忆库默认 ~/.pi/agent/okf-memory/(OKF_MEMORY_ROOT 可覆盖)。
+ */
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+import path from 'node:path'
+import os from 'node:os'
+import { promises as fs } from 'node:fs'
+// ── 运行时无关核心(零改动复用) ──
+import { ensureRoot, scanBundle } from '../server/store.js'
+import { search } from '../server/dedupe.js'
+import { preload, recall } from '../server/recall.js'
+import { loadMeta, recordSelect, recordSkip, consolidate, rank, startConsolidation } from '../server/learning.js'
+import { MEMORY_DISCIPLINE, RECALL_GUIDE } from '../server/capture.js'
+import { TYPE_VOCAB } from '../server/concept.js'
+import { buildGraph } from '../server/graph.js'
+import { rememberCore, forgetCore, type RememberResult, type ForgetResult } from '../server/memory.js'
+import { renderGraphHtml } from './graph-html.js'
+const EXT = 'okf-memory'
+/** 记忆库根:OKF_MEMORY_ROOT > ~/.pi/agent/okf-memory/ */
+function resolveRoot(): string {
+  const env = process.env.OKF_MEMORY_ROOT
+  if (env) return path.resolve(env)
+  return path.join(os.homedir(), '.pi', 'agent', 'okf-memory')
+}
+/** 工具返回值的统一包装(pi 用 content 数组 + details 结构化数据) */
+function text(s: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: 'text' as const, text: s }], details }
+}
+/** 把根 index.md 整理成提示片段(模型每轮可见"库里有啥") */
+async function buildIndexPrompt(root: string): Promise<string> {
+  try {
+    const idx = await fs.readFile(path.join(root, 'index.md'), 'utf8')
+    const concepts = await scanBundle(root)
+    return `记忆库共有 ${concepts.length} 个概念(路径即概念 ID)。库目录:\n${idx.slice(0, 3000)}`
+  } catch {
+    return 'OKF 记忆库为空或不可读。'
+  }
+}
+export default function okfMemoryExtension(pi: ExtensionAPI): void {
+  const root = resolveRoot()
+  /** 当前库摘要,写入后失效重建(避免每轮都扫盘) */
+  let digest = 'OKF 记忆库尚未初始化。'
+  const refreshDigest = async (): Promise<void> => {
+    digest = await buildIndexPrompt(root)
+  }
+  // ────────────────────────────── 工具 ──────────────────────────────
+  pi.registerTool({
+    name: 'okf_remember',
+    label: '记忆沉淀',
+    description:
+      '把一条新知识按 OKF v0.1 规范写入长期记忆库(概念文档 + index/log 更新)。' +
+      `type 词表:${TYPE_VOCAB.join('/')}。` +
+      'Decision/Insight 正文建议用 # 数据/# 分析/# 结论 三段式;TechChoice 用 ## Options 候选表 + ## Active。' +
+      '写入前自动去重:标题相同则更新/跳过,相近则返回建议。',
+    promptSnippet: '沉淀一条长期记忆(自动去重 + OKF 校验)',
+    promptGuidelines: [
+      'Use okf_remember when the user discloses a new durable fact, states a preference, makes a decision with rationale, corrects your understanding, or picks a technology — but search first with okf_search to avoid duplicates.',
+      'Always pass okf_remember a related array holding the concept IDs of concepts returned by okf_search that this new memory relates to — only related-written links become graph edges.',
+      'When okf_remember returns status "linked", resubmit with the returned similarTo value inside related instead of duplicating the body.',
+      'Do NOT call okf_remember for greetings, one-off tasks, or restating something already in the memory library.',
+    ],
+    parameters: Type.Object({
+      title: Type.String({ description: '概念标题(简洁,一句话可懂)' }),
+      type: Type.String({ description: `概念类型,可选:${TYPE_VOCAB.join('/')}` }),
+      content: Type.String({ description: '结构化正文(Markdown,含 # 小节标题)。Decision/Insight 传三段式;TechChoice 传 Options 表与 Active' }),
+      tags: Type.Optional(Type.Array(Type.String(), { description: '横切标签' })),
+      related: Type.Optional(Type.Array(Type.String(), { description: '相关概念 ID 列表(将互建交叉链接)' })),
+    }, { additionalProperties: false }),
+    async execute(_id, params) {
+      try {
+        const r: RememberResult = await rememberCore(root, {
+          title: params.title,
+          type: params.type,
+          tags: params.tags as string[] | undefined,
+          related: params.related as string[] | undefined,
+        }, params.content)
+        await refreshDigest()
+        const msg = r.status === 'created' ? `已沉淀记忆 ${r.conceptId}`
+          : r.status === 'updated' ? `已更新记忆 ${r.conceptId}`
+            : r.status === 'skipped' ? `跳过写入:${r.reason}`
+              : r.status === 'linked' ? `建议互补:${r.reason}`
+                : `记忆写入:${r.status}`
+        return text(msg, r as unknown as Record<string, unknown>)
+      } catch (e) {
+        return text(`记忆写入失败:${String((e as Error).message || e)}`, { status: 'error', reason: String((e as Error).message || e) })
+      }
+    },
+  })
+  pi.registerTool({
+    name: 'okf_search',
+    label: '记忆召回',
+    description:
+      '检索 OKF 长期记忆库,按唤起评分(相关度 × 权重 × 近因)排序返回概念摘要。' +
+      '命中 TechChoice 类型时附加返回完整 Options 候选表,供技术选型三档规则展示。' +
+      '写入新记忆前必须先搜索去重。',
+    promptSnippet: '检索长期记忆(按 相关度 × 权重 × 近因 排序)',
+    promptGuidelines: [
+      'Use okf_search before answering questions that may depend on the user\'s stored background, preferences, or past decisions, and always before okf_remember.',
+      'If okf_search returns no match, tell the user the memory library has nothing — never invent a memory.',
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: '检索关键词' }),
+      type: Type.Optional(Type.String({ description: '按类型过滤(如 TechChoice/Fact/Decision)' })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: '按标签过滤' })),
+      limit: Type.Optional(Type.Number({ description: '返回条数,默认 8' })),
+    }, { additionalProperties: false }),
+    async execute(_id, params) {
+      const raw = await search(root, String(params.query), {
+        type: params.type as string | undefined,
+        tags: params.tags as string[] | undefined,
+        limit: Math.min(Number(params.limit) || 8, 30),
+      })
+      const ranked = await rank(root, raw)
+      const results: Array<Record<string, unknown>> = []
+      for (const h of ranked) {
+        const item: Record<string, unknown> = { ...h }
+        if (h.type === 'TechChoice') {
+          // 附加候选表:读全文 Options 节
+          try {
+            const { readConcept } = await import('../server/store.js')
+            const c = await readConcept(root, h.conceptId)
+            const m = /## Options[\s\S]*?(?=## |$)/.exec(c.body || '')
+            item.options = m ? m[0].trim() : null
+          } catch { /* 读取失败则不带候选表 */ }
+        }
+        results.push(item)
+      }
+      const msg = results.length === 0
+        ? '记忆库无匹配。'
+        : `检索到 ${results.length} 条记忆:\n` + results.map((r) => `- ${r.conceptId} (${r.type}, 权重 ${r.weight}) ${r.description}`).join('\n')
+      return text(msg, { count: results.length, results })
+    },
+  })
+  pi.registerTool({
+    name: 'okf_read',
+    label: '记忆精读',
+    description:
+      '读取记忆库中某个概念全文(含交叉链接),并记录一次使用反馈(权重 +0.1)。',
+    promptSnippet: '读取某条记忆全文并记录一次使用反馈',
+    parameters: Type.Object({
+      concept_id: Type.String({ description: '概念 ID(如 fact/门店布局,可省略 .md)' }),
+    }, { additionalProperties: false }),
+    async execute(_id, params) {
+      const id = String(params.concept_id).replace(/\.md$/, '')
+      const c = await recall(root, id)
+      return text(`# ${c.meta?.title || id} (${c.meta?.type || ''})\n\n${c.body || ''}`, {
+        conceptId: c.conceptId,
+        title: c.meta?.title || id,
+        type: c.meta?.type || '',
+        body: c.body || '',
+        links: c.links || [],
+      })
+    },
+  })
+  pi.registerTool({
+    name: 'okf_forget',
+    label: '记忆撤回',
+    description:
+      '从记忆库索引撤回一条概念(默认保留文件,可从 index/log 追溯;可选删除文件)。',
+    promptSnippet: '撤回一条记错的记忆',
+    parameters: Type.Object({
+      concept_id: Type.String({ description: '概念 ID' }),
+      delete_file: Type.Optional(Type.Boolean({ description: 'true 时同时删除文件(默认 false 仅移出索引)' })),
+    }, { additionalProperties: false }),
+    async execute(_id, params) {
+      const id = String(params.concept_id).replace(/\.md$/, '')
+      try {
+        const r: ForgetResult = await forgetCore(root, id, params.delete_file === true)
+        await refreshDigest()
+        const msg = r.status === 'forgotten' ? `已撤回记忆 ${r.conceptId}${r.reason ? `(${r.reason})` : ''}`
+          : r.status === 'not_found' ? `记忆 ${r.conceptId} 不存在或已撤回`
+            : `撤回失败:${r.reason || r.status}`
+        return text(msg, r as unknown as Record<string, unknown>)
+      } catch (e) {
+        return text(`撤回失败:${String((e as Error).message || e)}`, { status: 'error', reason: String((e as Error).message || e) })
+      }
+    },
+  })
+  pi.registerTool({
+    name: 'okf_graph',
+    label: '记忆图谱',
+    description:
+      '导出记忆库的图谱 JSON:nodes(概念:title/type/tags/weight/state)+edges(交叉链接)+timeline(权重快照)。',
+    promptSnippet: '导出记忆图谱 JSON(nodes/edges/timeline)',
+    parameters: Type.Object({
+      limit: Type.Optional(Type.Number({ description: '可选:节点上限,默认全部' })),
+    }, { additionalProperties: false }),
+    async execute(_id, params) {
+      const g = await buildGraph(root)
+      const nodes = params.limit && Number(params.limit) > 0
+        ? g.nodes.slice(0, Math.min(Number(params.limit), 500))
+        : g.nodes
+      return text(
+        `记忆图谱:${nodes.length} 节点 · ${g.edges.length} 边 · ${g.timeline.length} 权重记录`,
+        { meta: g.meta, nodes, edges: g.edges, timeline: g.timeline },
+      )
+    },
+  })
+  // ── 修复 dsh 侧的反馈回路缺口:recordSelect / recordSkip 此前无任何调用入口 ──
+  pi.registerTool({
+    name: 'okf_feedback',
+    label: '记忆反馈',
+    description:
+      '对某条记忆给出显式反馈,更新其学习权重。action=select(用户选中/确认采用)权重 +1.0;' +
+      'action=skip(用户跳过/否定)权重 −0.5。用于技术选型候选拍板、被否定结论等场景。',
+    promptSnippet: '记录用户对某条记忆的选中(+1.0)或跳过(−0.5)反馈',
+    promptGuidelines: [
+      'Use okf_feedback with action "select" when the user confirms or picks a memory-backed option (for example a TechChoice candidate), and with action "skip" when the user rejects or ignores one.',
+    ],
+    parameters: Type.Object({
+      concept_id: Type.String({ description: '概念 ID' }),
+      action: Type.String({ description: 'select(选中,+1.0)或 skip(跳过,−0.5)' }),
+    }, { additionalProperties: false }),
+    async execute(_id, params) {
+      const id = String(params.concept_id).replace(/\.md$/, '')
+      const action = String(params.action)
+      if (action !== 'select' && action !== 'skip') {
+        return text(`无效 action:「${action}」;可选 select / skip`, { status: 'error' })
+      }
+      try {
+        const weight = action === 'select'
+          ? await recordSelect(root, id)
+          : await recordSkip(root, id)
+        return text(`${action === 'select' ? '已记录选中' : '已记录跳过'} ${id} → 权重 ${weight.toFixed(2)}`, { status: 'ok', conceptId: id, action, weight })
+      } catch (e) {
+        return text(`反馈记录失败:${String((e as Error).message || e)}`, { status: 'error', reason: String((e as Error).message || e) })
+      }
+    },
+  })
+  // ──────────────────── 系统提示注入(替代 dsh 的 section API) ────────────────────
+  pi.on('before_agent_start', async (event) => {
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${MEMORY_DISCIPLINE}\n\n# 记忆库现状\n\n${digest}\n\n${RECALL_GUIDE}`,
+    }
+  })
+  // ────────────────────────────── 命令 ──────────────────────────────
+  // 单一入口 /okf + 子命令 — 比 /memory-search、/memory-consolidate 这类长名少敲很多,
+  // 且子命令可 Tab 补全。pi 生态的常见形态(如 /subagents-guide [topic]、/run <agent> [task])。
+  /** 子命令表(同时用于参数补全与用法提示) */
+  const SUBS: Array<{ value: string; hint: string }> = [
+    { value: 'status', hint: '库状态 / 概念数 / 权重榜(默认)' },
+    { value: 'search', hint: '搜索记忆:search <关键词>' },
+    { value: 'graph', hint: '导出单文件自包含图谱 HTML 并打开' },
+    { value: 'consolidate', hint: '立即跑一次巩固(衰减 + 归档)' },
+  ]
+  const USAGE = '用法:/okf [status | search <关键词> | graph | consolidate]'
+  /** /okf(不带参数)= status */
+  const cmdStatus = async (ctx: ExtensionContext): Promise<void> => {
+    const concepts = await scanBundle(root)
+    const meta = await loadMeta(root)
+    const entries = Object.entries(meta.entries)
+      .sort((a, b) => b[1].weight - a[1].weight)
+      .slice(0, 8)
+    const lines = [
+      `记忆库:${root}`,
+      `概念数:${concepts.length}`,
+      entries.length ? `\n权重榜(前 ${entries.length}):` : '',
+      ...entries.map(([id, e]) => `  ${e.weight.toFixed(2)}  ${e.state === 'inactive' ? '⏸ ' : ''}${id}  (访问 ${e.accessCount} 次)`),
+    ].filter(Boolean)
+    ctx.ui.notify(lines.join('\n'), 'info')
+  }
+  const cmdSearch = async (q: string, ctx: ExtensionContext): Promise<void> => {
+    const query = q.trim()
+    if (!query) {
+      ctx.ui.notify('用法:/okf search <关键词>', 'warning')
+      return
+    }
+    const hits = await preload(root, query, { limit: 8 })
+    if (hits.length === 0) {
+      ctx.ui.notify(`记忆库无匹配:「${query}」`, 'info')
+      return
+    }
+    ctx.ui.notify(
+      hits.map((h) => `${h.weight.toFixed(2)}  ${h.conceptId} (${h.type}) — ${h.description}`).join('\n'),
+      'info',
+    )
+  }
+  const cmdGraph = async (ctx: ExtensionContext): Promise<void> => {
+    const g = await buildGraph(root)
+    const out = path.join(os.tmpdir(), `okf-memory-graph-${Date.now()}.html`)
+    await fs.writeFile(out, renderGraphHtml(g), 'utf8')
+    try {
+      await pi.exec('open', [out])
+      ctx.ui.notify(`已打开记忆图谱(${g.nodes.length} 节点 / ${g.edges.length} 边)\n${out}`, 'info')
+    } catch (e) {
+      ctx.ui.notify(`图谱已生成(自动打开失败:${String((e as Error).message || e)}):\n${out}`, 'warning')
+    }
+  }
+  const cmdConsolidate = async (ctx: ExtensionContext): Promise<void> => {
+    const meta = await consolidate(root)
+    const entries = Object.values(meta.entries)
+    const inactive = entries.filter((e) => e.state === 'inactive').length
+    ctx.ui.notify(`巩固完成:${entries.length} 条记忆,其中 ${inactive} 条已归档(inactive)`, 'info')
+  }
+  pi.registerCommand('okf', {
+    description: 'OKF 记忆库:/okf [status|search <词>|graph|consolidate]',
+    getArgumentCompletions: (prefix: string) => {
+      // 子命令后再跟参数(如 search 之后的关键词)就不再补全
+      if (prefix.includes(' ')) return null
+      const p = prefix.trim()
+      return SUBS.filter((s) => s.value.startsWith(p)).map((s) => ({ value: s.value, label: `${s.value} — ${s.hint}` }))
+    },
+    handler: async (args, ctx: ExtensionContext) => {
+      const raw = String(args || '').trim()
+      const sp = raw.indexOf(' ')
+      const sub = (sp === -1 ? raw : raw.slice(0, sp)).toLowerCase()
+      const rest = sp === -1 ? '' : raw.slice(sp + 1).trim()
+      switch (sub) {
+        case '':
+        case 'status':
+          await cmdStatus(ctx)
+          return
+        case 'search':
+        case 's':
+          await cmdSearch(rest, ctx)
+          return
+        case 'graph':
+        case 'g':
+          await cmdGraph(ctx)
+          return
+        case 'consolidate':
+        case 'c':
+          await cmdConsolidate(ctx)
+          return
+        case 'help':
+        case '?':
+          ctx.ui.notify(`${USAGE}\n\n${SUBS.map((s) => `  ${s.value.padEnd(12)} ${s.hint}`).join('\n')}`, 'info')
+          return
+        default:
+          ctx.ui.notify(`未知子命令「${sub}」\n${USAGE}`, 'warning')
+      }
+    },
+  })
+  // ─────────────────────────── 生命周期 ───────────────────────────
+  pi.on('session_start', async () => {
+    await ensureRoot(root)
+    await refreshDigest()
+    // 巩固定时器:用 globalThis 标记保证 /reload 后不会叠加多个定时器
+    // (consolidate 是按天数连续衰减,重复运行会加速遗忘)
+    const g = globalThis as Record<string, unknown>
+    if (!g.__okfConsolidationStarted) {
+      g.__okfConsolidationStarted = true
+      startConsolidation(root)
+    }
+  })
+}