dsh-memory-graph-chiyo 0.0.0-stage → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+## 0.7.0 — 2026-11-07
+
+从「库」变成「既能 import、也能装进 DSH 的插件」。
+
+### 新增
+- `plugin.js`：DSH 插件入口，`apply(ctx, config)` 注册 5 个工具
+  - `memory_write` 写记忆（带锚点）
+  - `memory_recall` 召回
+  - `memory_health` 体检
+  - `memory_nightly` 夜间整理（默认 dry-run）
+  - `memory_shared` 共享记忆（list/propose/approve/revoke）
+- `cordis.patch.yml`：bundle patch，profile 列出包名即挂载
+- `package.json` 增加 `dsh.bundle.patch`、`exports["./plugin"]`、`engines.dsh`
+- 数据目录默认 `~/.dsh/memory-graph`，默认 scope `agent:memory`
+
+### 兼容
+- 没有 `dsh-tools` 时用内置 `defineTool` 兜底（参数映射自动转 JSON Schema）
+- 单个工具注册失败不影响其它工具
+
+### 测试
+47 → **51**（新增插件注册、schema、体检/夜间、共享流程）
+
+## 0.6.0 — 2026-11-07
+
+收口这一版，目标是"别人敢用"。
+
+### 新增
+
+- **矛盾检测**（`conflicts.js`）
+  - 同一类别下"喜欢 / 不喜欢"这类极性翻转 → 旧的标 `superseded`，召回默认只给新的
+  - `scanConflicts()` 批量扫描历史遗留矛盾
+  - `includeSuperseded` 可以显式把旧说法也召回
+- **多进程写锁**：`store.append` 走目录级 `.lock`（mkdir 原子），等待超时 3s，10s 的陈旧锁自动清理
+- **损坏修复**（`repair.js`）：`scanStore` 只检查，`repairStore({apply:true})` 删坏行并备份原文件
+- **TypeScript 声明**：手写 `index.d.ts`，覆盖全部主要 API
+- **性能优化**
+  - 批量写：`appendMany` 一次锁一次写
+  - 缓存就地更新：写入后不再让整个 scope 缓存失效
+  - bigram 缓存：召回时不再重复切词
+  - 召回回写节流：30 秒内同一节点不重复累加 `recallCount`
+- **基准** `bin/bench.mjs`：2000 节点实测写入 ~1400 条/s、纯召回 0.42ms/次
+- **CLI**：`scan` / `repair` 命令
+
+### 测试
+
+39 → **47**
+
+## 0.5.0 — 2026-11-07
+
+把「记忆存储」补成「能接进 agent 的记忆系统」，同时补工程化。
+
+### 新增
+
+- `extractor.js`：从对话自动抽记忆
+  - `heuristicExtract(messages)`：规则 + 事实启发式，零模型
+  - `extractAndWrite(memory, scope, messages)`：过滤敏感 → 校验锚点 → 幂等去重 → 落盘
+  - `buildExtractionPrompt(messages)`：给大模型抽取用的提示词
+- `assemble.js`：按 **token 预算**把召回结果拼成提示词块（事实 / 在办的事 / 印象 / 共享记忆分区，带 id）
+- `snapshot.js`：整个数据目录导出成**单个 JSON 包**，可导入还原（换机器、误删恢复）
+- `SharedMemory`
+  - 每日提名配额（默认 3 条/天）
+  - `dependsOn` 依赖 + 撤销时**级联撤销**下游
+  - 审计日志（`propose` / `approve` / `revoke`，独立 `shared:audit` 作用域）
+- `JsonlStore` 内存缓存：按文件 mtime 失效，写入后自动失效，避免每次召回全量解析
+- 关系边强度：`relations[].weight` + `decayRelations()`（默认半年半衰期，低于阈值摘边）
+- 人物关联：`relations[].type === 'person'` 可指向人物层记录（`options.personIds` 白名单）
+- GitHub Actions：Node 20/22/24 三版本跑测试
+
+### 测试
+
+31 → **39** 个
+
+## 0.4.0 — 2026-11-07
+
+- 规则抽取（主人规矩 / 她自己的承诺）
+- 敏感内容过滤（路径 / QQ号 / 凭据 / 令牌）
+- 锚点强校验（引文必须真的在原文里）
+- 幂等键去重（`idempotencyKey` / `mentionKey`）
+- 人物层（登记 / 别名 / 合并审批）
+- 时段轨迹 + 漏检扫描
+- 六项体检
+- 人格旋钮（六旋钮 + 三重刹车，角色扮演层）
+- 星图可视化（SVG + Mermaid）
+
+## 0.3.0 — 2026-11-07
+
+- 带锚点的上下文压缩（prune / compact / stats，`expand()` 可取回原文）
+- 保证「压缩必须变小」的保护
+
+## 0.2.0 — 2026-11-07
+
+- 跨 scope 召回（合并打分、带来源）
+- 共享记忆（propose → approve → revoke）
+- plan 生命周期（`validTo` 过期）
+- 关系边（6 种类型，召回可沿边扩展）
+- 夜间入口 `nightly()`
+- 命令行 `bin/cli.mjs`
+
+## 0.1.0 — 2026-11-07
+
+- 图记忆内核：锚点强制、四层衰减、写入去重、重要度、召回
+- 即时记忆（6h 醒 / 6h 睡 / 墓碑 / 复活升级）
+- 夜间整理 + 体检
+- JSONL 存储（last-wins、按月分片）

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 浮水梦华
+
+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.md

