dsh-cortex-memory 0.1.0 → 0.2.0-rc.13

package/docs/install-windows.md

@@ -1,56 +1,144 @@
-# Windows install
+# Windows 安装与回滚
 
-## Requirements
+> 目标：和本鲸一样的 Windows DSH 用户，能从 tgz 直接安装，不需要编译、不需要原生依赖。
+> 前提：**Node >= 24**（`node:sqlite` 内置）、DSH `>=0.2.1-rc.2 <0.4.0`、Windows 10/11。
 
-- Windows 10/11
-- Node.js **>= 24** (DSH ships a compatible runtime on current builds)
-- DSH `>=0.2.1-rc.2 <0.4.0`
+## 1. 先备份
 
-## Install from a release tgz
+```powershell
+$stamp = Get-Date -Format 'yyyyMMdd-HHmm'
+Copy-Item -Recurse "$env:USERPROFILE\.dsh\profiles\desktop" "$env:USERPROFILE\Desktop\dsh-profile-backup-$stamp"
+```
+
+`dsh-cortex` 默认数据在 `~/.dsh/cortex`，**不读写 shiori 的 `D:\shiori-data`**。第一次安装没有旧数据，不需要迁移。
+
+## 2. 生成/取得 tgz
+
+在 `plugins/dsh-cortex`：
+
+```powershell
+npm pack
+# 产出 dsh-cortex-0.2.0-dev.1.tgz
+```
+
+如果用本鲸打好的包，直接用 `dist/dsh-cortex-0.2.0-dev.1.tgz`。包是纯 JS + SQL，无 `node_modules` 依赖。
+
+## 3. 安装到 desktop profile
 
 ```powershell
-dsh plugin --profile desktop add "C:\path\to\dsh-cortex-memory-0.1.0.tgz"
+dsh plugin --profile desktop add "C:\完整路径\dsh-cortex-0.2.0-dev.1.tgz"
 ```
 
-If `dsh` is not on PATH, install through **DSH → Settings → Plugins → Install**
-and select the same tgz.
+路径必须是**绝对路径**。装完重启 DSH。不要用 `link:` 去指向一个会被清理的目录。
 
-## Verify
+## 4. 验收
+
+重启后：
+
+1. 模型工具列表出现 21 个 `cortex_*`（至少 `cortex_write` / `cortex_search` / `cortex_as_of` / `cortex_playbook` / `cortex_consolidate`）。
+2. 侧栏/插件面板能看到 Cortex。
+3. 写一条测试记忆：
+
+```text
+cortex_write({ text: "安装验收：主人喜欢白饭。", explicit: true })
+cortex_search({ query: "白饭" })
+cortex_self({})
+cortex_guard({ action: "check" })
+```
+
+4. API（默认只回环）：
 
 ```powershell
-dsh plugin --profile desktop list
+curl.exe http://127.0.0.1:7430/api/cortex/health
 ```
 
-Expected: the `cortex` entry is enabled and active. Then open the Cortex panel
-and run **Guardian → check**.
+期望 `{"ok":true,...}` 且没有 shiori 数据被写。
 
-## Data
+## 5. 可选：开 LLM 巩固
 
-Default data root:
+默认 `features.llm=false`，巩固会记录 `skipped` 且零改动。可以在面板「设置 → 权限」点按钮，确认后写入：
 
 ```text
-%USERPROFILE%\.dsh\cortex
+<dataRoot>/feature-overrides.json
 ```
 
-It is separate from any other memory plugin's data. Do not point two memory
-plugins at the same SQLite file.
+**重启 DSH 后生效**；同一页可以回滚上一次权限修改，审计记录在本地 `audit` 表。
+也可以用配置：
+
+```yaml
+- id: cortex
+  name: dsh-cortex
+  config:
+    features:
+      llm: true
+      consolidateOnSleep: true
+```
 
-## Upgrade
+开之前先确认当前 DSH 的模型路由可用。失败会跳过，不阻塞睡眠。
+
+## 6. 回滚
 
 ```powershell
-dsh plugin --profile desktop add "C:\path\to\dsh-cortex-memory-0.2.0.tgz"
+dsh plugin --profile desktop remove dsh-cortex
 ```
 
