pi-okf-memory 0.1.0

package/src/server/memory.ts

@@ -0,0 +1,157 @@
+/**
+ * memory.ts — 运行时无关的记忆写入/撤回核心逻辑。
+ *
+ * 从 index.ts 抽出,供多运行时适配层共用:
+ *  - dsh 适配层(src/server/index.ts)用它注册 okf_remember / okf_forget
+ *  - pi 适配层(src/pi/index.ts)用它注册同名工具
+ * 本模块零 dsh / 零 pi 依赖,只有 node:fs 与包内核模块。
+ */
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import {
+  writeConcept, readConcept, refreshIndex, appendLog, filePathOf, withLock, type WriteResult,
+} from './store.js'
+import { findSimilarByTitle } from './dedupe.js'
+import { loadMeta, saveMeta } from './learning.js'
+import { normalizeType, mergeConceptBodies, type ConceptMeta } from './concept.js'
+
+export interface RememberArgs {
+  title: string
+  type: string
+  tags?: string[]
+  related?: string[]
+}
+
+export interface RememberOpts {
+  force?: boolean
+  description?: string
+  source?: string
+}
+
+export interface RememberResult {
+  status: string
+  conceptId: string | null
+  filePath?: string
+  reason?: string
+  similarTo?: string
+}
+
+/**
+ * remember 核心(服务与工具共用):类型校验 → 去重 → 小节级合并/新建 → 反馈。
+ * 全程持写锁,保证"判断→写入"原子,避免并发下同标题概念被重复创建。
+ */
+export async function rememberCore(root: string, meta: RememberArgs, body: string, opts: RememberOpts = {}): Promise<RememberResult> {
+  return withLock(async () => {
+    const { title, type, tags, related } = meta
+    if (!title || !body) throw new Error('title/content 必填')
+    // P0-4:类型归一化 + 词表校验(非法类型不得新建污染目录)
+    const normType = normalizeType(type)
+
+    // 去重
+    const similar = await findSimilarByTitle(root, title, normType)
+    if (similar.length > 0) {
+      const top = similar[0]
+      if (top.similarity >= 1) {
+        // 标题完全相同 → 更新(小节级合并)或跳过
+        const existing = await readConcept(root, top.conceptId)
+        const existingLen = String(existing.body || '').trim().length
+        const newLen = String(body || '').trim().length
+        if (newLen > existingLen * 0.7 && opts.force !== false) {
+          // P0-5:按 # 小节合并:同小节覆盖、新小节追加,不再无限 "## 补充(日期)"
+          const mergedBody = mergeConceptBodies(existing.body || '', body)
+          const res = await writeConcept(root, {
+            ...existing.meta, title, type: normType, tags: tags || existing.meta?.tags, timestamp: new Date().toISOString(),
+          } as ConceptMeta, mergedBody)
+          return { status: 'updated', conceptId: res.conceptId, filePath: res.filePath, reason: '标题相同,按小节合并更新' }
+        }
+        return { status: 'skipped', conceptId: top.conceptId, reason: `标题相同的概念已存在(${existingLen}字),新内容(${newLen}字)未显著增加` }
+      }
+      // 相近 → 建议互补
+      return {
+        status: 'linked',
+        conceptId: top.conceptId,
+        reason: `存在相近概念[${top.title}](${top.conceptId}),已返回其 ID;建议新建后与该概念互建交叉链接,而非复制内容`,
+        similarTo: top.conceptId,
+      }
+    }
+
+    // 新建
+    const res = await writeConcept(root, {
+      type: normType,
+      title,
+      description: opts.description || String(body).split('\n').find((l) => l.trim().startsWith('>'))?.replace(/^>\s*/, '').trim() || firstLine(body),
+      tags: tags || [],
+      timestamp: new Date().toISOString(),
+      source: opts.source || 'session',
+    }, body)
+    // 互建交叉链接(related)
+    if (Array.isArray(related) && related.length > 0) {
+      for (const rid of related) {
+        try {
+          const r = await readConcept(root, String(rid).replace(/\.md$/, ''))
+          const linkLine = `\n\n## 相关\n\n- [${title}](/${res.conceptId}.md)`
+          if (!(r.body || '').includes(res.conceptId)) {
+            await writeConcept(root, { ...r.meta, timestamp: new Date().toISOString() } as ConceptMeta, `${r.body?.trim() || ''}${linkLine}`)
+          }
+        } catch { /* 相关概念不存在则忽略 */ }
+      }
+    }
+    return { status: 'created', conceptId: res.conceptId, filePath: res.filePath, reason: '新建' }
+  })
+}
+
+export interface ForgetResult {
+  status: string
+  conceptId: string
+  reason?: string
+}
+
+/**
+ * forget 核心:概念不存在返回 not_found;默认移到 .meta/forgotten/(保留目录结构防同名冲突),
+ * delete_file=true 时直接删除文件。全程持写锁。
+ */
+export async function forgetCore(root: string, id: string, deleteFile: boolean): Promise<ForgetResult> {
+  return withLock(async () => {
+    const filePath = filePathOf(root, id)
+    let exists = true
+    try {
+      await fs.access(filePath)
+    } catch {
+      exists = false
+    }
+    if (!exists) {
+      return { status: 'not_found', conceptId: id, reason: '概念不存在(可能已撤回)' }
+    }
+    if (deleteFile) {
+      await fs.rm(filePath, { force: true })
+    } else {
+      // 保留相对目录结构,避免同 slug 概念在 forgotten 里撞文件
+      const forgottenDir = path.join(root, '.meta', 'forgotten')
+      const dest = path.join(forgottenDir, path.relative(root, filePath))
+      await fs.mkdir(path.dirname(dest), { recursive: true })
+      await fs.rename(filePath, dest)
+    }
+    await refreshIndex(root)
+    await appendLog(root, {
+      action: deleteFile ? 'forgotten(deleted)' : 'forgotten',
+      conceptId: id,
+      type: '—',
+      title: deleteFile ? '已删除文件' : '已移至 .meta/forgotten/',
+    })
+    // 学习元数据:标记 inactive(可复活)
+    const meta = await loadMeta(root)
+    if (meta.entries[id]) {
+      meta.entries[id].state = 'inactive'
+      await saveMeta(root, meta)
+    }
+    return { status: 'forgotten', conceptId: id, reason: deleteFile ? '已删除文件' : '已移至 .meta/forgotten/' }
+  })
+}
+
+/** 取正文首个非标题行,作为缺省 description */
+export function firstLine(s: string): string {
+  const line = String(s || '').split('\n').map((l) => l.trim()).find((l) => l && !l.startsWith('#'))
+  return line ? line.slice(0, 120) : ''
+}
+
+export type { WriteResult }