@@ -1,3 +1,298 @@
-# Temporary Holding Version
+# dsh-memory-graph-chiyo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 可回溯、会遗忘、会睡觉整理的记忆内核。给 AI agent 用的长期记忆图。
+
+[![tests](https://img.shields.io/badge/tests-51%20passing-brightgreen)](https://github.com/fushui-menghua/dsh-memory-graph-chiyo)
+[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/fushui-menghua/dsh-memory-graph-chiyo/blob/main/LICENSE)
+
+## 为什么又一个记忆库
+
+现在的开源记忆方案大致五条路（2026 年现状）：
+
+| 路线 | 代表 | 记忆形态 | 检索 | 短板 |
+|---|---|---|---|---|
+| A. 向量 RAG | 传统向量库 | 文本块 | 向量相似 | 谁说的、什么时候、还算不算数，全丢 |
+| B. 抽取 + 混合检索 | Mem0 | 结构化事实卡 | 语义+关键词+实体 | 事实是模型重写的，**原文不可回溯** |
+| C. 时序知识图谱 | Zep / Graphiti | 实体关系图 + 时间区间 | 图遍历 + 时间过滤 | 状态变化处理最强，但重 |
+| D. OS 分层记忆 | Letta / MemGPT | 内存页 + 归档 | 模型自己搬页 | 依赖模型自律，容易漂 |
+| E. 本体图谱 | Cognee | 本体 + 图 | 图查询 | 要设计 schema，接入成本高 |
+
+**本项目走 B+C 的混合，但多三件事：**
+
+1. **锚点强制（anchors）** —— fact / plan 必须能指回原话片段，否则拒收。
+2. **四层衰减** —— instant → short → long → cold；不是只增不减的仓库。
+3. **夜间整理（consolidation）** —— 归档重复与墓碑，把提过多次、规则承诺类升层。
+
+一句话：**它记得住，也忘得掉，而且每晚自己整理。**
+
+## 能力清单
+
+| 能力 | 说明 |
+|---|---|
+| 锚点强制 | `fact`/`plan` 必须带原话；`impression` 可无 |
+| 写入即去重 | 规范化文本相同 → 合并 `mentionCount` |
+| 四层衰减 | `short`→`long`（提 3 次满 2 天）；长期不用 →`cold` |
+| 重要度 | 提及 + 召回 + 锚点 + 类别 + 新鲜度加权，召回即反哺 |
+| 召回 | 字符 bigram + 关键词 + 重要度 + 新鲜度；过滤冷层/归档/过期 |
+| **跨 scope 召回** | 多 scope 合并打分，结果带 `scope` 来源 |
+| **关系边** | `person`/`relationship`/`because`/`derivedFrom`/`supports`/`contradicts`；召回可沿边扩展一跳（进出边都算） |
+| **plan 生命周期** | 有 `validTo`，过期自动 `expired`，过期后不再召回 |
+| 即时记忆 | 醒 6h → 睡 6h → 墓碑；精确复活；复活 3 次升级成 fact |
+| **共享记忆** | propose → approve → 跨会话可见 → revoke；未批准不可召回 |
+| 夜间整理 | 归档重复/墓碑/极小陈旧；强化规则承诺类 |
+| 体检 | 分层、类别、锚点覆盖率、90 天陈旧数 |
+| **上下文压缩（带锚点）** | 超阈值折叠旧轮次 → 摘要 + 锚点 + 原文可 `expand()` 取回；工具输出先掐头去尾 |
+| **规则抽取** | 从原话认出「主人定的规矩」和「她自己的承诺」，自动生成带锚点的规则节点 |
+| **敏感过滤** | 路径 / QQ号 / 凭据 / 令牌写入前拒收，可逐类放行 |
+| **锚点强校验** | 传了原始消息时，引文必须真的在里面，防模型编造 |
+| **幂等去重** | `idempotencyKey` / `mentionKey`，同一件事换说法也只记一次 |
+| **人物层** | 登记、别名解析、合并提议与审批 |
+| **时段轨迹 / 漏检扫描** | 回看某段时间发生了什么；找出没被任何锚点引用过的话 |
+| **人格旋钮（可选）** | 六个性格旋钮，带单步/每日/漂移三重刹车（角色扮演层，非记忆） |
+| **星图可视化** | 零依赖 SVG + Mermaid 输出，可直接贴 README |
+| **自动抽取管道** | `extractAndWrite`：从对话抽规则/事实 → 敏感过滤 → 锚点校验 → 幂等去重 → 落盘 |
+| **提示词装配** | `assembleContext`：按 token 预算分区拼装（记得的事/在办的事/印象/共享） |
+| **快照导入导出** | 整个数据目录导成单个 JSON，可还原（换机器、误删恢复） |
+| **关系强度衰减** | 边有 weight，默认半年半衰期，低于阈值自动摘边 |
+| **共享审计与配额** | 每日提名上限、依赖级联撤销、独立审计日志 |
+| **store 缓存** | 按文件 mtime 失效，写入即失效，召回不必全量解析 |
+| **矛盾检测** | 喜欢/不喜欢这类翻转 → 旧的标 `superseded`，只召回新的 |
+| **多进程写锁** | 目录级锁 + 超时 + 陈旧锁清理 |
+| **损坏修复** | `scanStore` / `repairStore`，坏行剔除并备份原文件 |
+| **TypeScript 类型** | 内置 `index.d.ts` |
+| **性能基准** | `npm run bench`：2000 节点写入 ~1400 条/s、召回 0.42ms |
+| 命令行 | `memory-graph health/recall/recall-all/nightly/shared-*/scan/repair` |
+| 零依赖 | 只用 Node 内置模块 |
+
+## 安装
+
+**作为库（推荐给开发者）**
+
+```bash
+npm i dsh-memory-graph-chiyo
+```
+
+**作为 DSH 插件（推荐给 DSH 用户）**
+
+```bash
+dsh plugin --profile web add dsh-memory-graph-chiyo
+```
+
+装上后 DSH 会注册 5 个工具：`memory_write` / `memory_recall` / `memory_health` / `memory_nightly` / `memory_shared`。
+数据默认在 `~/.dsh/memory-graph`，默认 scope `agent:memory`（可在 plugin 配置里改）。
+
+> 插件与库是同一个包：`import` 用 `./src/index.js`，DSH 走 `./plugin.js` 的 `apply(ctx)`。
+
+
+```bash
+npm i dsh-memory-graph-chiyo
+```
+
+要求 Node ≥ 20。
+
+## 快速开始
+
+```js
+import { createMemory } from 'dsh-memory-graph-chiyo';
+
+const mem = createMemory({ dir: './memory-data' });
+
+// 1) 写：fact 必须带锚点
+mem.write('user:alice', {
+  nodes: [
+    { kind: 'fact', text: '她喜欢下雨天', anchors: [{ quote: '我最喜欢下雨了' }] },
+    { kind: 'fact', text: '她怕黑', anchors: [{ quote: '我怕黑' }] },
+  ],
+});
+
+// 2) 建立关系边（目标必须已存在）
+const fear = mem.load('user:alice').find((n) => /怕黑/.test(n.text));
+mem.write('user:alice', {
+  nodes: [{ kind: 'fact', text: '睡觉要留一盏小灯', anchors: [{ quote: '留个灯' }], relations: [{ type: 'because', targetId: fear.id }] }],
+});
+
+// 3) 召回（hops=1 沿关系扩展）
+const hits = mem.recall('user:alice', { query: '怕黑', hops: 1 });
+
+// 4) 跨 scope 召回
+mem.recallAcross(['user:alice', 'agent:chiyo'], { query: '下雨' });
+
+// 5) 计划（3 天后自动过期）
+mem.write('user:alice', { nodes: [{ kind: 'plan', text: '周末去看海', anchors: [{ quote: '周末去海边' }], validDays: 3 }] });
+
+// 6) 共享记忆：提名 → 批准 → 可召回
+const s = mem.proposeShared({ text: '雨天适合听老唱片', sourceScope: 'group:demo' });
+mem.approveShared(s.id, { by: 'owner' });
+mem.recallShared({ query: '雨天' });
+
+// 7) 睡一觉：推进层/即时/计划 + 整理 + 体检
+const report = mem.nightly(['user:alice', 'agent:chiyo'], { apply: true });
+```
+
+## 上下文压缩（带锚点）
+
+普通压缩的毛病：摘要写完，原话就找不回来了。这里给摘要挂 **anchors**（被折叠事件的 id），
+被折叠的原文默认从 `shadowed` 返回，随时能取回。
+
+```js
+import { createCompactor } from 'dsh-memory-graph-chiyo';
+
+const comp = createCompactor({
+  windowTokens: 128000,   // 模型上下文窗口
+  thresholdRatio: 0.3,    // 超过 30% 才压
+  keepTurns: 10,          // 保留最近 10 轮
+  pruner: { thresholdChars: 8000, headChars: 6000, tailChars: 1500 },
+  // summarizer: async (events) => '用你的模型写摘要',  // 可选，默认是确定性抽取
+});
+
+const r = await comp.compact(events);
+// r.compacted     是否真的压了
+// r.events        新上下文：摘要块 + 最近 N 轮
+// r.anchors       被折叠事件的 id 列表（摘要里也写了一份）
+// r.shadowed      被折叠的原文，存哪儿由你决定
+// r.beforeTokens / r.afterTokens
+
+// 想核对摘要对不对：
+for (const e of comp.expand(r)) console.log(e.id, e.text);
+
+// 审计每次压缩：
+console.log(comp.stats());
+// [{ at, beforeK, afterK, freedK, folded, keptTurns }]
+```
+
+三层策略（跟她实际在用的那套一致）：
+
+| 层 | 做什么 | 什么时候 |
+|---|---|---|
+| prune | 工具输出掐头去尾 | 单条超过 `thresholdChars` |
+| compact | 旧轮次折叠成摘要 | 总占用超过 `windowTokens × thresholdRatio` |
+| stats | 记录放掉多少、留几轮 | 每次压缩后 |
+
+**保证不变大的保护**：如果摘要比原文还长（窗口很小时会这样），会先截短；实在压不下去就跳过并返回 `note`，不会假装压过。
+
+## 命令行
+
+```bash
+# 体检
+npx memory-graph health --dir ./data --scope user:alice
+
+# 召回
+npx memory-graph recall --dir ./data --scope user:alice --query 下雨
+
+# 跨 scope
+npx memory-graph recall-all --dir ./data --scopes user:alice,agent:chiyo --query 下雨
+
+# 夜间整理（dry-run / --apply）
+npx memory-graph nightly --dir ./data --scopes user:alice --apply
+
+# 共享记忆
+npx memory-graph shared-list --dir ./data
+npx memory-graph shared-approve --dir ./data --id s_xxx --by owner
+```
+
+配合系统计划任务，每天凌晨自动整理：
+
+```bash
+# Linux / macOS
+0 3 * * * cd /path/to/app && npx memory-graph nightly --dir ./data --scopes user:alice --apply
+```
+
+## 存储
+
+JSONL，按 scope 和月份分文件：
+
+```
+memory-data/
+├─ user_alice/2026-11.jsonl
+├─ agent_chiyo/2026-11.jsonl
+└─ shared_global/2026-11.jsonl   ← 共享记忆独立存放
+```
+
+- **last-wins**：同 id 以最后一条为准，改状态不改历史
+- **可 grep**：你的记忆是你自己的
+- **崩溃安全**：最多丢最后一行
+
+## 核心概念
+
+| 概念 | 说明 |
+|---|---|
+| `scope` | `user:alice` / `agent:chiyo` / `group:demo`，隔离单位 |
+| `kind` | `fact`（有锚点）/ `impression`（主观）/ `plan`（有失效期） |
+| `layer` | `instant` / `short` / `long` / `cold` / `permanent` |
+| `anchors` | 原话片段，用于回溯与验证 |
+| `relations` | 节点间的边，召回可扩散 |
+| `status` | plan 专用：`active` / `done` / `abandoned` / `expired` |
+
+## 规则抽取 / 人物 / 时间线 / 体检 / 星图
+
+```js
+// 规则：从原话里认出规矩与承诺
+const rules = mem.extractRules('以后不要在深夜给我发消息', { speaker: 'owner' });
+// → [{ kind:'fact', text:'以后不要在深夜给我发消息', cluster:'rule-owner', anchors:[...] }]
+mem.write('user:alice', { nodes: rules });
+
+// 人物：登记 → 别名解析 → 合并审批
+mem.person.upsert({ name: '阿岚', aliases: ['小岚'] });
+const p = mem.person.proposeMerge('阿岚', '岚岚');
+mem.person.approveMerge(p.id, { by: 'owner' });
+
+// 时间线：这段时间发生了什么 + 哪些话没进记忆
+mem.episode({ scope: 'user:alice', from: Date.now() - 86400_000 });
+mem.missedScan({ scope: 'user:alice', messages });
+
+// 体检：六项指标
+mem.healthReport({ scope: 'user:alice' });
+// { checks: [锚点覆盖率, 重复率, 长期占比, 即时占比, 陈旧度, 归档与共享], ok, failed }
+
+// 星图：SVG 或 Mermaid
+const svg = mem.starMap(mem.load('user:alice'), { title: '她的记忆星图' });
+const mmd = mem.mermaid(mem.load('user:alice'));
+```
+
+### 人格旋钮（可选，跟记忆无关）
+
+> ⚠️ 这一层是**角色扮演**，不是记忆。记忆回答"发生过什么"，人格回答"用什么性格说话"。
+> 不需要的话完全不调用即可，不影响其它能力。
+
+```js
+mem.persona.get();                    // { tsundere, playfulness, initiative, softness, snark, moodSwing }
+mem.persona.tune('initiative', 0.05, { by: 'owner', reason: '希望更主动' });
+mem.persona.summary();                // 「傲娇 中等；爱玩 偏高；主动 很高…」
+mem.persona.revert();
+```
+
+三重刹车（防止人格一夜之间漂走）：
+
+```
+单步 ≤ 0.05      · 每天最多 1 次      · 距基线累计偏移 ≤ 0.15
+```
+
+## 范围说明
+
+- **长期记忆**：跨会话的节点、衰减、关系、整理（本项目的核心）
+- **上下文压缩**：单次对话太长时腾出窗口，摘要带锚点可回溯（v0.3.0 起内置）
+
+两者互补：压缩管"这一次对话装不下"，整理管"跨天该忘什么"。
+
+## 测试
+
+```bash
+npm test
+# 47 tests: 锚点 / 召回 / 去重 / 即时记忆 / 整理 / 层推进 / 体检
+         跨 scope / 共享审批 / plan 过期 / 关系边扩展 / nightly 全流程
+         压缩 / 规则抽取 / 敏感过滤 / 锚点强校验 / 幂等键 / 人物合并 / 时间线 / 漏检
+         自动抽取 / 提示词装配 / 快照往返 / 关系衰减 / 共享审计配额 / store 缓存
+         矛盾检测 / 矛盾扫描 / 写锁超时 / 陈旧锁 / 损坏修复 / d.ts 完整 / 召回性能护栏
+```
+
+## 设计取舍
+
+- **不做嵌入向量**：默认字符 bigram + 关键词 + 重要度，零依赖、可解释；
+  要语义检索可自行替换 `recall`（纯函数，好接 embedding）。
+- **不自动摘要**：摘要会丢掉原话，而原话是这套系统的地基。
+- **不删除**：归档只是 `archived: true`，永远可恢复。
+- **共享要审批**：默认只能提名，批准后才跨会话可见。
+
+## License
+
+MIT © 浮水梦华

package/bin/bench.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * bench.mjs —— 性能基准：生成 N 条记忆，测写入/召回/整理耗时
+ *
+ *   node bin/bench.mjs 10000
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createMemory } from '../src/index.js';
+
+const N = Number(process.argv[2]) || 10000;
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'chiyo-bench-'));
+const mem = createMemory({ dir });
+
+const words = ['下雨', '猫', '深夜', '海边', '唱片', '咖啡', '书', '散步', '旧照片', '风'];
+const t0 = Date.now();
+let batch = [];
+let writeErrors = 0;
+for (let i = 0; i < N; i += 1) {
+  const w = words[i % words.length];
+  batch.push({ kind: i % 7 === 0 ? 'impression' : 'fact', text: `第 ${i} 条：她${w}相关的事 ${i % 97}`, anchors: [{ quote: `${w} ${i}` }], category: 'preference' });
+  // 单次最多写 5 条（options.maxNodesPerWrite），批量按 5 切
+  if (batch.length === 5) {
+    try { mem.write('user:bench', { nodes: batch, allowSensitive: true }); } catch (e) { writeErrors += 1; }
+    batch = [];
+  }
+}
+if (batch.length) mem.write('user:bench', { nodes: batch, allowSensitive: true });
+const writeMs = Date.now() - t0;
+
+const t1 = Date.now();
+let hits = 0;
+for (let i = 0; i < 200; i += 1) hits += mem.recall('user:bench', { query: words[i % words.length], limit: 20, track: false }).length;
+const recallMs = Date.now() - t1;
+const t1b = Date.now();
+for (let i = 0; i < 50; i += 1) mem.recall('user:bench', { query: words[i % words.length], limit: 20 });
+const recallTrackedMs = Date.now() - t1b;
+
+const t2 = Date.now();
+const cons = mem.consolidate('user:bench', { apply: false });
+const consMs = Date.now() - t2;
+
+const live = mem.load('user:bench').filter((n) => !n.archived).length;
+console.log(JSON.stringify({
+  nodes: live,
+  writeMs,
+  writePerSec: Math.round((live / Math.max(1, writeMs)) * 1000),
+  writeErrors,
+  recall200PureMs: recallMs,
+  recallPureAvgMs: Number((recallMs / 200).toFixed(2)),
+  recall50TrackedMs: recallTrackedMs,
+  recallTrackedAvgMs: Number((recallTrackedMs / 50).toFixed(2)),
+  hits,
+  consolidateMs: consMs,
+  candidates: { archive: cons.archived, reinforce: cons.reinforced },
+  dir,
+}, null, 2));