-Back up the data root before major upgrades:
+重启。`~/.dsh/cortex` 不会被自动删除；确认不要后再手动处理。要恢复 profile，拷回第 1 步的备份。
+
+### 卸载后清理手写 patch
+
+如果你在 `cordis.patch.yml` 里手写过 cortex 配置，`dsh plugin remove` **不会删这段**。残留块通常不影响 `--dump-config`，但会让 diff 变脏，重装时也可能踩到“entry not found”。
+
+可以用脚本：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\examples\uninstall-cortex.ps1 `
+  -Dsh "D:\path\to\dsh.cmd" -Profile <profile>
+```
+
+脚本只删 `- id: cortex` 段，保留其他 patch，并跑一次 `--dump-config`；不删 dataRoot。已手动移除时也会跳过 remove、继续清 patch。
+
+卸载后检查：
 
 ```powershell
-Copy-Item "$env:USERPROFILE\.dsh\cortex" "$env:USERPROFILE\Desktop\cortex-backup" -Recurse
+notepad "$HOME\.dsh\profiles\<profile>\cordis.patch.yml"
+```
+
+删除整段：
+
+```yaml
+- id: cortex
+  name: dsh-cortex
+  config:
+    ...
 ```
 
-## Rollback
+保留其他条目；如果文件只剩注释，写回：
+
+```yaml
+[]
+```
+
+然后再跑一次：
+
+```powershell
+dsh --profile <profile> --dump-config > $null
+```
+
+不要为了清理 patch 去删整个 profile 目录；dataRoot 可能不在 profile 内。
+
+## 7. 常见问题
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 装完没有工具 | 插件条目没 active / 重启没做 | 看 profile 的 bundles，重启 DSH |
+| `node:sqlite` 报错 | Node < 24 或运行时不带 SQLite | 升级 DSH/Node 到 24+ |
+| 工具名冲突 | 另一个插件也注册同名工具 | 先停用旧插件，或改名后再装 |
+| 数据目录不对 | 改过 `dataRoot` | 用绝对路径，不要指向 profile 内部 |
+| 面板 403 | 非回环 Host / 跨源 | 用 `127.0.0.1`，同源打开 |
 
-1. Disable the `cortex` entry in the DSH plugin manager.
-2. Re-enable the previous plugin entry if needed.
-3. Restore the profile configuration and data backup.
+## 8. 兼容性说明
 
-The plugin never modifies another plugin's data.
+- 这是 **bundle 插件**：`dsh.bundle.patch` 指向 `cordis.patch.yml`，装完自动注册 Host 行。
+- 零运行时 npm 依赖；SQLite 用 Node 内置。
+- Windows 路径手写 `C:\...` 即可；包内没有 shell 脚本。
+- 不修改全局 patch，不覆盖系统提示，不碰 shiori。

package/docs/models.md

@@ -1,48 +1,183 @@
-# Optional models
+# 可选模型：embedder / rerank
 
-## Default: hash
+> 结论先说：**安装包不自动下载模型，也不默认联网。**
+> 大模型动辄几百 MB，自动下载会把“装插件”变成“装模型”，还可能带来磁盘、网络、校验和更新问题。
+> 本插件只提供可插拔接口；用户显式配置后才使用。
 
-No model, no network. Uses a local lexical hash embedder.
+## 0. 当前接线状态（2026-11-11）
 
-## Local: Ollama bge-m3
+- HTTP rerank：**已接到 QA**（`cortex_qa`），默认关，失败开放。
+- HTTP embedder：**接口已实现**（`createOpenAIEmbedder`）；**异步索引入口** `POST /vector/index` / `POST /vector/rebuild` 已可用，写不会被网络阻塞；**异步混合检索** `GET /search?async=true` 与 QA 已走 `searchAsync`（远程向量可参与）；默认同步 `/search` 仍不等待网络。
+- 安装包**不自动下载**任何模型。
 