package/src/server/recall.ts

@@ -0,0 +1,58 @@
+/**
+ * recall.ts — 预测性唤起:摘要层粗筛 → 细节层校验 → 反馈回路。
+ * 对应"预测加工":先预测需要什么记忆,再检索验证,命中质量写回权重。
+ */
+import { search, type SearchOptions, type SearchHit } from './dedupe.js'
+import { readConcept, type ConceptRef } from './store.js'
+import { rank, recordHit } from './learning.js'
+
+export interface PreloadOptions extends SearchOptions {
+  limit?: number
+}
+
+export interface PreloadHit {
+  conceptId: string
+  title: string
+  description: string
+  type: string
+  tags: string[]
+  weight: number
+  state: string
+  score: number
+}
+
+/**
+ * 预测性预取:给定查询,返回按唤起评分排序的记忆摘要。
+ */
+export async function preload(root: string, query: string, opts: PreloadOptions = {}): Promise<PreloadHit[]> {
+  const raw = await search(root, query, { ...opts, limit: (opts.limit || 8) * 3 })
+  const ranked = await rank(root, raw)
+  return ranked.slice(0, opts.limit || 8).map(({ conceptId, title, description, type, tags, weight, state, score }) => ({
+    conceptId, title, description, type, tags, weight, state, score,
+  }))
+}
+
+export interface ConceptLink {
+  text: string
+  conceptId: string
+}
+
+export interface RecalledConcept extends ConceptRef {
+  links: ConceptLink[]
+}
+
+/**
+ * 精读:读全文 + 提取交叉链接,并记录命中反馈。
+ */
+export async function recall(root: string, conceptId: string): Promise<RecalledConcept> {
+  const concept = await readConcept(root, conceptId)
+  // 提取交叉链接 [text](/path/to/x.md)
+  const links: ConceptLink[] = []
+  const re = /\[([^\]]+)\]\(\/([^)]+\.md)\)/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(concept.body || '')) !== null) {
+    links.push({ text: m[1], conceptId: m[2].replace(/\.md$/, '') })
+  }
+  await recordHit(root, conceptId)
+  return { ...concept, links }
+}

package/src/server/store.ts