package/bin/cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * cli.mjs —— 命令行入口
+ *
+ *   node bin/cli.mjs health   --dir ./data --scope user:alice
+ *   node bin/cli.mjs recall   --dir ./data --scope user:alice --query 下雨
+ *   node bin/cli.mjs nightly  --dir ./data --scopes user:alice,agent:chiyo [--apply]
+ *   node bin/cli.mjs shared-list --dir ./data
+ *   node bin/cli.mjs shared-approve --dir ./data --id s_xxx --by owner
+ */
+import { createMemory } from '../src/index.js';
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) out[key] = true;
+      else { out[key] = next; i += 1; }
+    } else out._.push(a);
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0];
+const dir = String(args.dir ?? './memory-data');
+const memory = createMemory({ dir });
+const scope = args.scope ? String(args.scope) : null;
+const scopes = args.scopes ? String(args.scopes).split(',').map((s) => s.trim()).filter(Boolean) : (scope ? [scope] : []);
+
+if (!cmd) {
+  console.log('用法: cli.mjs <health|recall|recall-all|tick|consolidate|nightly|shared-list|shared-approve|shared-revoke> [--dir ...] [--scope ...] [--query ...] [--apply]');
+  process.exit(0);
+}
+if (!scope && !['nightly', 'shared-list', 'shared-approve', 'shared-revoke', 'scan', 'repair'].includes(cmd)) {
+  console.error('缺少 --scope（或命令不适用）');
+  process.exit(1);
+}
+
+switch (cmd) {
+  case 'health': {
+    console.log(JSON.stringify(memory.health(scope), null, 2));
+    break;
+  }
+  case 'recall': {
+    const hits = memory.recall(scope, { query: String(args.query ?? ''), limit: Number(args.limit ?? 10), includeCold: args.cold === true });
+    for (const h of hits) console.log(`[${h.kind}/${h.layer}] ${h.text}  (score ${h.score})`);
+    if (!hits.length) console.log('（没有命中）');
+    break;
+  }
+  case 'recall-all': {
+    const hits = memory.recallAcross(scopes.length ? scopes : [scope], { query: String(args.query ?? ''), limit: Number(args.limit ?? 15) });
+    for (const h of hits) console.log(`[${h.scope}] [${h.kind}/${h.layer}] ${h.text}  (score ${h.score})`);
+    if (!hits.length) console.log('（没有命中）');
+    break;
+  }
+  case 'tick': {
+    const changes = memory.tickLayers(scope, { apply: args.apply === true });
+    console.log(`层变化 ${changes.length} 条${args.apply ? '（已写入）' : '（dry-run）'}`);
+    for (const c of changes) console.log(`  ${c.from} → ${c.to}  ${c.text}`);
+    break;
+  }
+  case 'consolidate': {
+    const r = memory.consolidate(scope, { apply: args.apply === true });
+    console.log(JSON.stringify({ scope: r.scope, total: r.total, archived: r.archived, reinforced: r.reinforced, apply: r.apply }, null, 2));
+    break;
+  }
+  case 'scan': {
+    console.log(JSON.stringify(memory.scanStore({ dir }), null, 2));
+    break;
+  }
+  case 'repair': {
+    console.log(JSON.stringify(memory.repairStore({ dir, apply: args.apply === true }), null, 2));
+    break;
+  }
+  case 'nightly': {
+    const r = memory.nightly(scopes, { apply: args.apply === true });
+    console.log(JSON.stringify(r, null, 2));
+    break;
+  }
+  case 'shared-list': {
+    const rows = memory.listShared({ status: String(args.status ?? '') });
+    for (const e of rows) console.log(`[${e.status}] ${e.id}  ${e.text.slice(0, 60)}  (from ${e.sourceScope})`);
+    if (!rows.length) console.log('（没有共享记忆）');
+    break;
+  }
+  case 'shared-approve': {
+    const e = memory.approveShared(String(args.id), { by: String(args.by ?? 'owner') });
+    console.log(`已批准：${e.id}  ${e.text.slice(0, 60)}`);
+    break;
+  }
+  case 'shared-revoke': {
+    const e = memory.revokeShared(String(args.id), { by: String(args.by ?? 'owner'), reason: String(args.reason ?? '') });
+    console.log(`已撤销：${e.id}`);
+    break;
+  }
+  default:
+    console.error(`未知命令：${cmd}`);
+    process.exit(1);
+}

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# ============================================================================
+# dsh-memory-graph-chiyo —— DSH bundle patch
+# 装上之后，profile 在 dsh.profile.bundles 里列出本包名即生效：
+#   dsh plugin --profile web add dsh-memory-graph-chiyo
+# ============================================================================
+- insert:
+    - id: memory-graph
+      name: dsh-memory-graph-chiyo
+      config:
+        # 数据目录默认为 ~/.dsh/memory-graph，scope 默认为 agent:memory
+        scope: agent:memory