pi-okf-memory

简体中文 | English

会话记忆 → OKF 知识沉淀。让 pi 跨会话记住你。

把会话里高价值的内容按 OKF v0.1 规范自动沉淀成长期记忆,下次开新会话自动唤起。每次选择、跳过、纠正都是学习信号 —— 用得越久,召回越准。

English TL;DR — pi-okf-memory distills high-value content from your pi sessions into durable OKF v0.1 Markdown files and recalls it in later sessions. The memory is yours: plain files you can read, git, and edit. Weighted recall sharpens with every pick and skip. Install: pi install npm:pi-okf-memory (or pi install git:github.com/ZHI-QI/pi-okf-memory). One command: /okf. Six tools: okf_remember / okf_search / okf_read / okf_forget / okf_graph / okf_feedback. Full English README →

---

为什么需要它

pi 每次开新会话都从零开始。你反复交代同样的事:

「我用 pnpm 不用 npm」 「经营数据走鼎赞 SaaS 的 MySQL,别翻本地文件」 「上季度定了 React 18 + Vite,别再问我前端用什么」

pi-okf-memory 把这些沉淀成文件。它是你的,不是黑盒:

• 可读 —— 就是 Markdown,直接打开看、git 管、随时手改
• 可迁 —— 一个目录,拷走就是完整记忆
• 不编造 —— 检索不到会明确说「记忆库没有」,不会假装记得

安装

pi install git:github.com/ZHI-QI/pi-okf-memory        # 从 GitHub
pi install /path/to/pi-okf-memory                     # 从本地 checkout
pi -e /path/to/pi-okf-memory/src/pi/index.ts          # 试用,不写配置

零运行时依赖,无需构建步骤 —— pi 用 jiti 直接加载 TypeScript,并通过别名提供 typebox 与 @earendil-works/pi-*。

用法

你不需要学任何命令

装好后,插件会注入一段「记忆纪律」,pi 会自己判断该记什么、该查什么:

你: 记住,我的三家门店是韶山/湘乡/塘厦,共用局域网共享文件夹
    → pi 自行判断价值、去重、写入、建索引

你: 查询经营数据走哪里?
    → pi 先 okf_search 召回,再基于记忆回答(而不是瞎猜或翻文件)

你: 查一下记忆里关于门店的
    → 显式触发检索

6 个工具(pi 自主调用)

工具	作用
okf_remember	写入一条记忆(自动类型校验 → 去重 → 小节级合并 → 落盘)
okf_search	按 相关度 × 权重 × 近因 排序召回;命中 TechChoice 附候选表
okf_read	精读某条全文(含交叉链接),并记一次使用反馈
okf_forget	撤回一条(默认保留文件可追溯,可选删文件)
okf_graph	导出图谱 JSON(nodes / edges / timeline)
okf_feedback	用户选中 +1.0 / 跳过 −0.5,直接调权重

命令:一个 /okf 就够

只注册一个命令,子命令可 Tab 补全(输入 /okf 后按 Tab)。

命令	作用
/okf	记忆库状态:根目录 / 概念数 / 权重榜
/okf search <关键词>	检索(短别名 /okf s)
/okf graph	导出单文件自包含交互式图谱 HTML 并打开(短别名 /okf g)
/okf consolidate	立即跑一次巩固(衰减 + 归档)(短别名 /okf c)
/okf help	列出全部子命令

什么值得记

记 ✅	不记 ❌
新背景事实 / 偏好 / 习惯	寒暄、过程性问答
拍板的决策及理由	单轮临时任务
可复用方法论 / 流程 / 教训	已有记忆的重复表述
你纠正它的时候(最强信号)	未验证的猜测(可归入 Idea 等成熟)
被确认的反直觉结论
技术选型(前端/后端/语言/方案/配置)

工作原理

捕获 ──→ 概念化 ──→ 沉淀 ──→ 唤起
 │        │         │        │
 │        │         │        └─ 相关度 × 权重 × 近因 排序,写回使用反馈
 │        │         └─ type 校验 → 标题去重 → 小节级合并 → index/log 更新
 │        └─ 8 类型词表 + OKF v0.1 frontmatter 校验
 └─ pi 依据「记忆纪律」判断本轮是否产生值得沉淀的新知识

权重学习

召回评分是 relevance × weight × recency。权重随你的行为变化:

行为	权重
用户选中 / 确认采用	+1.0
用户跳过 / 否定	−0.5
被精读使用	+0.1
30 天未触碰	开始衰减(0.9^超出天数/30)
权重 < 0.3	归档(inactive,不删除,可复活)
归档后被重新使用	回到 ≥ 0.6

