pi-okf-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-okf-memory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,204 @@
+# pi-okf-memory
+
+[简体中文](README.md) | English
+
+**Session memory → OKF knowledge. Make pi remember you across sessions.**
+
+High-value content from your sessions is distilled into long-term memory as [OKF v0.1](https://github.com/open-knowledge-format) documents, and recalled automatically in later sessions. Every pick, skip and correction is a learning signal — recall gets sharper the longer you use it.
+
+> **中文速览** —— `pi-okf-memory` 把 pi 会话中的高价值内容沉淀为持久的 [OKF v0.1](https://github.com/open-knowledge-format) Markdown 文件,
+> 并在之后的会话中自动唤起。记忆完全属于你:纯文件,可读、可 `git`、可手改。权重随你的每次选择与跳过持续调整,召回越来越准。
+> **安装:** `pi install npm:pi-okf-memory`(或 `pi install git:github.com/ZHI-QI/pi-okf-memory`)。
+> 一个命令:`/okf`。六个工具:`okf_remember` / `okf_search` / `okf_read` / `okf_forget` / `okf_graph` / `okf_feedback`。
+> [完整中文说明 →](README.md)
+
+![Memory graph · search hit and neural propagation](docs/graph-demo.png)
+
+---
+
+## Why
+
+Every new pi session starts from zero, so you keep repeating yourself:
+
+> "I use pnpm, not npm."
+> "Revenue data comes from the Dezensaas MySQL — don't grep local files."
+> "We settled on React 18 + Vite last quarter; stop asking about the frontend."
+
+`pi-okf-memory` turns that into files. The memory is yours, not a black box:
+
+- **Readable** — plain Markdown. Open it, `git` it, hand-edit it.
+- **Portable** — one directory. Copy it and the whole memory moves with you.
+- **Honest** — when nothing matches, it says "not in the memory library" instead of making something up.
+
+## Install
+
+```sh
+pi install git:github.com/ZHI-QI/pi-okf-memory        # from GitHub
+pi install /path/to/pi-okf-memory                     # from a local checkout
+pi -e /path/to/pi-okf-memory/src/pi/index.ts          # try it without writing config
+```
+
+Zero runtime dependencies and **no build step** — pi loads TypeScript directly via [jiti](https://github.com/unjs/jiti) and provides `typebox` / `@earendil-works/pi-*` through aliases.
+
+## Usage
+
+### You don't need to learn any commands
+
+Once installed, the plugin injects a "memory discipline" prompt and pi decides on its own what to store and what to look up:
+
+```
+You: Remember — my three stores are Shaoshan/Xiangxiang/Tangxia, sharing a LAN folder
+     → pi judges value, dedupes, writes the concept, updates the index
+
+You: Where should revenue queries go?
+     → pi runs okf_search first, then answers from memory instead of guessing
+
+You: Search memory for anything about stores
+     → explicit recall
+```
+
+### 6 tools (called by pi autonomously)
+
+| Tool | Purpose |
+|---|---|
+| `okf_remember` | Write a concept (type validation → dedupe → section-level merge → persist) |
+| `okf_search` | Recall ranked by relevance × weight × recency; `TechChoice` hits include the full options table |
+| `okf_read` | Read a concept in full (with cross-links) and record one usage feedback |
+| `okf_forget` | Withdraw a concept (file kept by default for traceability; optionally delete) |
+| `okf_graph` | Export the graph JSON (nodes / edges / timeline) |
+| `okf_feedback` | User selected `+1.0` / skipped `−0.5` — moves weights directly |
+
+### Commands: just `/okf`
+
+Only **one** command is registered; subcommands complete with Tab (type `/okf ` then Tab).
+
+| Command | Purpose |
+|---|---|
+| `/okf` | Library status: root, concept count, weight leaderboard |
+| `/okf search <query>` | Search (short alias `/okf s`) |
+| `/okf graph` | Export a **single self-contained** interactive HTML graph and open it (alias `/okf g`) |
+| `/okf consolidate` | Run consolidation now, decay + archive (alias `/okf c`) |
+| `/okf help` | List all subcommands |
+
+### What gets remembered
+
+| Worth storing ✅ | Not worth storing ❌ |
+|---|---|
+| New background facts, preferences, habits | Greetings, process chatter |
+| Decisions **and their rationale** | One-off tasks |
+| Reusable methods, processes, lessons | Restating what's already stored |
+| **When you correct pi** (strongest signal) | Unverified guesses (goes to `Idea` until it matures) |
+| Counter-intuitive findings you confirm | |
+| Technology choices (frontend/backend/language/approach/config) | |
+
+## How it works
+
+```
+capture ──→ conceptualize ──→ persist ──→ recall
+  │            │                 │           │
+  │            │                 │           └─ rank by relevance × weight × recency, write back feedback
+  │            │                 └─ validate type → dedupe by title → section-level merge → update index/log
+  │            └─ 8-type vocabulary + OKF v0.1 frontmatter validation
+  └─ pi decides whether this turn produced knowledge worth keeping
+```
+
+### Weighted learning
+
+Recall score is `relevance × weight × recency`, and weight follows your behaviour:
+
+| Behaviour | Weight |
+|---|---|
+| User selects / confirms an option | **+1.0** |
+| User skips / rejects | **−0.5** |
+| Concept read and used | +0.1 |
+| Untouched for 30 days | starts decaying (`0.9^(days over 30 / 30)`) |
+| Weight < 0.3 | archived (`inactive` — **never deleted, revivable**) |
+| Used again after archiving | restored to ≥ 0.6 |
+
+Decay is **incremental**: if no time has passed, nothing is deducted. Running consolidation repeatedly gives exactly the same result as running it once.
+
+### TechChoice three-tier rule (built-in protocol)
+
+For frontend/backend/language/approach/config decisions:
+
+1. **2+ candidates match** → present all of them and let you choose; never decide unilaterally
+2. **1 candidate matches** → use it directly
+3. You didn't name a technology but the message matches a dimension keyword (e.g. "frontend") → handle via that dimension's memory
+4. You propose a new option / switch / config → **append** rather than overwrite (keeps the v1→vN trail)
+
+## Memory library layout
+
+Defaults to `~/.pi/agent/okf-memory/` (override with `OKF_MEMORY_ROOT`):
+
+```
+~/.pi/agent/okf-memory/
+├── index.md            ← progressive index (okf_version: "0.1")
+├── log.md              ← change history (## YYYY-MM-DD)
+├── fact/               ← background facts
+├── preference/         ← preferences
+├── decision/           ← decisions (three-part: data / analysis / conclusion)
+├── method/             ← methodologies
+├── insight/            ← insights
+├── idea/               ← unformed ideas
+├── lesson/             ← lessons learned
+├── techchoice/         ← technology choices (Options table + Active)
+└── .meta/weights.json  ← learning weights (dot dir, keeps OKF conformance clean)
+```
+
+A concept ID *is* its relative path (e.g. `fact/store-layout`), and cross-links use in-bundle absolute paths: `[text](/fact/store-layout.md)`.
+
+## Graph visualization
+
+`/okf graph` produces a **single self-contained** HTML file (no CDN, no build artifacts) you can double-click or share:
+
+- Node size = weight, colour = type, dashed outline = archived
+- Hover for details, scroll to zoom, drag to pan, drag nodes to rearrange
+- A search hit gets a white ring, a pulse, and `⚡hit`, then **BFS-propagates** along cross-links to light up related memories
+
+## Configuration
+
+| Item | How | Default |
+|---|---|---|
+| Memory root | `OKF_MEMORY_ROOT` env var | `~/.pi/agent/okf-memory/` |
+| Learning parameters | `PARAMS` in `src/server/learning.ts` | see "Weighted learning" above |
+
+Tuning knobs live in `PARAMS`: `SELECT_DELTA` / `SKIP_DELTA` / `HIT_DELTA` / `DECAY_DAYS` / `DECAY_FACTOR` / `ARCHIVE_THRESHOLD` / `ARCHIVE_RECOVER` / `CONSOLIDATE_INTERVAL_MS`.
+
+## The same core also drives the dsh plugin
+
+The runtime-agnostic core (`src/server/*`) has zero host coupling — its only imports are `node:fs` / `node:path` / `node:os`, and `src/server/index.ts` is the sole dsh adapter. So the dsh plugin `dsh-okf-memory` and the pi extension `pi-okf-memory` share one implementation:
+
+| | pi (this repo's focus) | dsh |
+|---|---|---|
+| Adapter | `src/pi/index.ts` | `src/server/index.ts` |
+| Default library | `~/.pi/agent/okf-memory/` | `~/.dsh/memory/` |
+| Prompt injection | `pi.on("before_agent_start")` | `ctx.systemPrompt.section()` |
+| Graph | `/okf graph` exports HTML | web conversation-view tab |
+| Tools | 6 | 5 |
+
+Both honour `OKF_MEMORY_ROOT` — point them at the same directory to share one memory library.
+
+## Development & testing
+
+```sh
+pnpm install
+pnpm test          # typecheck + build + 6 suites, 250 assertions, offline & deterministic
+pnpm test:e2e      # real-model end-to-end (needs a token), 9 assertions
+```
+
+| Layer | Script | What it proves |
+|---|---|---|
+| Type check | `tsc -p tsconfig.typecheck.json` | Adapter usage matches pi's **real `.d.ts`** |
+| Core | `scripts/smoke.js` | store / concept / dedupe / learning / recall / graph |
+| dsh integration | `scripts/integration.js` | 5 tools end-to-end under a mocked dsh ctx |
+| pi integration | `scripts/pi-integration.js` | 6 tools + 4 commands + schema validation under a mocked pi API |
+| **pi real RPC** | `scripts/pi-rpc-commands.js` | Commands are recognised and executed by a **real pi process** |
+| **Real-model E2E** | `scripts/pi-e2e-model.js` | The model really calls the tools, really persists, really recalls across sessions |
+
+**Why the last two layers exist**: a hand-written mock only proves "the code matches my assumptions" — not that the assumptions are right. This project's first real bug slipped through exactly there: the model never knew to pass the `related` parameter, so in real use the graph was always a set of edgeless islands while every mock test stayed green.
+
+**Note**: `tsdown` (rolldown) strips types without checking them, so a passing `pnpm build` does *not* mean the types are correct — `typecheck` is a separate layer.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,265 @@
+# pi-okf-memory
+
+[简体中文](README.md) | [English](README.en.md)
+
+**会话记忆 → OKF 知识沉淀。让 pi 跨会话记住你。**
+
+把会话里高价值的内容按 [OKF v0.1](https://github.com/open-knowledge-format) 规范自动沉淀成长期记忆,下次开新会话自动唤起。每次选择、跳过、纠正都是学习信号 —— 用得越久,召回越准。
+
+> **English TL;DR** — `pi-okf-memory` distills high-value content from your pi sessions into
+> durable [OKF v0.1](https://github.com/open-knowledge-format) 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 →](README.en.md)
+
+![记忆图谱 · 搜索命中与神经传导](docs/graph-demo.png)
+
+---
+
+## 为什么需要它
+
+pi 每次开新会话都从零开始。你反复交代同样的事:
+
+> 「我用 pnpm 不用 npm」
+> 「经营数据走鼎赞 SaaS 的 MySQL,别翻本地文件」
+> 「上季度定了 React 18 + Vite,别再问我前端用什么」
+
+`pi-okf-memory` 把这些**沉淀成文件**。它是你的,不是黑盒:
+
+- **可读** —— 就是 Markdown,直接打开看、`git` 管、随时手改
+- **可迁** —— 一个目录,拷走就是完整记忆
+- **不编造** —— 检索不到会明确说「记忆库没有」,不会假装记得
+
+## 安装
+
+```sh
+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](https://github.com/unjs/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 轨迹)
+
+## 记忆库结构
+
+默认 `~/.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` 两个宿主都认 —— 指向同一目录即可共享记忆库。
+
+## 开发与测试
+
+```sh
+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 路子完全走不通时:
+
+```sh
+npm login          # 浏览器 / OTP 完成 2FA
+npm publish --access public
+```
+
+已有一个 `node scripts/release.mjs` 脚本(bump 版本 → 构建 → dry-run → 发布),但它走 token 路子,
+在当前的 npm 政策下**已不可用**,仅作参考保留。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-okf-memory 挂载声明:把自己插入 Loader
+# 注:本仓库是 pi 扩展 pi-okf-memory 的主场,dsh 插件由 dsh-okf-memory 仓库发布;
+# 这里保留双宿主声明是为了让同一份运行时无关核心仍能被 dsh 加载。
+- insert:
+  - id: okf-memory
+    name: pi-okf-memory

package/lib/capture.js

@@ -0,0 +1,53 @@
+//#region src/server/capture.ts
+/**
+* capture.ts — 记忆纪律(系统提示片段)与捕获评估。
+* 神经自我学习驱动:捕获由"预测误差"驱动 —— 用户纠正、首次披露、反直觉结论
+* 都是模型预测失败的信号,内在动机触发写入;取代固定规则表。
+*/
+/** 注入系统提示的"记忆纪律"片段(Agent 自主决定何时调用 okf_remember) */
+const MEMORY_DISCIPLINE = `
+# 记忆纪律(okf-memory)
+
+你有一个 OKF 长期记忆库。记忆不靠自动记录,而靠你判断"本轮是否产生了值得沉淀的新知识"。
+
+## 值得记忆(高价值信号,写!)
+- 用户给出新背景事实 / 偏好 / 习惯(首次披露)
+- 达成的决策及理由(尤其用户明确拍板的事项)
+- 可复用方法论 / 流程 / 经验教训
+- 用户纠正了你的理解(这是最强的"预测误差"信号)
+- 反直觉但被用户确认的结论
+- 技术选型:用户提到前端/后端/语言/方案/配置的选择、切换、配置细节
+
+## 不值得记忆(不写)
+- 寒暄、过程性问答、单轮临时任务
+- 已记忆内容的重复表述(先搜再写,命中则跳过)
+- 未验证的猜测、尚未落地的设想(可归入 Idea 类型等待成熟)
+
+## 写入纪律
+1. 写入前必先 okf_search:命中同标题 → 不新建,更新或跳过;命中相近 → 互补合并或互建交叉链接
+2. 每篇必须:type 非空、title 简洁、description 一句话摘要(检索全靠它)、正文结构化(标题/列表/表格)
+3. type 词表:Fact 背景事实 / Preference 偏好 / Decision 决策 / Method 方法论 / Insight 洞察 / Idea 灵感 / Lesson 教训 / TechChoice 技术选型
+4. 正文模板:Decision/Insight 用 # 数据 → # 分析 → # 结论 三段式;TechChoice 用 # Options 候选表 + # Active 当前使用;其余自由结构化
+5. **交叉链接必须显式传 related 参数**:新建概念时,把 okf_search 命中的相关概念 ID 填进
+   related(如 related: ["fact/门店布局"])。工具会自动双向建立「## 相关」链接。
+   - 正文里手写路径 **不会** 生成图谱边 —— 图谱的边只来自 related 写入的链接。
+   - 一次会话里新建多条互相相关的概念时,后建的必须把先建的 ID 放进 related。
+   - 若 okf_remember 返回 status="linked",说明命中相近概念,用返回的 similarTo 作 related 重新提交(不要重复写正文)。
+
+## 技术选型三档规则(用户既定协议,硬性执行)
+1. 命中 2+ 候选 → 全部展示给用户选择(带说明/配置/状态),绝不擅自决定
+2. 命中 1 个候选 → 直接使用
+3. 用户未指定技术,但消息命中维度关键词(如"前端")→ 按该维度记忆处理
+4. 用户说出新技术/切换/配置 → okf_remember 追加式更新,不覆盖旧候选
+5. 用户拍板后,记录选择反馈(权重自动更新,下次排序靠前)
+
+## 唤起纪律
+- 会话开场先 okf_search 预取相关记忆,再开始干活
+- 检索不到 → 明确告知"记忆库没有",不要编造
+`.trim();
+/** 预取提示:会话启动时建议先搜什么(低优先级,供摘要注入用) */
+const RECALL_GUIDE = `
+记忆库概念清单见本片段顶部(okf-memory index)。需要细节时用 okf_read <concept_id>。
+`.trim();
+//#endregion
+export { MEMORY_DISCIPLINE, RECALL_GUIDE };