pi-okf-memory 0.1.0

package/src/server/index.ts

@@ -0,0 +1,376 @@
+/**
+ * okf-memory — 会话记忆 → OKF 知识沉淀:dsh 适配层(src/server/index.ts)。
+ * pi 侧入口见 src/pi/index.ts;两者共用本目录下的运行时无关核心。
+ *
+ * 工具:okf_remember / okf_search / okf_read / okf_forget / okf_graph
+ * 服务:ctx.okfMemory(root, search, read, write, consolidate, meta, preload, graph)
+ * 记忆库:OKF v0.1 bundle,默认 ~/.dsh/memory/(环境变量 OKF_MEMORY_ROOT 可覆盖)
+ */
+import path from 'node:path'
+import { promises as fs } from 'node:fs'
+import {
+  ensureRoot, writeConcept, readConcept, defaultRoot, scanBundle,
+  type WriteResult,
+} from './store.js'
+import { search, type SearchHit } from './dedupe.js'
+import { preload, recall } from './recall.js'
+import { loadMeta, consolidate, rank, startConsolidation, type MemoryMeta } from './learning.js'
+import { MEMORY_DISCIPLINE, RECALL_GUIDE } from './capture.js'
+import { TYPE_VOCAB, type ConceptMeta } from './concept.js'
+import { buildGraph, type GraphData } from './graph.js'
+// 运行时无关的写入/撤回核心(与 pi 适配层共用)
+import {
+  rememberCore, forgetCore,
+  type RememberArgs, type RememberOpts, type RememberResult, type ForgetResult,
+} from './memory.js'
+
+/**
+ * defineTool 动态解析:dsh 运行时提供 @deepseek-ai/dsh-tools 时用官方 API,
+ * 不可用时降级为透传定义对象(兼容运行时不暴露该包的情况)。
+ */
+async function loadDefineTool(): Promise<(def: unknown) => unknown> {
+  try {
+    const mod = await import('@deepseek-ai/dsh-tools')
+    return (mod as { defineTool?: (d: unknown) => unknown }).defineTool || ((def: unknown) => def)
+  } catch {
+    return (def: unknown) => def
+  }
+}
+
+export const name = 'okf-memory'
+
+export const inject = ['tools', 'systemPrompt']
+
+/** 会话启动预取条数 */
+const PRELOAD_LIMIT = 5
+
+/** 最小 dsh Cordis 上下文类型(实际以运行时为准;只声明本插件用到的面) */
+export interface DshContext {
+  settings?: { okfMemory?: { root?: string } }
+  systemPrompt?: { section: (opts: { name: string; order: number; text: string }) => void }
+  provide?: (name: string, impl: unknown) => void
+  tools: { register: (def: unknown) => void }
+  inject?: (services: string[], fn: (scope: Record<string, unknown>) => void) => void
+  okfMemory?: unknown
+  [key: string]: unknown
+}
+
+/** 解析记忆库根目录(优先级:settings > env > 默认) */
+function resolveRoot(ctx: DshContext): string {
+  try {
+    const s = ctx.settings?.okfMemory?.root
+    if (s) return path.resolve(String(s))
+  } catch { /* settings API 不可用时忽略 */ }
+  return defaultRoot()
+}
+
+/**
+ * 注入系统提示片段(正确 API:dsh-system-prompt 的 section,字段 name/order/text。
+ * 之前误用 add() 静默失效;不能用 register()。失败时静默跳过,不阻塞插件加载)。
+ */
+function addPrompt(ctx: DshContext, name: string, content: string, order: number): void {
+  try {
+    if (ctx.systemPrompt?.section) {
+      ctx.systemPrompt.section({ name, order, text: content })
+    }
+  } catch { /* 无 systemPrompt 扩展点时跳过 */ }
+}
+
+/** 把根 index.md 摘要整理成提示片段(模型每轮可见"库里有啥") */
+async function buildIndexPrompt(root: string): Promise<string> {
+  try {
+    const text = await fs.readFile(path.join(root, 'index.md'), 'utf8')
+    const concepts = await scanBundle(root)
+    return `记忆库共有 ${concepts.length} 个概念(路径即概念 ID)。库目录:\n${text.slice(0, 3000)}`
+  } catch {
+    return 'OKF 记忆库为空或不可读。'
+  }
+}
+
+interface OkfMemoryService {
+  root: string
+  search: (q: string, opts?: object) => Promise<SearchHit[]>
+  read: (id: string) => Promise<unknown>
+  write: (meta: ConceptMeta, body: string) => Promise<WriteResult>
+  remember: (meta: RememberArgs, body: string, opts?: RememberOpts) => Promise<RememberResult>
+  consolidate: () => Promise<MemoryMeta>
+  meta: () => Promise<MemoryMeta>
+  preload: (query: string, opts?: object) => Promise<unknown>
+  graph: (opts?: object) => Promise<GraphData>
+}
+
+export async function apply(ctx: DshContext): Promise<() => void> {
+  const defineTool = await loadDefineTool()
+  const root = resolveRoot(ctx)
+  await ensureRoot(root)
+
+  // ── 服务:ctx.okfMemory(供其他插件/工具消费) ──
+  const service: OkfMemoryService = {
+    root,
+    search: (q, opts) => search(root, q, opts),
+    read: (id) => recall(root, id),
+    write: (meta, body) => writeConcept(root, meta, body),
+    remember: (meta, body, opts) => rememberCore(root, meta, body, opts),
+    consolidate: () => consolidate(root),
+    meta: () => loadMeta(root),
+    preload: (query, opts) => preload(root, query, opts),
+    graph: (opts) => buildGraph(root, opts),
+  }
+  try {
+    ctx.provide?.('okfMemory', service)
+  } catch {
+    ctx.okfMemory = service
+  }
+  ctx.okfMemory = service
+
+  // ── Web 路由:/okf-graph 供 client 插件 fetch 记忆图谱 JSON(M2) ──
+  // webServer 只在 web profile 存在;声明式 inject 会在 headless 加载失败,
+  // 故用 modlens 同款的运行时按需注入 ctx.inject(['webServer'], scope).
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], (scope) => {
+      try {
+        const ws = scope.webServer as { register: (opts: { name: string; kind: string; path: string; handler: (req: unknown, res: { writeHead: (s: number, h: Record<string, string>) => void; end: (b: string) => void }) => Promise<void> | void }) => void }
+        ws.register({
+          name: 'okf-memory-graph',
+          kind: 'exact',
+          path: '/okf-graph',
+          handler: async (_req, res) => {
+            try {
+              const g = await buildGraph(root)
+              res.writeHead(200, { 'content-type': 'application/json' })
+              res.end(JSON.stringify(g))
+            } catch (e) {
+              res.writeHead(500, { 'content-type': 'application/json' })
+              res.end(JSON.stringify({ error: String((e as Error).message || e) }))
+            }
+          },
+        })
+      } catch {
+        /* 无 webServer 时跳过 */
+      }
+    })
+  }
+
+  // ── 工具 1:okf_remember(核心:概念化→去重→写入→索引) ──
+  ctx.tools.register(defineTool({
+    name: 'okf_remember',
+    description:
+      '把一条新知识按 OKF v0.1 规范写入长期记忆库(概念文档 + index/log 更新)。' +
+      'type 词表:Fact/Preference/Decision/Method/Insight/Idea/Lesson/TechChoice。' +
+      'Decision/Insight 正文建议用 # 数据/# 分析/# 结论 三段式;TechChoice 用 # Options 候选表 + # Active。' +
+      '写入前自动去重:标题相同则更新/跳过,相近则返回建议。' +
+      'Write a new piece of knowledge into the long-term memory library as an OKF v0.1 concept (updates index/log). ' +
+      'Types: Fact/Preference/Decision/Method/Insight/Idea/Lesson/TechChoice. Deduplicates automatically: same title → update or skip; similar → returns suggestion.',
+    parameters: {
+      title: { type: 'string', required: true, description: '概念标题(简洁,一句话可懂)' },
+      type: { type: 'string', required: true, description: `概念类型,可选:${TYPE_VOCAB.join('/')}` },
+      content: { type: 'string', required: true, description: '结构化正文(Markdown,含 # 小节标题)。Decision/Insight 传三段式;TechChoice 传 Options 表与 Active' },
+      tags: { type: 'array', items: { type: 'string' }, description: '横切标签' },
+      related: { type: 'array', items: { type: 'string' }, description: '相关概念 ID 列表(将互建交叉链接)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          status: { type: 'string' },
+          conceptId: { type: 'string' },
+          filePath: { type: 'string' },
+          reason: { type: 'string' },
+        },
+      },
+      render: (_args: unknown, value: RememberResult) => [{
+        type: 'text',
+        text: value.status === 'error'
+          ? `记忆写入失败:${value.reason}`
+          : value.status === 'created'
+            ? `已沉淀记忆 ${value.conceptId}`
+            : value.status === 'updated'
+              ? `已更新记忆 ${value.conceptId}`
+              : value.status === 'skipped'
+                ? `跳过写入:${value.reason}`
+                : `记忆写入:${value.status}`,
+      }],
+    },
+    async execute(args: { title: string; type: string; content: string; tags?: string[]; related?: string[] }) {
+      try {
+        return await rememberCore(root, {
+          title: args.title,
+          type: args.type,
+          tags: args.tags,
+          related: args.related,
+        }, args.content)
+      } catch (e) {
+        return { status: 'error', conceptId: null, reason: String((e as Error).message || e) }
+      }
+    },
+  }))
+
+  // ── 工具 2:okf_search(检索,命中 TechChoice 返回完整候选表) ──
+  ctx.tools.register(defineTool({
+    name: 'okf_search',
+    description:
+      '检索 OKF 长期记忆库,按唤起评分(相关度×权重×近因)排序返回概念摘要。' +
+      '命中 TechChoice 类型时附加返回完整 Options 候选表,供技术选型三档规则展示。' +
+      '写入新记忆前必须先搜索去重。' +
+      'Search the OKF long-term memory library, returning concept summaries ranked by recall score (relevance × weight × recency). ' +
+      'TechChoice hits additionally return the full Options table. Always search before writing new memory.',
+    parameters: {
+      query: { type: 'string', required: true, description: '检索关键词' },
+      type: { type: 'string', description: '按类型过滤(如 TechChoice/Fact/Decision)' },
+      tags: { type: 'array', items: { type: 'string' }, description: '按标签过滤' },
+      limit: { type: 'number', description: '返回条数,默认 8' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          count: { type: 'number' },
+          results: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: (_args: unknown, value: { count: number; results: Array<{ conceptId: string; type: string; weight: number; description: string }> }) => [{
+        type: 'text',
+        text: value.count === 0
+          ? '记忆库无匹配。'
+          : `检索到 ${value.count} 条记忆:\n` + value.results.map((r) => `- ${r.conceptId} (${r.type}, 权重 ${r.weight}) ${r.description}`).join('\n'),
+      }],
+    },
+    async execute(args: { query: string; type?: string; tags?: string[]; limit?: number }) {
+      const raw = await search(root, args.query, {
+        type: args.type,
+        tags: args.tags,
+        limit: Math.min(args.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 { body } = await readConcept(root, h.conceptId)
+            const optsMatch = /## Options[\s\S]*?(?=## |$)/.exec(body || '')
+            item.options = optsMatch ? optsMatch[0].trim() : null
+          } catch { /* 读取失败则不带候选表 */ }
+        }
+        results.push(item)
+      }
+      return { count: results.length, results }
+    },
+  }))
+
+  // ── 工具 3:okf_read(精读 + 交叉链接 + 命中反馈) ──
+  ctx.tools.register(defineTool({
+    name: 'okf_read',
+    description:
+      '读取记忆库中某个概念全文(含交叉链接),并记录一次使用反馈(权重更新)。' +
+      'Read a full concept from the memory library (with cross-links) and record one usage feedback (weight update).',
+    parameters: {
+      concept_id: { type: 'string', required: true, description: '概念 ID(如 facts/meituan-data-source,可省略 .md)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          conceptId: { type: 'string' },
+          title: { type: 'string' },
+          type: { type: 'string' },
+          body: { type: 'string' },
+          links: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: (_args: unknown, value: { title: string; type: string; body: string }) => [{
+        type: 'text',
+        text: `# ${value.title} (${value.type})\n\n${value.body}`,
+      }],
+    },
+    async execute(args: { concept_id: string }) {
+      const id = String(args.concept_id).replace(/\.md$/, '')
+      const concept = await recall(root, id)
+      return {
+        conceptId: concept.conceptId,
+        title: concept.meta?.title || id,
+        type: concept.meta?.type || '',
+        body: concept.body || '',
+        links: concept.links || [],
+      }
+    },
+  }))
+
+  // ── 工具 5:okf_graph(导出记忆图谱 JSON,供可视化前端) ──
+  ctx.tools.register(defineTool({
+    name: 'okf_graph',
+    description:
+      '导出记忆库的图谱 JSON:nodes(概念:title/type/tags/weight/state)+edges(交叉链接)+timeline(权重历史)。' +
+      '供图谱可视化前端渲染,契约稳定。' +
+      'Export the memory graph JSON: nodes (concepts: title/type/tags/weight/state) + edges (cross-links) + timeline (weight history).',
+    parameters: {
+      limit: { type: 'number', description: '可选:节点上限,默认全部' },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: true, properties: { meta: { type: 'object', additionalProperties: true }, nodes: { type: 'array', items: { type: 'object', additionalProperties: true } }, edges: { type: 'array', items: { type: 'object', additionalProperties: true } }, timeline: { type: 'array', items: { type: 'object', additionalProperties: true } } } },
+      render: (_args: unknown, value: GraphData) => [{
+        type: 'text',
+        text: `记忆图谱:${value.nodes?.length || 0} 节点 · ${value.edges?.length || 0} 边 · ${value.timeline?.length || 0} 权重历史`,
+      }],
+    },
+    async execute(args: { limit?: number }) {
+      const g = await buildGraph(root)
+      if (args.limit && args.limit > 0) g.nodes = g.nodes.slice(0, Math.min(args.limit, 500))
+      return { meta: g.meta, nodes: g.nodes, edges: g.edges, timeline: g.timeline }
+    },
+  }))
+
+  // ── 工具 4:okf_forget(撤回记忆) ──
+  ctx.tools.register(defineTool({
+    name: 'okf_forget',
+    description:
+      '从记忆库索引撤回一条概念(默认保留文件,可从 index/log 追溯;可选删除文件)。' +
+      'Withdraw a concept from the memory library index (keeps the file by default, traceable via index/log; optionally deletes the file).',
+    parameters: {
+      concept_id: { type: 'string', required: true, description: '概念 ID' },
+      delete_file: { type: 'boolean', description: 'true 时同时删除文件(默认 false 仅移出索引)' },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: true, properties: { status: { type: 'string' }, conceptId: { type: 'string' }, reason: { type: 'string' } } },
+      render: (_args: unknown, value: ForgetResult) => [{
+        type: 'text',
+        text: value.status === 'forgotten'
+          ? `已撤回记忆 ${value.conceptId}${value.reason ? `(${value.reason})` : ''}`
+          : value.status === 'not_found'
+            ? `记忆 ${value.conceptId} 不存在或已撤回`
+            : `撤回失败:${value.reason || value.status}`,
+      }],
+    },
+    async execute(args: { concept_id: string; delete_file?: boolean }) {
+      const id = String(args.concept_id).replace(/\.md$/, '')
+      try {
+        return await forgetCore(root, id, args.delete_file === true)
+      } catch (e) {
+        return { status: 'error', conceptId: id, reason: String((e as Error).message || e) }
+      }
+    },
+  }))
+
+  // ── 系统提示注入:记忆纪律 + 库摘要 + 召回指引(用正确的 section API) ──
+  addPrompt(ctx, 'okf-memory-discipline', MEMORY_DISCIPLINE, 50)
+  const indexPrompt = await buildIndexPrompt(root)
+  addPrompt(ctx, 'okf-memory-index', indexPrompt, 150)
+  addPrompt(ctx, 'okf-memory-recall-guide', RECALL_GUIDE, 160)
+
+  // ── 预取增强(暂移除) ──
+  // 之前用 ctx.on('agent/request', ...) 做会话预取,但 agent/request 是瀑布事件,
+  // 监听器必须调用 next() 委托;未正确实现会卡死模型请求链,导致
+  // "Cannot read properties of undefined (reading 'provider')"。
+  // 预取是增强功能,先移除保稳定;后续按瀑布事件规范(带 next())重新实现。
+
+  // 卸载时清理:停掉巩固定时器(注册均为 effect-based,自动撤销)
+  const stopConsolidation = startConsolidation(root)
+  return () => {
+    stopConsolidation()
+  }
+}
+