衰减是增量式的:时间没流逝就不会重复扣血 —— 反复调用巩固与只调用一次结果完全相同。

技术选型三档规则(内置协议)

针对前端/后端/语言/方案/配置这类选型:

1. 命中 2+ 候选 → 全部展示给你选,绝不擅自决定
2. 命中 1 个候选 → 直接使用
3. 你未指定技术但命中维度关键词(如「前端」)→ 按该维度记忆处理
4. 你提出新方案/切换/配置 → 追加式更新,不覆盖旧候选(保留 v1→vN 轨迹)

设计依据:每个机制都追得到记忆研究

权重、衰减、归档、检索强化 —— 这些不是拍脑袋定的,各自对应认知心理学与神经科学里的经典结论。

机制	文献	本项目实际怎么做
遗忘曲线	Ebbinghaus (1885) Über das Gedächtnis	decayFactor():30 天宽限期后按 0.9^((t−30)/30) 幂衰减
记忆可用性追踪「需要概率」	Anderson & Schooler (1991), Psychological Science 2(6):396–408	权重 = 使用频率(选中 +1.0 / 精读 +0.1)+ 近因 1/(1+days/30)
存储强度 ≠ 提取强度	Bjork & Bjork (1992), From Learning Processes to Cognitive Processes	归档只置 state: inactive,文件不删;再用可把权重抬回
提取练习效应(测试效应)	Roediger & Karpicke (2006), Psychological Science 17(3):249–255	okf_read 精读一次即写回权重反馈
激活扩散	Collins & Loftus (1975), Psychological Review 82(6):407–428	/okf graph 命中后沿交叉链接 BFS 传导点亮
半衰期回归	Settles & Meeder (2016), ACL pp.1848–1858	PARAMS 把衰减参数化(DECAY_DAYS/DECAY_FACTOR),可调
长时程增强(LTP)	Bliss & Lømo (1973), J. Physiol. 232(2):331–356	每次使用权重递增,上限 10

边界说明(不吹)

上面是设计类比,不是「本插件实现了神经科学」。差别具体在哪:

• 权重是一张 JSON 表,不是脉冲神经网络 —— 没有神经元、没有突触、没有膜电位
• 交叉链接靠写入时显式传 related,不做共现自动统计 —— 所以不是 Hebbian 自动联想
• 激活扩散只用于可视化,不参与权重计算
• 半衰期是固定参数,没做个性化拟合 —— 而 Settles & Meeder 那篇的核心恰恰是「拟合」

写清楚这些,是因为「参考了哪些研究的结论」和「实现了多少」是两件事。 知道边界在哪,你才能判断它适不适合你的场景。

记忆库结构

默认 ~/.pi/agent/okf-memory/(环境变量 OKF_MEMORY_ROOT 可覆盖):