@@ -0,0 +1,255 @@
+/**
+ * store.ts — OKF bundle 存储:根目录初始化、概念落盘、index.md 渐进式目录、log.md 变更历史。
+ * 路径即概念 ID:<root>/<type小写>/<kebab-id>.md
+ */
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { parseFrontmatter, validateConcept, slugify, type ConceptMeta } from './concept.js'
+
+/**
+ * 进程内写锁(可重入):串行化对 bundle 文件(index.md/log.md/概念/weights.json)的读-改-写,
+ * 避免多会话并发写入时丢失更新。Cordis 单进程内生效,跨进程不保证。
+ */
+let writeQueue: Promise<void> = Promise.resolve()
+let lockDepth = 0
+export function withLock<T>(fn: () => Promise<T>): Promise<T> {
+  // 已在锁内(可重入):直接执行,避免嵌套自锁死锁
+  if (lockDepth > 0) return Promise.resolve().then(fn)
+  const run = writeQueue.then(async () => {
+    lockDepth = 1
+    try {
+      return await fn()
+    } finally {
+      lockDepth = 0
+    }
+  })
+  writeQueue = run.then(() => {}, () => {})
+  return run
+}
+
+/** 默认记忆库根目录(可被 OKF_MEMORY_ROOT 环境变量覆盖) */
+export function defaultRoot(): string {
+  return process.env.OKF_MEMORY_ROOT || path.join(os.homedir(), '.dsh', 'memory')
+}
+
+/** 概念文件路径 → 概念 ID(相对根,去扩展名,正斜杠归一) */
+export function conceptIdOf(filePath: string, root: string): string {
+  const rel = path.relative(root, filePath).replace(/\\/g, '/').replace(/\.md$/, '')
+  return rel
+}
+
+/** 概念 ID → 文件路径(含安全校验:防路径穿越) */
+export function filePathOf(root: string, conceptId: string): string {
+  const norm = String(conceptId || '').replace(/\\/g, '/').replace(/^\/+/, '')
+  const resolved = path.resolve(root, ...norm.split('/'))
+  const rootResolved = path.resolve(root)
+  if (!resolved.startsWith(rootResolved + path.sep) && resolved !== rootResolved) {
+    throw new Error(`非法 concept_id(路径穿越):${conceptId}`)
+  }
+  return resolved.endsWith('.md') ? resolved : `${resolved}.md`
+}
+
+/** 确保记忆库骨架存在(根 index.md + log.md) */
+export async function ensureRoot(root: string): Promise<void> {
+  await fs.mkdir(root, { recursive: true })
+  const indexPath = path.join(root, 'index.md')
+  const logPath = path.join(root, 'log.md')
+  try {
+    await fs.access(indexPath)
+  } catch {
+    await fs.writeFile(
+      indexPath,
+      [
+        '---',
+        'type: Bundle Root',
+        'title: OKF 记忆库',
+        'description: 会话记忆沉淀库(OKF v0.1)',
+        'okf_version: "0.1"',
+        '---',
+        '',
+        '# OKF 记忆库',
+        '',
+        '由 okf-memory 插件维护。概念按类型分目录,路径即概念 ID。',
+        '',
+      ].join('\n'),
+      'utf8',
+    )
+  }
+  try {
+    await fs.access(logPath)
+  } catch {
+    await fs.writeFile(
+      logPath,
+      '---\ntype: Log\ntitle: 变更历史\n---\n\n# 变更历史\n\n',
+      'utf8',
+    )
+  }
+}
+
+export interface ConceptRef {
+  filePath: string
+  conceptId: string
+  meta: ConceptMeta | null
+  body: string
+  text: string
+}
+
+/** 读取并解析概念文档(校验概念 ID 安全) */
+export async function readConcept(root: string, conceptId: string): Promise<ConceptRef> {
+  const filePath = filePathOf(root, conceptId)
+  const text = await fs.readFile(filePath, 'utf8')
+  const { meta, body } = parseFrontmatter(text)
+  return { filePath, conceptId: conceptIdOf(filePath, root), meta, body, text }
+}
+
+export interface WriteResult {
+  action: 'created' | 'updated'
+  conceptId: string
+  filePath: string
+}
+
+/** 写概念文档(先做符合性校验,再落盘,更新 index/log) */
+export async function writeConcept(root: string, meta: ConceptMeta, body: string): Promise<WriteResult> {
+  return withLock(async () => {
+    const { buildConcept } = await import('./concept.js')
+    const md = buildConcept(meta, body)
+    const check = validateConcept(md)
+    if (!check.ok) throw new Error(`OKF 符合性校验失败:${check.errors.join('; ')}`)
+
+    // type 目录用 slug 化命名:防路径穿越(如 type="../../x")与非法字符
+    const typeDir = slugify(meta.type) || 'other'
+    const dir = path.join(root, typeDir)
+    await fs.mkdir(dir, { recursive: true })
+
+    const base = slugify(meta.title || meta.type || 'untitled')
+    const filePath = path.join(dir, `${base}.md`)
+
+    // 同路径已有内容 → 更新(timestamp 刷新),否则新建
+    let action: 'created' | 'updated' = 'created'
+    try {
+      await fs.access(filePath)
+      action = 'updated'
+    } catch {
+      /* new */
+    }
+    await fs.writeFile(filePath, md, 'utf8')
+    const conceptId = conceptIdOf(filePath, root)
+    await refreshIndex(root)
+    await appendLog(root, { action, conceptId, type: meta.type, title: meta.title })
+    return { action, conceptId, filePath }
+  })
+}
+
+export interface BundleEntry {
+  filePath: string
+  conceptId: string
+  typeDir: string
+}
+
+/** 全库扫描:返回所有概念文档清单(用于 index 重建与检索) */
+export async function scanBundle(root: string): Promise<BundleEntry[]> {
+  const out: BundleEntry[] = []
+  let entries: import('node:fs').Dirent[]
+  try {
+    entries = await fs.readdir(root, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue
+    if (e.name.startsWith('.')) continue
+    const dir = path.join(root, e.name)
+    let files: string[]
+    try {
+      files = await fs.readdir(dir)
+    } catch {
+      continue
+    }
+    for (const f of files) {
+      if (!f.endsWith('.md')) continue
+      const filePath = path.join(dir, f)
+      const conceptId = conceptIdOf(filePath, root)
+      out.push({ filePath, conceptId, typeDir: e.name })
+    }
+  }
+  return out
+}
+
+/** 重建根 index.md(渐进式目录:按类型分组列概念,每行附 description 供模型感知"库里有啥";写锁内串行) */
+export async function refreshIndex(root: string): Promise<void> {
+  return withLock(async () => {
+    const concepts = await scanBundle(root)
+    // 并行读每个概念 frontmatter,取 title/description 供 index 展示
+    // 显式标注返回类型:否则失败分支的 {} 会让 metas[i].description 报类型错
+    const metas = await Promise.all(concepts.map(async (c): Promise<Partial<ConceptMeta>> => {
+      try {
+        const text = await fs.readFile(c.filePath, 'utf8')
+        const { meta } = parseFrontmatter(text)
+        return meta || {}
+      } catch {
+        return {}
+      }
+    }))
+    const byType = new Map<string, Array<{ id: string; desc: string }>>()
+    for (let i = 0; i < concepts.length; i++) {
+      const c = concepts[i]
+      if (!byType.has(c.typeDir)) byType.set(c.typeDir, [])
+      const desc = String(metas[i].description || '').trim().replace(/\s+/g, ' ').slice(0, 60)
+      byType.get(c.typeDir)!.push({ id: c.conceptId, desc })
+    }
+    const lines = [
+      '---',
+      'type: Bundle Root',
+      'title: OKF 记忆库',
+      'description: 会话记忆沉淀库(OKF v0.1)',
+      'okf_version: "0.1"',
+      '---',
+      '',
+      '# OKF 记忆库',
+      '',
+      `共 ${concepts.length} 个概念。路径即概念 ID,交叉链接用包内绝对路径。`,
+      '',
+    ]
+    for (const [typeDir, items] of [...byType.entries()].sort()) {
+      lines.push(`## ${typeDir}`, '')
+      for (const item of [...items].sort((a, b) => a.id.localeCompare(b.id))) {
+        lines.push(item.desc ? `- [${item.id}](/${item.id}.md) — ${item.desc}` : `- [${item.id}](/${item.id}.md)`)
+      }
+      lines.push('')
+    }
+    if (byType.size === 0) lines.push('(空库 — 在会话中说"记住这个",即可沉淀第一条记忆)', '')
+    await fs.writeFile(path.join(root, 'index.md'), lines.join('\n'), 'utf8')
+  })
+}
+
+export interface LogEntry {
+  action: string
+  conceptId: string
+  type: string
+  title?: string
+}
+
+/** 追加 log.md 变更记录(## YYYY-MM-DD 分组;写锁内串行) */
+export async function appendLog(root: string, entry: LogEntry): Promise<void> {
+  return withLock(async () => {
+    const logPath = path.join(root, 'log.md')
+    const now = new Date()
+    const date = now.toISOString().slice(0, 10)
+    const time = now.toISOString().slice(11, 19)
+    let text = ''
+    try {
+      text = await fs.readFile(logPath, 'utf8')
+    } catch {
+      text = '---\ntype: Log\ntitle: 变更历史\n---\n\n# 变更历史\n\n'
+    }
+    const marker = `## ${date}`
+    const line = `- ${time} — ${entry.action} [${entry.conceptId}](${entry.conceptId}.md) (${entry.type}${entry.title ? ` · ${entry.title}` : ''})`
+    if (text.includes(marker)) {
+      text = `${text.replace(/\s*$/, '')}\n${line}\n`
+    } else {
+      text = `${text.replace(/\s*$/, '')}\n${marker}\n\n${line}\n`
+    }
+    await fs.writeFile(logPath, text, 'utf8')
+  })
+}