package/src/server/learning.ts

@@ -0,0 +1,219 @@
+/**
+ * learning.ts — 神经自我学习核心:记忆权重元数据、强化反馈回路、巩固与遗忘。
+ * 唤起评分 = relevance × weight × recency_factor(相关度 × 历史权重 × 近因)。
+ * 元数据存 <root>/.meta/weights.json(点目录,不影响 OKF 符合性)。
+ */
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { withLock } from './store.js'
+
+/** 学习参数(起步默认值,可随使用校准) */
+export const PARAMS = {
+  SELECT_DELTA: 1.0,        // 用户选中某候选/概念 → 权重增量
+  SKIP_DELTA: 0.5,          // 用户跳过/否定 → 权重减量
+  HIT_DELTA: 0.1,           // 被唤起且使用 → 小幅增量
+  MIN_WEIGHT: 0.05,         // 权重下限
+  MAX_WEIGHT: 10,           // 权重上限
+  DECAY_DAYS: 30,           // 宽限期:距上次「触摸」(被读 / 入表)未超过 N 天不衰减
+  DECAY_FACTOR: 0.9,        // 每超出宽限期一个 DECAY_DAYS 的衰减系数
+  MAX_DECAY_STEPS: 30,      // 衰减指数上限(防极端天数把权重一步打到地板)
+  ARCHIVE_THRESHOLD: 0.3,   // 权重低于该值 → 归档 inactive(不删除,可复活)
+  ARCHIVE_RECOVER: 0.6,     // 归档后再次被触摸 → 权重至少恢复到该值(防「复活即再归档」抖动)
+  CONSOLIDATE_INTERVAL_MS: 24 * 60 * 60 * 1000, // 巩固周期:24h
+} as const
+
+export interface WeightEntry {
+  weight: number
+  accessCount: number
+  lastAccessed: string | null
+  state: 'active' | 'inactive'
+  /** 概念首次进入权重表的时间(从未被读取时的衰减基线;旧数据可能缺失) */
+  createdAt?: string
+  /** 上次应用衰减时的「距触摸天数」——用于把衰减做成增量式,保证 consolidate 幂等 */
+  lastDecayDays?: number
+}
+
+export interface MemoryMeta {
+  version: number
+  updatedAt: string | null
+  entries: Record<string, WeightEntry>
+}
+
+function metaFile(root: string): string {
+  return path.join(root, '.meta', 'weights.json')
+}
+
+function emptyMeta(): MemoryMeta {
+  return { version: 1, updatedAt: null, entries: {} }
+}
+
+async function ensureMetaDir(root: string): Promise<void> {
+  await fs.mkdir(path.dirname(metaFile(root)), { recursive: true })
+}
+
+/** 加载元数据(不存在则初始化) */
+export async function loadMeta(root: string): Promise<MemoryMeta> {
+  await ensureMetaDir(root)
+  try {
+    const raw = await fs.readFile(metaFile(root), 'utf8')
+    const m = JSON.parse(raw) as MemoryMeta
+    if (!m.entries) m.entries = {}
+    return m
+  } catch {
+    return emptyMeta()
+  }
+}
+
+export async function saveMeta(root: string, meta: MemoryMeta): Promise<void> {
+  meta.updatedAt = new Date().toISOString()
+  await ensureMetaDir(root)
+  await fs.writeFile(metaFile(root), JSON.stringify(meta, null, 2), 'utf8')
+}
+
+function entryOf(meta: MemoryMeta, conceptId: string): WeightEntry {
+  if (!meta.entries[conceptId]) {
+    meta.entries[conceptId] = {
+      weight: 1.0, accessCount: 0, lastAccessed: null, state: 'active',
+      // 记下入表时间作为衰减基线 —— 否则「只被跳过、从未被读」的记忆会因为
+      // lastAccessed=null 而被当成无限陈旧,第一次巩固就瞬间衰减+归档
+      createdAt: new Date().toISOString(),
+    }
+  }
+  return meta.entries[conceptId]
+}
+
+/** 触摸时间基线:读过用 lastAccessed;只入表未读过用 createdAt;两者都缺(旧数据)→ 视为现在(保守,不衰减) */
+function touchedAtMs(e: WeightEntry, now: number): number {
+  const t = e.lastAccessed || e.createdAt
+  if (!t) return now
+  const ms = new Date(t).getTime()
+  return Number.isFinite(ms) ? ms : now
+}
+
+/** 衰减因子:宽限期内为 1;超出后按 (超出天数 / DECAY_DAYS) 做 DECAY_FACTOR 幂衰减 */
+function decayFactor(elapsedDays: number): number {
+  if (elapsedDays <= PARAMS.DECAY_DAYS) return 1
+  const over = (elapsedDays - PARAMS.DECAY_DAYS) / PARAMS.DECAY_DAYS
+  return Math.pow(PARAMS.DECAY_FACTOR, Math.min(over, PARAMS.MAX_DECAY_STEPS))
+}
+
+/** 交互反馈:用户选中(如 TechChoice 候选被拍板);写锁内串行防权重丢失 */
+export async function recordSelect(root: string, conceptId: string, delta: number = PARAMS.SELECT_DELTA): Promise<number> {
+  return withLock(async () => {
+    const meta = await loadMeta(root)
+    const e = entryOf(meta, conceptId)
+    e.weight = Math.min(PARAMS.MAX_WEIGHT, e.weight + delta)
+    e.accessCount += 1
+    e.lastAccessed = new Date().toISOString()
+    // 触摸后衰减基线归零:下次从宽限期重新起算
+    e.lastDecayDays = 0
+    if (e.state === 'inactive') {
+      // 复活:权重至少抬到 ARCHIVE_RECOVER —— 否则 okf_read 只 +0.1,
+      // 复活后仍低于归档线,下次巩固立刻再归档(来回抖动)
+      e.weight = Math.max(e.weight, PARAMS.ARCHIVE_RECOVER)
+      e.state = 'active'
+    }
+    await saveMeta(root, meta)
+    return e.weight
+  })
+}
+
+/** 交互反馈:用户跳过/否定;写锁内串行防权重丢失 */
+export async function recordSkip(root: string, conceptId: string, delta: number = PARAMS.SKIP_DELTA): Promise<number> {
+  return withLock(async () => {
+    const meta = await loadMeta(root)
+    const e = entryOf(meta, conceptId)
+    e.weight = Math.max(PARAMS.MIN_WEIGHT, e.weight - delta)
+    await saveMeta(root, meta)
+    return e.weight
+  })
+}
+
+/** 交互反馈:被唤起且被使用 */
+export async function recordHit(root: string, conceptId: string): Promise<number> {
+  return recordSelect(root, conceptId, PARAMS.HIT_DELTA)
+}
+
+/**
+ * 巩固:增量衰减 + 阈值归档(不删除,可复活);写锁内串行。
+ *
+ * 幂等性:衰减按「本次因子 / 上次已应用的因子」增量施加。两次调用之间 elapsedDays
+ * 不变时比值为 1,所以时间没流逝就不会重复扣血 —— 这正是旧实现的问题:
+ * 它每次都把 factor 乘到已衰减的权重上,连调 N 次就衰减 N 次(24h 定时器 + 每次
+ * 重启/reload 多跑一次即反复扣血)。
+ */
+export async function consolidate(root: string): Promise<MemoryMeta> {
+  return withLock(async () => {
+    const meta = await loadMeta(root)
+    const now = Date.now()
+    let changed = false
+    for (const e of Object.values(meta.entries)) {
+      const elapsedDays = (now - touchedAtMs(e, now)) / 86400000
+      if (elapsedDays > PARAMS.DECAY_DAYS) {
+        const prev = typeof e.lastDecayDays === 'number' ? e.lastDecayDays : PARAMS.DECAY_DAYS
+        const ratio = Math.min(1, decayFactor(elapsedDays) / decayFactor(prev))
+        if (ratio < 1) {
+          e.weight = Math.max(PARAMS.MIN_WEIGHT, e.weight * ratio)
+          changed = true
+        }
+        if (e.lastDecayDays !== elapsedDays) {
+          e.lastDecayDays = elapsedDays
+          changed = true
+        }
+      }
+      if (e.state === 'active' && e.weight < PARAMS.ARCHIVE_THRESHOLD) {
+        e.state = 'inactive'
+        changed = true
+      }
+    }
+    if (changed) await saveMeta(root, meta)
+    return meta
+  })
+}
+
+/**
+ * 启动巩固定时器:每 intervalMs 对记忆库做一次巩固(衰减+归档),返回停止函数。
+ * 定时器 unref(不阻止进程退出);内部吞异常,单次失败不中断进程。
+ */
+export function startConsolidation(root: string, intervalMs: number = PARAMS.CONSOLIDATE_INTERVAL_MS): () => void {
+  const id = setInterval(() => {
+    consolidate(root).catch(() => {})
+  }, intervalMs)
+  if (typeof id.unref === 'function') id.unref()
+  return () => clearInterval(id)
+}
+
+/**
+ * 唤起评分:relevance × weight × recency_factor。
+ */
+export function recallScore(relevance: number, weight: number = 1.0, lastAccessed: string | null = null): number {
+  let recency = 1.0
+  if (lastAccessed) {
+    const days = (Date.now() - new Date(lastAccessed).getTime()) / 86400000
+    recency = Math.max(0.4, 1 / (1 + days / 30))
+  }
+  return relevance * weight * recency
+}
+
+/**
+ * 可排序命中项:只要带 conceptId 与 score 即可。
+ * 不要求索引签名 —— 否则 SearchHit 这类具体接口会被判为不可赋值。
+ */
+export interface RankableHit {
+  conceptId: string
+  score: number
+}
+
+/** 把检索结果与学习权重合并,按唤起评分排序 */
+export async function rank<T extends RankableHit>(root: string, searchHits: T[]): Promise<Array<T & { weight: number; state: string; score: number }>> {
+  const meta = await loadMeta(root)
+  const ranked = searchHits.map((h) => {
+    const e = meta.entries[h.conceptId]
+    const weight = e ? e.weight : 1.0
+    const state = e ? e.state : 'active'
+    const score = recallScore(h.score, weight, e ? e.lastAccessed : null)
+    return { ...h, weight: +weight.toFixed(2), state, score: +score.toFixed(3) }
+  })
+  ranked.sort((a, b) => b.score - a.score)
+  return ranked
+}