-```powershell
-ollama pull bge-m3
+## 1. 默认路径（零依赖）
+
+- `features.vector = false`：不用向量，FTS5 + 图 + recent 融合。
+- `features.vector = true`：使用内置 `hash-256` embedder（词法哈希，**不是语义模型**）。
+- 不下载任何文件；不需要 `node_modules`；Windows 直接可用。
+
+## 2. 可选 HTTP embedder
+
+代码：`src/vector/providers.js` 的 `createOpenAIEmbedder`。
+
+接口是 OpenAI-compatible `/embeddings`：
+
+```http
+POST {baseUrl}/embeddings
+Authorization: Bearer <apiKey>
+{"model":"bge-m3","input":["文本"]}
 ```
 
-Settings:
+返回：
 
-```text
-mode: local
-baseUrl: http://127.0.0.1:11434/v1
-model: bge-m3
-dim: 1024
-key: (blank)
+```json
+{"data":[{"embedding":[0.1,0.2]}]}
 ```
 
-`bge-m3` supports Chinese and multilingual text. A smaller fallback is
-`nomic-embed-text` (768 dimensions), but it is weaker on Chinese.
+它不会在安装时运行。要接本地服务（如 Xinference / Ollama 的 OpenAI 兼容层 / vLLM），由用户自己启动服务并提供 `baseUrl`。
+**不要把 API key 写进仓库或安装包。**
+
+## 2.1 本地 bge 可选配置（默认关）
+
+本机实测用 Ollama 的 `bge-m3`（1024 维）通过 OpenAI 兼容 `/v1/embeddings` 接入。
 
-## Remote: OpenAI-compatible `/embeddings`
+### profile 配置
+
+```yaml
+- id: cortex
+  name: dsh-cortex
+  config:
+    features:
+      vector: true
+    # dataRoot / dbFile 按你的 profile 配
+```
+
+### 模型配置
+
+在 cortex 的 dataRoot 下放 `model-config.json`（可在面板模型设置里保存，效果相同）：
+
+```json
+{
+  "embedding": {
+    "mode": "local",
+    "baseUrl": "http://127.0.0.1:11434/v1",
+    "model": "bge-m3",
+    "dim": 1024,
+    "apiKey": ""
+  },
+  "rerank": {
+    "enabled": false,
+    "baseUrl": "",
+    "model": "",
+    "apiKey": ""
+  }
+}
+```
+
+- `mode: local` 表示本地 keyless 服务；不要把云端 key 写进仓库。
+- 不配模型时，`features.vector=true` 只会用内置 `hash-256` 词法哈希，**不是语义模型**。
+- 向量索引是暴力扫描，适合个人千条级记忆；不是十亿级 ANN。
+
+### 实测代价（2026-11-11，300 traces / 50 paraphrase queries）
 
 ```text
-mode: remote
-baseUrl: https://your-provider.example/v1
-model: your-embedding-model
-dim: provider dimension
-key: required
+FTS:  hit 0.96 / MRR 0.694 / nDCG 0.603 / p50 4.5-4.8ms
+bge:  hit 1.00 / MRR 0.960 / nDCG 0.883 / p50 51-63ms
+```
+
+- 语义召回明显提升，但查询延迟约 10 倍。
+- 这是合成 paraphrase，不是 LoCoMo；不能当公开 SOTA。
+- 默认仍关闭；没有本地模型/服务就不要开。
+
+## 2.2 可选 ANN（默认关）
+
+```yaml
+features:
+  vector: true
+  vectorAnn: true
+vectorAnnMin: 20000
+vectorAnnEngine: hnsw
+```
+
+- 复用 `src/vector/ann.js` 的单层 NSW 索引；纯 JS，无原生依赖。
+- 小于 `vectorAnnMin` 时仍走暴力精确扫描。
+- ANN 命中不足 5 条时自动回退暴力扫描，避免 scope/过滤把结果卡空。
+- 首次搜索从 embeddings 懒构建；写入/删除会同步索引。
+- 默认 `vectorAnn: false`；不开启时行为不变。
+- 当前验证是单元/小规模，不是 100k ANN 压测；大库收益和召回还需单独 benchmark。
+- 5000 条 A/B 结论（dim 64）：ANN ef=120 recall@10 0.29，ef=400 0.70（p50 0.99ms，暴力 1.11ms），ef=800 0.93（p50 2.73ms，暴力 1.16ms），ef=1600 0.998（p50 11ms）。**小库暴力反而更快**，所以默认阈值放在 20000，且 ANN 默认关。
+- 20k / 100k 复验（ef=800/1600）：20k recall 0.591（ANN p50 5.4ms，暴力 9.2ms）；100k recall 0.413（ANN p50 10.9ms，暴力 38.9ms，构建约 101s）。
+- HNSW 候选（`src/vector/hnsw.js`，二叉堆版）在 5k/20k 的质量：
+  - 5k：recall 0.997，build 5.5s，p50 2.24ms（暴力 1.15ms）
+  - 20k：recall 0.956，build 58.4s，p50 4.88ms（暴力 5.78ms）
+- 所以 `vectorAnnEngine: hnsw` 已接到可选路径，但 **`vectorAnn` 仍默认关**；HNSW 冷构建慢，20k 以下没明显查询优势。
+- 旧 NSW 保留为 `vectorAnnEngine: nsw` 的兼容选项，不再是默认引擎。
+- 100k 构建/内存尚未验证；不建议在生产库直接开。
+
+### 外置 ANN（默认关）
+
+```yaml
+features:
+  vector: true
+  vectorAnnExternal: true
+vectorAnnEndpoint: 'http://127.0.0.1:8765/search'
+vectorAnnTimeoutMs: 800
 ```
 