~/.pi/agent/okf-memory/
├── index.md            ← 渐进式目录(okf_version: "0.1")
├── log.md              ← 变更历史(## YYYY-MM-DD)
├── fact/               ← 背景事实
├── preference/         ← 偏好
├── decision/           ← 决策(三段式:数据/分析/结论)
├── method/             ← 方法论
├── insight/            ← 洞察
├── idea/               ← 未成型灵感
├── lesson/             ← 经验教训
├── techchoice/         ← 技术选型(Options 候选表 + Active)
└── .meta/weights.json  ← 学习权重(点目录,不污染 OKF 符合性)

概念 ID 就是相对路径(如 fact/门店布局),交叉链接用包内绝对路径 [文字](/fact/门店布局.md)。

可视化图谱

/okf graph 生成单文件自包含 HTML(无 CDN、无构建产物),双击即可打开或分享:

• 节点大小 = 权重,颜色 = 类型,虚线描边 = 已归档
• 悬停看详情,滚轮缩放,拖拽平移,可拖动节点
• 搜索命中 → 白边 + 脉冲光环 + ⚡命中,并沿交叉链接 BFS 传导点亮关联记忆

配置

项	方式	默认
记忆库根目录	环境变量 OKF_MEMORY_ROOT	~/.pi/agent/okf-memory/
学习参数	src/server/learning.ts 的 PARAMS	见上「权重学习」

调参入口都集中在 PARAMS:SELECT_DELTA / SKIP_DELTA / HIT_DELTA / DECAY_DAYS / DECAY_FACTOR / ARCHIVE_THRESHOLD / ARCHIVE_RECOVER / CONSOLIDATE_INTERVAL_MS。

同一份核心也驱动 dsh 插件

运行时无关的核心(src/server/*)零宿主耦合 —— 外部依赖只有 node:fs / node:path / node:os,只有 src/server/index.ts 是 dsh 适配层。因此 dsh 插件 dsh-okf-memory 与 pi 扩展 pi-okf-memory 共享同一实现:

	pi(本仓库主场)	dsh
适配层	src/pi/index.ts	src/server/index.ts
默认记忆库	~/.pi/agent/okf-memory/	~/.dsh/memory/
提示注入	pi.on("before_agent_start")	ctx.systemPrompt.section()
图谱	/okf graph 导出 HTML	web 对话视图标签
工具	6	5

OKF_MEMORY_ROOT 两个宿主都认 —— 指向同一目录即可共享记忆库。

开发与测试

pnpm install
pnpm test          # typecheck + build + 6 套件,250 断言,离线确定性
pnpm test:e2e      # 真实模型端到端(需 token),9 断言

层	脚本	证明什么
类型对账	tsc -p tsconfig.typecheck.json	适配层用法符合 pi 真实 .d.ts
核心功能	scripts/smoke.js	store / concept / dedupe / learning / recall / graph
dsh 集成	scripts/integration.js	mock dsh ctx 下 5 工具全链路
pi 集成	scripts/pi-integration.js	mock pi API 下 6 工具 + 4 命令 + schema 校验
pi 真实 RPC	scripts/pi-rpc-commands.js	命令真的被真实 pi 进程识别并执行
真实模型 E2E	scripts/pi-e2e-model.js	模型真的调工具、真的落盘、真的跨会话召回

为什么必须有最后两层:自写 mock 只能证明「代码符合我的假设」,证明不了假设本身。本项目的第一个真实 bug 就是这样漏掉的 —— 模型从不知道要传 related 参数,导致真实使用下图谱恒为零边孤岛,而 mock 测试全绿。

注意:tsdown(rolldown)只剥离类型、不做类型检查,所以 pnpm build 通过 ≠ 类型正确,typecheck 是独立一层。

发布到 npm

发布由 .github/workflows/npm-publish.yml 负责,认证走 Trusted Publishing(OIDC)—— 不需要任何 npm token。

为什么不用 token

npm 在 2026 年收紧了 token 发布:

• 自 2025-11 起不再支持经典 access token,只认 granular token
• granular token 里「绕过 2FA」的那类,自 2026-07-31 起也不能再直接发布 (实测报 403 You may not perform that action with these credentials)

所以 CI 发布的正路是 OIDC:npm 用本次 workflow 的 OIDC 身份换一个短时 token, 无需存储任何长期凭据。workflow 里所需的全部权限就是 id-token: write。

首次使用前:在 npmjs.com 配一次 Trusted Publisher

打开 https://www.npmjs.com/package/pi-okf-memory/access → Trusted Publisher → 选 GitHub Actions,填:

字段	值
Organization or user	ZHI-QI
Repository	pi-okf-memory
Workflow filename	npm-publish.yml(只填文件名,不带路径)
Environment name	留空
Allowed actions	勾上 npm publish

这个配置动作本身需要 2FA,所以只能人工在网页完成一次。 该端点对尚未发布的包名也可用 —— 也就是说可以先配好,再让 CI 发第一个版本。

之后两条发布路径

方式	行为
发一个 GitHub Release	自动发布到 npm(打 latest 标签)
Actions → npm-publish → Run workflow	默认 dry_run = true 只做校验;确认后把开关关掉再跑

workflow 会在发布前依次拦截:

• pnpm test 全绿(typecheck + 构建 + 266 断言;含需要真实 pi 进程的 RPC 测试层)
• npm 版本 < 11.5.1 → 拦(trusted publishing 的硬要求)
• Release tag 与 package.json 版本不一致 → 拦
• 该版本已存在于 npm → 拦(防重复发布)
• 包内容缺少 src/ 或 lib/ → 拦

最后一条是关键守卫:lib/ 在 .gitignore 里,CI 是干净 checkout。 package.json 的 prepublishOnly 会在 npm publish 时自动构建,避免发出残缺包。

本地发布

本地发布需要交互式 2FA,适合首次破壳或 token 路子完全走不通时:

npm login          # 浏览器 / OTP 完成 2FA
npm publish --access public

已有一个 node scripts/release.mjs 脚本(bump 版本 → 构建 → dry-run → 发布),但它走 token 路子, 在当前的 npm 政策下已不可用,仅作参考保留。

License

MIT