-The remote mode refuses to save without a key. The key is stored locally and
-redacted from API responses.
+- 只接 `searchAsync` 异步路径；同步 `search` 继续精确扫描。
+- 端点为空或请求失败 → 回退精确扫描，不丢召回。
+- 客户端契约见 `docs/external-ann.md`。
+- **需要你手动启动本地 ANN 服务**；当前没有常驻服务。
+- 20k 端到端验证：recall@10 1.0，p50 20.3-20.8ms（HTTP 客户端 + HNSW 服务）。
+
+## 3. 可选 HTTP rerank（已接到 QA）
+
+代码：`createHttpReranker`，已在 `cortex_qa` 的检索结果上生效（失败开放，回退融合顺序）。
+
+配置：
+
+```yaml
+- id: cortex
+  name: dsh-cortex
+  config:
+    rerankEnabled: true
+    rerankBaseUrl: "http://127.0.0.1:9000/v1"
+    rerankModel: "bge-reranker-base"
+    # rerankApiKey: ""   # 本机服务通常不需要
+```
+
+接口：
+
+```http
+POST {baseUrl}/rerank
+{"model":"bge-reranker-base","query":"...","documents":["..."],"top_n":8}
+```
+
+返回 `results: [{index, relevance_score}]`。
+
+默认关；没有配置或请求失败时，QA 保持原来的 RRF 顺序，不阻塞回答。
+
+## 4. 本地 ONNX 模型（未内置）
+
+本鲸没有把 `onnxruntime-node` 或 `@huggingface/transformers` 放进运行时依赖，原因：
+
+- 安装体积大（数百 MB）；
+- Windows 上原生二进制/驱动差异；
+- 安装期下载模型不可审计。
+
+后续如果要内置，应该是**单独的 optional 包**，并满足：
 
-## Rerank (optional)
+1. 用户显式点“下载模型”；
+2. 显示 URL、大小、SHA-256；
+3. 下载到 `~/.dsh/cortex/models/`，不写 profile；
+4. 失败开放，不影响 FTS；
+5. 可一键删除。
 
-Any OpenAI-compatible `/rerank` service can be configured. If it is disabled or
-fails, Cortex keeps the original fusion order.
+## 5. 安装包里有什么
 
-## Security
+- 没有模型文件；
+- 没有原生 `.node`；
+- 没有 `node_modules`；
+- 只有纯 JS + SQL + 文档。
 
-- Do not paste keys into issues or chat logs.
-- Local mode is the safest for private data.
-- Remote mode sends memory text to the configured endpoint.
+所以 Windows 用户装完即可用；要用语义模型时再按上面的配置接服务。

package/docs/multimodal.md

@@ -0,0 +1,112 @@
+# 多模态附件：只存引用，不存字节
+
+> 当前实现是**元数据边界**，不是视觉/音频理解模型。
+
+## 1. 写入
+
+`cortex_write` / `POST /api/cortex/write` 支持 `attachments`：
+
+```json
+{
+  "text": "主人发来一张白饭照片。",
+  "explicit": true,
+  "attachments": [
+    {
+      "kind": "image",
+      "uri": "https://example.test/rice.png",
+      "name": "rice.png",
+      "mime": "image/png",
+      "bytes": 12345,
+      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    }
+  ]
+}
+```
+
+约束：
+
+- 最多 8 个
+- `kind`: image / audio / video / file
+- `uri` 必填，最长 2000
+- `sha256` 必须是 64 位 hex
+- `bytes` 0..1e9
+- **不读取、不下载、不解析 URI**
+- 不把二进制写进 SQLite
+
+## 2. 存储
+
+落在 `traces.metadata_json.attachments`：
+
+```json
+{
+  "attachments": [
+    {"kind": "image", "uri": "https://example.test/rice.png", "mime": "image/png", "bytes": 12345}
+  ]
+}
+```
+
+没有单独附件表，也没有内容寻址存储。旧库会通过 `ensureTraceColumns` 自动补 `metadata_json` 列，默认 `{}`。
+
+## 3. 当前能做什么
+
+- 记录“这条记忆关联了哪些附件”的引用
+- 在 trace 读取时返回 metadata
+- 在写入结果里报告附件数量
+- 为未来的视觉/音频模型留出入口
+
+## 4. 当前不能做什么
+
+- 不能读取图片/音频内容
+- 不能生成缩略图
+- 不能做 OCR / 语音转写
+- 不能校验 URI 指向的内容
+- 不能防止恶意 URI（调用方自己负责）
+- 不能自动下载模型
+
+## 5. 安全边界
+
+- 附件只是引用，不是可信内容
+- 不要把私密 URL、token、签名参数写进 uri
+- 隐私删除 trace 时，metadata 随 trace 一起离开；外部 URI 上的文件不在 cortex 控制内
+- 导出 Markdown 是否包含附件元数据，后续再定
+
+## 5.1 可选本地读取器（默认关）
+
+```yaml
+features:
+  attachmentReader: true
+```
+
+```http
+POST /api/cortex/attachments/inspect
+{"uri":"file:///C:/path/rice.txt"}
+```
+
+- **只接受 `file://`**
+- 只返回 name/bytes/mtime/sha256
+- 不返回文件内容
+- 最大 50MB
+- 默认关；未开启 403
+- 写入 audit：`attachment.inspect`
+
+这不是 OCR/转写。它只做本地文件元数据与哈希校验，方便把附件引用和实际文件对上。
+
+## 5.2 提取器联动（可选）
+
+独立包 `dsh-cortex-extractors` 的 `cortex_extract_text` 支持显式 `traceId`：
+
+```json
+{"uri":"file:///C:/tmp/frame.png","mode":"ocr","traceId":"trc_target"}
+```
+
+- 主脑写入一条 **派生 trace**（不修改原 trace）
+- metadata 保留 `derivedFrom`、URI、mode、engine
+- 需要提取器与主脑同时启用
+- 不传 `traceId` 时仍只返回文字，不写记忆
+
+## 6. 下一步
+
+1. 可选附件读取器接口（本地、显式开启）
+2. 图片缩略图/OCR 作为独立可选包
+3. 附件级删除/保留策略
+4. 与 bge 一样：默认关，失败开放，不自动下载模型

package/docs/scopes.md

@@ -0,0 +1,142 @@
+# Scope 与只读共享
+
+> 结论先说：`scope` 是**数据隔离边界**，`readOnlyScopes` 是**写保护**；
+> 它们不是完整的身份认证/授权系统。能读 shared 的调用方仍然能读，只是不能改。
+
+## 0. 默认行为
+
+- 默认 scope：`global`
+- 默认 `readOnlyScopes: []`
+- 默认 dataRoot：`desktop` profile 仍是历史 `~/.dsh/cortex`；其他 profile 未显式配置时派生到 `~/.dsh/cortex/profiles/<profile>`（避免干净 profile 读到 desktop 库）
+- 显式 `dataRoot` / `dbFile` / `CORTEX_HOME` 优先级更高
+- 不配置 `readOnlyScopes` 时，写权限行为和以前一样
+
+## 1. scope 怎么用
+
+API 支持：
+
+```http
+x-cortex-scope: agent-a
+```
+
+或查询参数：
+
+```text
+?scope=agent-a
+```
+
+工具大多只操作当前配置的默认 scope；按 id 的写工具会先查记录所属 scope。
+
+## 2. 只读共享示例
+
+主配置：
+
+```yaml
+- id: cortex
+  name: dsh-cortex
+  config:
+    scope: agent-a
+    readOnlyScopes:
+      - shared
+```
+
+含义：
+
+- `agent-a` 可写自己的 scope
+- `shared` 只能读
+- 写 `shared` 的记忆、工作项、目标、准则、候选边、日记、情绪都会拒绝
+- `forget` / compress / retention / consolidate / vector rebuild 也不会动 `shared`
+
+API 返回：
+
+```json
+{"ok":false,"error":"scope-read-only","scopeId":"shared"}
+```
+
+状态码：**403**。
+
+工具返回：
+
+```text
+未执行：该记录属于只读共享 scope。
+```
+
+## 2.1 显式写授权（可选）
+
+默认只读 scope 谁都写不了。需要给某个 agent 开写时：
+
+```yaml
+- id: cortex
+  name: dsh-cortex
+  config:
+    readOnlyScopes:
+      - shared
+    scopeWriteGrants:
+      - shared:agent-a
+      - grant: shared:agent-b
+        until: '2026-12-31T00:00:00Z'
+```
+
+字符串是永久授权；对象形式到期自动失效。调用时带：
+
+```http
+x-cortex-agent: agent-a
+```
+
+未带 header / 未授权仍是 403。
+
+### 运行时撤销/新增（不重启）
+
+```text
+GET  /api/cortex/security/grants
+POST /api/cortex/security/grants  { "action": "add", "grant": "shared:agent-a" }
+POST /api/cortex/security/grants  { "action": "revoke", "grant": "shared:agent-a" }
+```
+
+覆盖保存在 `<dataRoot>/scope-grants.json`，重启后仍生效。
+撤销会写入 `revoked` 列表，优先于配置文件里的同名 grant。
+这些改动会进 audit：`scope.grant.add` / `scope.grant.revoke`。
+
+这不是登录或签名：header 是本地调用方自报的 agent id，只适合本机多 agent 协作。工具路径不带这个 header，因此工具仍按“默认 scope 只读”处理。
+
+## 3. 多 agent 的两种隔离
+
+### 同一 dataRoot，不同 scope
+
+适合“一个进程里多个 agent / 会话共享一份库”。
+
+- 各自读写自己的 scope
+- `shared` 设为只读
+- 谁有 API 访问权，谁就能读 `shared`
+
+### 不同 dataRoot / profile
+
+适合“完全不同的 agent，不共享数据库”。
+
+- 每个 profile 独立 `dataRoot`
+- 不会互相看到 traces/facts/graph
+- 需要共享时，走导出/导入或单独的共享库
+
+## 4. 这不是什么
+
+- 不是多用户登录 / token 身份系统
+- 不是按 agent 的细粒度 ACL
+- 不会阻止能访问本地 API 的人读取 shared
+- 不会自动把 desktop 数据迁到 shared
+- 不会替调用方判断“这个 agent 该不该读”
+
+## 5. 已验证的边界
+
+- 两个 scope 的 facts / as-of 互不可见
+- 两个 scope 的候选边互不混
+- 只读 scope 的 write / working / goal / playbook / candidate / life / emotion / compress / forget 都会拒绝
+- 候选边仍然要人工 approve 才进图
+
+## 6. 还没做
+
+- agent 身份与签名
+- 显式 share grant / 到期时间
+- 跨 agent 审计报表
+- 多模态附件的共享边界
+
+在这些完成前，文档里不要把它写成“多 agent 安全模型”，只能写“scope 隔离 + 写保护”。