recallnest 2.6.1 → 3.0.1

package/README_CN.md

@@ -2,17 +2,17 @@
 
 # RecallNest
 
-**面向任意 MCP 客户端的共享记忆层 —— Claude Code、Codex、Kimi、Antigravity、Gemini CLI**
+**面向任意 AI 客户端的共享记忆层 —— CLI agent、桌面 app、你自己的脚本**
 
-*一套记忆，每个终端，上下文跨窗口延续。*
+*一套记忆，每个客户端，上下文跨窗口延续——也跨机器。*
 
 基于 LanceDB 的本地优先记忆系统，把散落在各个终端的对话历史沉淀为可复用知识，跨终端共享，自动召回。
 
 [![GitHub](https://img.shields.io/github/stars/AliceLJY/recallnest?style=social)](https://github.com/AliceLJY/recallnest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Runtime](https://img.shields.io/badge/Runtime-Bun_|_Node.js_18+-f9f1e1?logo=bun)](https://bun.sh)
+[![Runtime](https://img.shields.io/badge/Runtime-Bun_|_Node.js_22+-f9f1e1?logo=bun)](https://bun.sh)
 [![LanceDB](https://img.shields.io/badge/LanceDB-Vector+FTS-orange)](https://lancedb.com)
-[![MCP](https://img.shields.io/badge/MCP-43_tools-blue)](https://modelcontextprotocol.io)
+[![MCP](https://img.shields.io/badge/MCP-44_tools-blue)](https://modelcontextprotocol.io)
 [![CI](https://github.com/AliceLJY/recallnest/actions/workflows/ci.yml/badge.svg)](https://github.com/AliceLJY/recallnest/actions/workflows/ci.yml)
 [![CC Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://github.com/AliceLJY/recallnest)
 
@@ -26,115 +26,34 @@
 
 编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Kimi、Antigravity 以及你打开的每一个终端里，互相不通。
 
-RecallNest 的解法：**一个 LanceDB 驱动的记忆层，供你的编程 Agent 共读共写**。一个窗口存入的上下文，另一个窗口自动召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——不是简单的日志堆积。
+RecallNest 是**一个 LanceDB 驱动的记忆层，你所有的 Agent 共读共写**。一个窗口存入的上下文，另一个窗口能召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——它不是一堆等你 grep 的日志。
 
+### 一次召回长什么样
 
-## 快速开始
-
-### 方式 A：Claude Code Plugin（推荐）
-
-```bash
-/plugin marketplace add AliceLJY/recallnest
-/plugin install recallnest@AliceLJY
-```
-
-RecallNest 随 Claude Code 自动启动，无需手动配置 MCP。
-
-安装时 Claude Code 会提示填写 Jina API key。密钥由 Claude Code 的敏感插件配置保存；自动生成的配置和 LanceDB 数据库则放在插件持久数据目录，不会混进按版本更新的插件缓存。
-
-> Claude Code 插件与 npm 包共用同一个发布版本，并随版本发布同步更新。
->
-> **前置要求：** [Bun](https://bun.sh)。首次启动自动安装依赖。
-
-### 方式 B：npm 安装
-
-```bash
-npx recallnest --help          # 直接运行
-# 或
-npm install -g recallnest      # 全局安装
-recallnest doctor
-```
-
-支持 Node.js 18+（通过 tsx）或 Bun，无需 clone 仓库。
-
-### 方式 C：手动安装
-
-```bash
-git clone https://github.com/AliceLJY/recallnest.git
-cd recallnest
-bun install
-cp config.json.example config.json
-cp .env.example .env
-# 编辑 .env → 填入 JINA_API_KEY
-```
-
-### 启动服务
-
-```bash
-bun run api
-# → RecallNest API running at http://localhost:4318
-```
-
-### 试一下
-
-```bash
-# 存入一条记忆
-curl -X POST http://localhost:4318/v1/store \
-  -H "Content-Type: application/json" \
-  -d '{"text": "用户偏好暗色模式", "category": "preferences"}'
-
-# 搜索记忆
-curl -X POST http://localhost:4318/v1/recall \
-  -H "Content-Type: application/json" \
-  -d '{"query": "用户偏好"}'
-
-# 查看统计
-curl http://localhost:4318/v1/stats
-```
-
-### 接入终端
-
-```bash
-bash integrations/claude-code/setup.sh
-bash integrations/gemini-cli/setup.sh
-bash integrations/codex/setup.sh
-```
+```text
+Query   : deploy rollback
+Hits    : 5
 
-每个脚本会同时安装 MCP 和 continuity 规则，新窗口自动触发 `resume_context`。
-
-### 索引已有对话
-
-```bash
-bun run src/cli.ts ingest --source all
-bun run seed:continuity
-bun run src/cli.ts doctor
+#  ID       Score Category  Tier        Source  Date        Age  Retrieval Path
+1  ee79037a 46.1% cases     peripheral  cc      2026-08-25  2d   vector
+   [assistant] Rolled back to the previous image and pinned the digest so the next…
+   prov : evidence/transcript-ingest
+   imgs : 52 agent-made in this session · read sess=dca70d4a
 ```
 
----
-
-## Web UI
+这一小块里有三样东西，几乎就是整个设计：
 
-<p align="center">
-  <img src="assets/dashboard.png" alt="RecallNest Dashboard" width="800" />
-  <br><em>Dashboard —— 总量、类别分布、健康评分、增长趋势一目了然。</em>
-</p>
-
-<p align="center">
-  <img src="assets/screenshots/ui-full.png" alt="RecallNest Search Workbench" width="800" />
-  <br><em>Search Workbench —— 混合检索 + Topic Tag 过滤 + 4 套检索策略 + Skills 浏览 + 资产管理。</em>
-</p>
-
-<p align="center">
-  <img src="assets/knowledge-graph.png" alt="RecallNest Knowledge Graph" width="800" />
-  <br><em>Knowledge Graph —— 交互式力导向图，语义桥接揭示跨域隐藏关联。</em>
-</p>
+- **`Source cc` · `Age 2d`** —— 它出自两天前的一个 Claude Code 窗口，而你正在另一个终端、
+  甚至另一台机器上读它。整个项目就建在这个前提上。
+- **`prov : evidence/…`** —— 每一行都标着自己待在哪一层。从对话里刮下来的碎片，永远没资格
+  冒充你真正做过的决定；要变成稳定记忆，得另走一道带证据门槛的提升流程。
+- **`imgs : …`** —— 那个 session 里有 52 张图，**一张都没进数据库**。这一行的存在只是让你知道
+  那儿有东西可看，而产生它没花一次模型调用、没多一个向量、没占一份存储。
 
-```bash
-bun run src/ui-server.ts
-# → http://localhost:4317
-```
+最后这条就是整套做法的缩影：**只存"让一样东西能被找到"所需的部分，不存"将来可能被问到"的一切。**
+完整的推理——包括最显然的那种实现错在哪两个地方——在
+[图片：可寻址，而不是被编码](#图片可寻址而不是被编码)。
 
----
 
 ## 核心能力
 
@@ -143,8 +62,8 @@ bun run src/ui-server.ts
 | 能力 | 说明 |
 |---|---|
 | **CC Plugin** | 一行命令装入 Claude Code，无需手动配置 MCP |
-| **共享索引** | 所有支持 MCP 的终端共用同一个 LanceDB 存储 |
-| **双通道接入** | MCP（stdio）给 CLI 工具 + HTTP API 给自定义 Agent |
+| **共享索引** | 所有客户端共用同一个 LanceDB 存储，跨机指向 `ssh` 即可共用真相源 |
+| **双通道接入** | MCP（stdio）给 CLI agent 与能填 MCP 配置的 GUI app + HTTP API 给只会发请求的客户端 |
 | **一键接入** | 集成脚本同时安装 MCP 和 continuity 规则 |
 
 ### 检索与连续性
@@ -196,133 +115,240 @@ bun run src/ui-server.ts
 
 ---
 
-## v2.6 新增：跨进程一致性与可靠分发
+## 架构
 
-v2.6 把 v2.5.4 以来的开发整理成一版可升级、可安装、版本口径一致的正式候选：
+```
+  CLIENTS                    ACCESS                      CORE ENGINE                    STORAGE
+  ──────────────────────     ───────────────────────     ────────────────────────────   ──────────────────────
+
+  Claude Code                MCP over stdio              Retriever                      LanceDB
+  Codex                ───▶  44 tools, 3 tiers    ───▶   vector + BM25 + RRF     ───▶   vector + columnar
+  Kimi · Antigravity                                     Classifier · 6 categories
+  Doubao desktop                                         Context composer
+                             HTTP API :4318              resume_context                 Jina embeddings v5
+  your scripts · cron  ───▶  21 endpoints          ───▶  Decay · Weibull half-life ─▶   1024-dim, task-aware
+                                                         Conflict · audit + merge
+  phone app            ───▶  read-only gateway     ───▶  Capture: evidence → durable
+                             :8791, token-gated
+```
 
-- **跨进程即时可见** —— LanceDB 默认每次读取都检查外部提交，常驻 MCP/API/UI 无需重启即可看见 CLI ingest 写入。可用 `RECALLNEST_READ_CONSISTENCY_INTERVAL=<秒>` 设置允许的延迟窗口，或设为 `off` 恢复旧版不检查行为。
-- **更安全的记忆演化** —— 信念变化不再原地覆盖，旧记录保留为 `superseded`；程序性记忆免于时间衰减；冷启动和长度归一化不再压低短实体查询与稳定记忆。
-- **更可靠的整合管线** —— `dream` 增加失败分型、总时长预算、聚类前向量回填，以及“成功必须真的产出结果”的断言。
-- **更完整的对话来源** —— Kimi、AGY/Antigravity 和 minis 已同步纳入 ingest、scope 边界与术语识别。
-- **一个公开版本号** —— npm 元数据、CLI `--version`、MCP 握手、HTTP 健康接口和 Claude Code marketplace 统一遵守 `2.6.0` 发布契约。
-- **真正可安装的 Claude Code 插件** —— 安装后自动注册 43 个 MCP 工具与连续性 skill，通过敏感插件配置接收 Jina key，并把配置与 LanceDB 数据放进 Claude Code 的持久插件数据目录。
+> 图内保留英文术语：等宽字体下中文占两格，混排会把对齐打乱。四段从左到右分别是
+> 客户端、接入层（MCP / HTTP / 只读网关）、核心引擎、存储层。
 
-### 从 v2.5.4 升级
+### 内部设计
+
+- **L0 / L1 / L2 动态折叠** —— 每条记忆存储 3 个粒度层（一句话 / 要点概要 / 完整内容）；检索时根据相关性分数和 token 预算动态选择返回哪个层级
+- **Weibull 衰减 + 情绪调制** —— 记忆沿参数化 Weibull 曲线衰减；情绪显著性可额外延长半衰期最高 30%
+- **向量预筛 + LLM 去重** —— 90% 的去重决策用低成本余弦相似度（≥ 0.92）；仅临界情况调用 LLM 判断
+- **类别分化合并策略** —— `profile` 和 `preferences` 采用冲突合并（新版覆盖）；`events` 和 `cases` 采用追加（保留历史）
+- **展示分 vs 淘汰分双轨制** —— 检索使用双轨评分：tier floor 防止核心记忆被淘汰，decay boost 让新鲜记忆临时浮现而不永久挤掉稳定记忆
 
-- 现有 LanceDB 数据原地打开；缺少新字段的旧表会自动迁移，空表也覆盖。
-- 插件数据位于版本缓存之外，更新插件不会清空；手动 clone 仍沿用现有 `config.json` 与数据库路径。
-- 检索操作现已写入审计日志。`audit.jsonl` 暂无自动轮转，接近 50 MB 时建议人工归档。
-- `RECALLNEST_LAYER_ADMISSION` 仍是显式开启项（`observe` 或 `on`），默认 `off`。
+> 完整架构详解：[`docs/architecture.md`](docs/architecture.md)
 
 ---
 
-## v2.1 新增：记忆哲学驱动的架构升级
+## 谁能接上
 
-v2.0 建立了完整的记忆操作平台；v2.1 加入了记忆哲学驱动的记忆行为。
+**数据层不知道你的客户端长什么样。** RecallNest 把同一个 LanceDB 存储通过三个出口暴露出来，接法按客户端的能力选，而不是绑死在某一种协议上。
 
-来自 9 个记忆哲学研究维度的 5 项工程升级：
+| 你的客户端能做什么 | 走哪条 | 已验证 |
+|---|---|---|
+| 执行本地命令（CLI agent） | **MCP over stdio** | Claude Code、Codex、Kimi、Antigravity |
+| 执行本地命令（GUI app，手填 MCP 配置） | **MCP over stdio** | 豆包桌面端——与 Cherry Studio / ChatBox 同一形态 |
+| 只会发 HTTP 请求 | **HTTP API** | 自定义 agent、脚本、定时任务 |
+| 跑在另一台机器上 | 把 stdio 启动命令换成 `ssh <host> recallnest-mcp` | 笔记本上的四个客户端共读家里服务器上的同一个库 |
 
-- **情绪感知衰减** *（情感记忆理论）* —— 带有强烈情绪的记忆衰减慢 20-30%。基于关键词的情绪检测计算 `salience`（记忆显著性），注入 Weibull 半衰期公式和重新平衡的 4 因子演化评分。零 LLM 成本。
+两条值得直说的推论：
 
-- **记忆伦理层** *（遗忘权 / GDPR 第 17 条）* —— 四级隐私：`ephemeral`（临时）/ `private`（私密）/ `durable`（持久）/ `shared`（共享）。级联遗忘引擎贯穿 KG 三元组、演化链、Pin 资产和摘要。完整审计日志。`forget_memory` MCP 工具支持 Agent 驱动的删除。
+- **不绑单一协议。** 支持填 MCP 配置的 GUI 聊天 app，接入方式和终端里的 agent 完全一样；只会发 HTTP 请求的客户端，读到的仍是同一份记忆。
+- **不绑单台机器。** 因为 MCP 传输走 stdio，启动命令由你定义——把它指向 `ssh`，每台机器上的每个客户端共用同一个真相源，而不是各自长出一个数据库。
 
-- **自传叙事架构** *（叙事身份理论 / Conway 三层模型）* —— 记忆标注 `生命阶段 → 一般事件 → 具体事件` 层级，正交于现有 6 类别。检索自动拉取叙事兄弟。上下文渲染按生命阶段分组。支持中英文的规则式标注器。
+接一个新客户端不等于要改 RecallNest：够格的客户端自己写一行配置，能力受限的在 HTTP API 前面加一层薄网关。
 
-- **建构式检索** *（模拟理论 / Michaelian）* —— 不再返回原始存储文本，而是从扩展候选集（KG 邻居 + 演化链 + 聚类成员 + 叙事兄弟）中重建上下文。Source-map 语义覆盖率替代词汇重叠。矛盾检测与标记。
+### 手机上的 AI app：只读网关
 
-- **预测式前瞻记忆** *（精神时间旅行 / Tulving）* —— 启发式预测引擎从行为信号中浮现"你可能需要这个"提醒：过期的 checkpoint 待办事项、被纠正的工作流观察、高频休眠记忆和未覆盖的查询主题。零 LLM 成本。7 天未接受自动过期。
+HTTP API（`:4318`）只监听 `127.0.0.1`，并且会拒绝任何 Host 头不是本地的请求——这是**有意的**：它同时暴露写入路由（`/v1/store`、`/v1/checkpoint`），直接开到公网等于把写权限交出去。
 
----
+所以要让手机上的 AI app 读到同一份记忆，前面加一层只读网关：
 
-## v2.2 新增：检索质量强化
+```bash
+openssl rand -hex 32 > ~/.config/recallnest/gateway-token
+chmod 600 ~/.config/recallnest/gateway-token
 
-v2.1 加入了哲学记忆行为；v2.2 补齐前沿扫描（ACC、PI-LLM、TSM）发现的最后三个引擎层空白。
+bun run api        # 本机 API，:4318
+bun run gateway    # 只读网关，:8791 → 转发到 :4318
+```
 
-- **记忆置信度元标签** *（ACC / 双过程不确定性量化）* —— 每条记忆携带结构化 `ConfidenceMetadata`（分数 + 可靠性层级：`direct` 用户亲述 / `inferred` LLM 推断 / `hearsay` 二手转述）。写入时根据 source 自动赋值（manual=0.9, agent=0.7, conversation_import=0.5）。检索评分加权置信度。`resume_context` 对低置信条目标注 `[低置信]`。
+网关只放行读路由（`/recall`、`/search`、`/stats`、`/health`），**任何写路由一律 404**；Bearer token 常量时间比较、每分钟限流、请求与响应都有大小上限。把它放到隧道后面（Tailscale Serve/Funnel、Cloudflare Tunnel 等）即可从手机访问。
 
-- **干扰检测 + 主动遗忘门** *（PI-LLM / SleepGate）* —— 语义聚簇检测识别竞争检索的近重复记忆群。增强版 RIF 每簇仅保留 top-K（默认 3），多余的降权 50% 而非删除。写入时预警：scope 内累积 ≥5 条高相似活跃记忆时，最弱的标记 `pending_review`。`data_checkup` 报告干扰密度。
+```bash
+curl -X POST https://<你的隧道地址>/recall \
+  -H "Authorization: Bearer $(cat ~/.config/recallnest/gateway-token)" \
+  -H 'content-type: application/json' \
+  -d '{"query":"上次那个部署问题怎么解决的","limit":3,"allScopes":true}'
+```
 
-- **时间有效性窗口** *（TSM / TiMem / Zep）* —— `store_memory` 接受 `validUntil`（过期时间）和 `eventTime`（事件发生时间）。`search_memory` 支持 `validAt`（时间点查询）和 `includeExpired`（降权 80% 而非隐藏）。auto-GC 对过期记忆施加 2 倍衰减加速。
+可选：配 `RECALLNEST_GATEWAY_FILE_ROOTS="notes=/abs/path,wiki=/abs/path"` 会多出一个 `GET /files/search`，用 ripgrep 只读检索你指定的 markdown 目录（查询词以 argv 传入，不经过 shell）。不配就没有这个路由。
 
-- **Usage-adjusted Auto-GC** *（默认关闭）* —— `RECALLNEST_USAGE_DECAY=true` 且建构式检索 use 信号开启时，GC 专用分支才会对 cold 记忆的 frequency 项打折；在线检索排序不读取这个分支。
+> 网关默认也只绑 `127.0.0.1`——把它暴露到公网是隧道的职责，请自行评估风险。
 
----
+作者用这条路把 iPhone 上的 [OpenMinis](https://github.com/OpenMinis/OpenMinis) 接了上来：手机 app 经 Tailscale Funnel 打到网关，能查到同一份记忆库。有意思的是它查回的是**它自己**的历史——那些对话导出后回流、被索引，于是一个每次冷启动的手机 agent 有了跨会话的记忆。
+
+
+
+## 快速开始
+
+### 方式 A：Claude Code Plugin（推荐）
 
-## v2.3 新增：Connector 生态 + 数据源健康
+```bash
+/plugin marketplace add AliceLJY/recallnest
+/plugin install recallnest@AliceLJY
+```
 
-v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康监控，把 RecallNest 开放给外部数据源。
+RecallNest 随 Claude Code 自动启动，无需手动配置 MCP。
 
-- **Connector-v1 标准** *（GB-2）* —— 一套 JSON 格式（`ConnectorOutputV1`），任何外部脚本都可以输出。Obsidian 笔记、邮件、RSS、日志文件——标准化一次，走完整的 dedup/embed/extract 管线入库。规范见 [`docs/connector-spec.md`](docs/connector-spec.md)，适配器骨架见 [`connectors/examples/`](connectors/examples/)（email、logs、RSS）。
+安装时 Claude Code 会提示填写 Jina API key。密钥由 Claude Code 的敏感插件配置保存；自动生成的配置和 LanceDB 数据库则放在插件持久数据目录，不会混进按版本更新的插件缓存。
 
-- **Obsidian Vault 接入** *（GB-1）* —— 官方 Obsidian 连接器：扫描 `.md` 文件，提取 frontmatter + wikilink，文件夹结构映射为 tag。一条命令：`lm ingest --obsidian /path/to/vault`。
+> Claude Code 插件与 npm 包共用同一个发布版本，并随版本发布同步更新。
+>
+> **前置要求：** [Bun](https://bun.sh)。首次启动自动安装依赖。
 
-- **数据源健康监控** *（GB-3）* —— 每次 connector ingest 写心跳到 `data/source-heartbeat.json`。`data_checkup` 标记过期数据源（>7 天 warning，>30 天 error）。`doctor --ci` 按数据源展示心跳摘要（如"obsidian: 2h ago"）。
+### 方式 B：npm 安装
 
----
+```bash
+npx recallnest --help          # 直接运行
+# 或
+npm install -g recallnest      # 全局安装
+recallnest doctor
+```
 
-## 架构
+支持 Node.js 22+（通过 tsx）或 Bun，无需 clone 仓库。
 
+### 方式 C：手动安装
+
+```bash
+git clone https://github.com/AliceLJY/recallnest.git
+cd recallnest
+bun install
+cp config.json.example config.json
+cp .env.example .env
+# 编辑 .env → 填入 JINA_API_KEY
 ```
-┌──────────────────────────────────────────────────────────┐
-│                       客户端层                            │
-├──────────┬──────────┬──────────┬──────────────────────────┤
-│ Claude   │ Gemini   │ Codex    │ 自定义 Agent / curl      │
-│ Code     │ CLI      │          │                          │
-└────┬─────┴────┬─────┴────┬─────┴──────┬──────────────────┘
-     │          │          │            │
-     └──── MCP (stdio) ───┘     HTTP API（端口 4318）
-                │                       │
-                ▼                       ▼
-┌──────────────────────────────────────────────────────────┐
-│                      集成层                               │
-│  ┌─────────────────────┐  ┌────────────────────────────┐ │
-│  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  43 个工具           │  │  21 个端点                  │ │
-│  └─────────┬───────────┘  └──────────┬─────────────────┘ │
-└────────────┼─────────────────────────┼───────────────────┘
-             └──────────┬──────────────┘
-                        ▼
-┌──────────────────────────────────────────────────────────┐
-│                      核心引擎                             │
-│                                                           │
-│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐ │
-│  │ 检索器      │  │ 分类器      │  │ 上下文编排器         │ │
-│  │（向量 +     │  │（6 类分类） │  │（resume_context）   │ │
-│  │ BM25 + RRF）│  │            │  │                      │ │
-│  └────────────┘  └────────────┘  └──────────────────────┘ │
-│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐ │
-│  │ 衰减引擎    │  │ 冲突引擎    │  │ 捕获引擎             │ │
-│  │（Weibull） │  │（审计 +     │  │（evidence → durable）│ │
-│  │            │  │  合并）     │  │                      │ │
-│  └────────────┘  └────────────┘  └──────────────────────┘ │
-└──────────────────────────┬───────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────┐
-│                      存储层                               │
-│  ┌─────────────────────┐  ┌────────────────────────────┐ │
-│  │ LanceDB             │  │ Jina Embeddings v5         │ │
-│  │（向量 + 列式存储）   │  │（1024 维，任务感知）       │ │
-│  └─────────────────────┘  └────────────────────────────┘ │
-└──────────────────────────────────────────────────────────┘
+
+### 启动服务
+
+```bash
+bun run api
+# → RecallNest API running at http://localhost:4318
 ```
 
-### 内部设计
+### 试一下
 
-- **L0 / L1 / L2 动态折叠** —— 每条记忆存储 3 个粒度层（一句话 / 要点概要 / 完整内容）；检索时根据相关性分数和 token 预算动态选择返回哪个层级
-- **Weibull 衰减 + 情绪调制** —— 记忆沿参数化 Weibull 曲线衰减；情绪显著性可额外延长半衰期最高 30%
-- **向量预筛 + LLM 去重** —— 90% 的去重决策用低成本余弦相似度（≥ 0.92）；仅临界情况调用 LLM 判断
-- **类别分化合并策略** —— `profile` 和 `preferences` 采用冲突合并（新版覆盖）；`events` 和 `cases` 采用追加（保留历史）
-- **展示分 vs 淘汰分双轨制** —— 检索使用双轨评分：tier floor 防止核心记忆被淘汰，decay boost 让新鲜记忆临时浮现而不永久挤掉稳定记忆
+```bash
+# 存入一条记忆
+curl -X POST http://localhost:4318/v1/store \
+  -H "Content-Type: application/json" \
+  -d '{"text": "用户偏好暗色模式", "category": "preferences"}'
 
-> 完整架构详解：[`docs/architecture.md`](docs/architecture.md)
+# 搜索记忆
+curl -X POST http://localhost:4318/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query": "用户偏好"}'
+
+# 查看统计
+curl http://localhost:4318/v1/stats
+```
+
+### 接入终端
+
+```bash
+bash integrations/claude-code/setup.sh
+bash integrations/agy/setup.sh
+bash integrations/codex/setup.sh
+```
+
+每个脚本会同时安装 MCP 和 continuity 规则，新窗口自动触发 `resume_context`。
+
+### 索引已有对话
+
+```bash
+bun run src/cli.ts ingest --source all
+bun run seed:continuity
+bun run src/cli.ts doctor
+```
 
 ---
 
+## 图片：可寻址，而不是被编码
+
+对话里有图，而文本记忆层没有。通常的答案是上一个多模态 embedding 模型，把每张图编码进
+和文字同一个向量空间。那个答案对相册和商品库是对的，放在这里却是错的形状，理由很便宜：
+**在对话里，一张图几乎从不孤零零地出现。** 它总被"你看这个报错"包着，而紧跟其后的回复
+通常已经描述了图里是什么。图周围的文字，本来就是这张图的索引。缺的从来不是对像素做语义
+检索，而是**知道那儿有一张图**。
+
+所以 RecallNest 不编码图片。它只记下**这条记忆所属的 session 里有几张图**，剩下的交给你判断
+要不要去翻原始对话。图的含义在需要的那一刻、由当时在问的那个模型现场解读。
+
+代价值得说清楚：**不需要多模态模型，不重新 embedding，不存图片，不改动任何一个向量。**
+给存量的 21,319 条记忆补上这个标记，只动了 metadata。
+
+这里面有两个不那么显然的选择，而且两次的第一版都是错的。
+
+### 粒度取 session，是故意的
+
+标记数的是整个 session，不是单轮——比第一眼该有的粒度更粗，而粗正是重点。
+
+一轮如果只有一张截图、几乎没有文字，它根本过不了长度闸，压根没进过库。在真实对话上实测，
+**含用户贴图的轮次里有 12.5% 是整轮被丢掉的**——而且丢的恰恰是最值钱的那些：七张截图一个字
+没配，或者「操作步骤在这里」配一张图、而那张图**就是**步骤本身。轮次级的标记，对最该被找到的
+那批图**无处可挂**。session 级的标记会落到同一个 session 里**其他**进了库的记忆上，而那些才是
+搜索会捞出来的东西。
+
+代价不加掩饰：同一个 session 的每条记忆都带同一个数字，所以那些图未必和你眼前这一条有关。
+输出里写的是 `in this session` 而不是 `in this memory`，就是为了这个。
+
+### 分成两类，因为它们回答的不是同一个问题
+
+| 类别 | 是什么 | 回答什么问题 |
+|---|---|---|
+| user-pasted | 人贴进消息里的图 | *我发过的那张截图在哪？* |
+| agent-made | 这个 session 产生的其余所有图 | *那个页面当时长什么样？我当时生成的图是哪张？* |
+
+只留第一类很诱人——人翻自己的记忆，想找的是自己的截图。但一个 agent 回溯自己干过的活，
+要的是第二类：它画的示意图、它截的渲染结果、它为一篇文章配的插图。**1,767 个带图 session 里，
+有 1,103 个一张人贴的图都没有。** 只留第一类，这些 session 就全哑了——而它们恰恰是 agent
+做了大量视觉工作的那些。
+
+### 第二类是补集，不是清单
+
+第一版的实现是靠**枚举**定义"AI 产的图"：`tool_result` 里的、`payload.output` 里的、
+`tool.result` 里的。每一个位置都真实存在，这份清单依然是错的，因为**图片可能出现的方式只会
+越来越多**，而枚举会悄无声息地漏掉它没预料到的那一种。
+
+所以第二类改成了补集：数出这条记录里所有的图片信号，减去能明确认定为"人贴的"，剩下的
+一律归入，不问它从哪儿来。在 9,619 份对话记录上：
+
+| | 枚举 | 补集 |
+|---|---|---|
+| AI 产的图 | 5,812 | **10,938** |
+| 有图的 session | 1,507 | **1,767** |
+| 人贴的图 | 1,629 | 1,629 |
+
+**枚举漏掉了 5,126 张图和 376 个 session**，接近一半。漏得最多的是**生图**——它待在那份清单
+知道的两个容器之外。而人贴的图在两种口径下数字完全一致，这正是关键的校验点：放宽第二类
+没有污染精确的第一类。有一条回归测试钉住这件事：它喂给解析器一个源码里从未出现过的
+`image_generation_call`，断言它落进第二类；在枚举式实现下那条测试必红。
+
+一点诚实的说明：补集数的是*信号*，不是确认过的图片张数。一次生图可能同时留下调用和完成
+两条记录，被数成两张。这个方向是刻意选的——它要回答的是"这儿有没有东西可看"，而不是
+"到底几张"。
+
 ## 接口
 
 RecallNest 提供两种接口：
 
-- **MCP** —— 给任意 MCP 客户端使用：Claude Code、Codex、Kimi、Antigravity、Gemini CLI（原生工具访问）
+- **MCP（stdio）** —— 给任何能启动一条命令的客户端：CLI agent（Claude Code、Codex、Kimi、Antigravity）与能填 MCP 配置的 GUI app（豆包、Cherry Studio、ChatBox）
 - **HTTP API** —— 给自定义 Agent、SDK 应用和任何 HTTP 客户端使用
 
 ### Agent 框架示例
@@ -338,7 +364,7 @@ RecallNest 提供两种接口：
 ---
 
 <details>
-<summary><strong>MCP 工具（43 个）</strong></summary>
+<summary><strong>MCP 工具（44 个）</strong></summary>
 
 | 工具 | 说明 |
 |------|------|
@@ -350,6 +376,7 @@ RecallNest 提供两种接口：
 | `store_case` | 存储问题-方案对 |
 | `promote_memory` | 显式升级 evidence 为持久记忆 |
 | `promote_scan` | 扫描近期 evidence，自动晋升合格记忆为持久存储 |
+| `promote_synthesis` | 扫描 dream 合成出的结论，把自身证据集撑得住的那些晋升为持久记忆 |
 | `list_conflicts` | 列出或查看冲突候选 |
 | `audit_conflicts` | 汇总过期/升级的冲突优先级 |
 | `escalate_conflicts` | 预览或应用冲突升级元数据 |
@@ -462,6 +489,46 @@ bun run src/cli.ts doctor
 
 ---
 
+## Web UI
+
+<p align="center">
+  <img src="assets/dashboard.png" alt="RecallNest Dashboard" width="800" />
+  <br><em>Dashboard —— 总量、类别分布、健康评分、增长趋势一目了然。</em>
+</p>
+
+<p align="center">
+  <img src="assets/screenshots/ui-full.png" alt="RecallNest Search Workbench" width="800" />
+  <br><em>Search Workbench —— 混合检索 + Topic Tag 过滤 + 4 套检索策略 + Skills 浏览 + 资产管理。</em>
+</p>
+
+<p align="center">
+  <img src="assets/knowledge-graph.png" alt="RecallNest Knowledge Graph" width="800" />
+  <br><em>Knowledge Graph —— 交互式力导向图，语义桥接揭示跨域隐藏关联。</em>
+</p>
+
+```bash
+bun run src/ui-server.ts
+# → http://localhost:4317
+```
+
+---
+
+## 最近更新
+
+**v3.0** 把运行时下限提到 **Node 22**（本次唯一的破坏性变更，Bun 用户不受影响），
+并给"合成出来的结论"开了一条通往稳定记忆的路：`dream` 产出的洞察现在可以凭它自己
+那套已验证的证据被提升，而不是永远卡在证据层、下游谁也不敢依赖。
+
+同批还修了一个限流回复引发的无限请求风暴——实测在一个正让我们慢下来的接口上
+五秒打了六万多次请求。它是被新加的 HTTP 契约测试抓出来的：那些测试让真实的客户端类
+去打一个本地回环服务，而不是把 SDK 打桩糊过去。
+
+已有的 LanceDB 数据原地打开，不需要导出导入。
+
+**完整变更历史（v3.0 到 v1.0，含每个版本的升级说明）在
+[CHANGELOG.md](CHANGELOG.md)。**
+
+
 ## 多语言支持
 
 RecallNest 开箱即用支持英文。如需多语言记忆（中文、日文、泰文及 20+ 种语言），安装 [babel-memory](https://github.com/AliceLJY/babel-memory) 及所需语言包：
@@ -498,7 +565,7 @@ RecallNest 持续维护中。所有主要架构阶段已完成——完整路线
 RecallNest 起源于 [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) 的 fork，共享混合检索、衰减建模、记忆即系统的核心理念。关键区别：
 
 - **memory-lancedb-pro** 是 OpenClaw 插件——为单个 OpenClaw Agent 添加长期记忆。
-- **RecallNest** 是独立记忆层——通过 MCP + HTTP API 同时服务任意 MCP 客户端（Claude Code、Codex、Kimi、Antigravity、Gemini CLI），内建会话连续性、结构化资产和冲突管理。
+- **RecallNest** 是独立记忆层——通过 MCP + HTTP API 同时服务 CLI agent、GUI 聊天 app 与纯 HTTP 调用方，内建会话连续性、结构化资产和冲突管理。
 
 ## 致谢
 
@@ -518,13 +585,13 @@ RecallNest 起源于 [memory-lancedb-pro](https://github.com/CortexReach/memory-
 | 项目 | 说明 |
 |------|------|
 | [babel-memory](https://github.com/AliceLJY/babel-memory) | BM25 多语言预处理——27+ 种语言，零依赖 |
-| [content-alchemy](https://github.com/AliceLJY/content-alchemy) | 5 阶段 AI 写作管线 |
-| [content-publisher](https://github.com/AliceLJY/content-publisher) | 图片生成 + 排版 + 微信公众号发布 |
-| [wechat-ai-bridge](https://github.com/AliceLJY/wechat-ai-bridge) | 在微信中运行 Claude Code / Codex / Gemini |
-| [telegram-ai-bridge](https://github.com/AliceLJY/telegram-ai-bridge) | Telegram Bot：Claude、Codex、Gemini |
+| content-alchemy *(private)* | 5 阶段 AI 写作管线 |
+| content-publisher *(private)* | 图片生成 + 排版 + 微信公众号发布 |
+| [wechat-ai-bridge](https://github.com/AliceLJY/wechat-ai-bridge) | 在微信中运行 Claude Code / Codex |
+| [telegram-ai-bridge](https://github.com/AliceLJY/telegram-ai-bridge) | Telegram Bot：Claude、Codex、Agy、Kimi |
 | [telegram-cli-bridge](https://github.com/AliceLJY/telegram-cli-bridge) | Telegram CLI 桥接 Gemini CLI |
 | [openclaw-tunnel](https://github.com/AliceLJY/openclaw-tunnel) | Docker ↔ 宿主机 CLI 桥接 |
-| [openclaw-config](https://github.com/AliceLJY/openclaw-config) | OpenClaw Bot 配置与记忆备份 |
+| openclaw-config *(private)* | OpenClaw Bot 配置与记忆备份 |
 | [digital-clone-skill](https://github.com/AliceLJY/digital-clone-skill) | 从语料构建数字分身 |
 | [claude-code-studio](https://github.com/AliceLJY/claude-code-studio) | Claude Code 多会话协作平台 |
 | [cc-genius](https://github.com/AliceLJY/cc-genius) | Web 版 Claude 客户端（PWA）—— 自托管，iPad 可用 |

package/config.json.example

@@ -25,6 +25,11 @@
       "path": "auto",
       "glob": "*.md",
       "description": "Claude Code memory files"
+    },
+    "minis": {
+      "path": "~/Desktop/minis-outbox/ingest",
+      "glob": "*.jsonl",
+      "description": "Minis (iPhone) conversations, dropped here by the agent itself"
     }
   },
   "retrieval": {
@@ -36,6 +41,8 @@
     "hardMinScore": 0.3
   },
   "scopeRelations": {
-    "project:example-a": ["project:example-b"]
+    "project:example-a": [
+      "project:example-b"
+    ]
   }
 }

package/docs/api-reference.md

@@ -298,7 +298,7 @@ Each memory item supports:
       "source": "agent",
       "storedAt": "2026-03-16T02:11:00.000Z",
       "disposition": "stored",
-      "canonicalKey": "entities:recallnest-is-the-shared-memory-layer-for-claude-code-codex-and-gemini-cli"
+      "canonicalKey": "entities:recallnest-is-the-shared-memory-layer-for-claude-code-codex-and-agy"
     }
   ]
 }

package/integrations/README.md

@@ -11,7 +11,7 @@ Best for AI coding assistants that support Model Context Protocol natively.
 | Tool | Setup | What it does |
 |------|-------|-------------|
 | [Claude Code](claude-code/) | `setup.sh` adds MCP to `~/.claude.json` and installs rules in `~/.claude/CLAUDE.md` | Proactive continuity plus shared recall |
-| [Gemini CLI](gemini-cli/) | `setup.sh` adds MCP to `~/.gemini/settings.json` and installs rules in `~/.gemini/GEMINI.md` | Same MCP tools, shared index, continuity prompts |
+| [Antigravity CLI (agy)](agy/) | `setup.sh` adds MCP to `~/.gemini/config/mcp_config.json` and installs rules in `~/.gemini/config/GEMINI.md` | Same MCP tools, shared index, continuity prompts |
 | [Codex](codex/) | `setup.sh` adds MCP to `~/.codex/config.toml` and installs rules in `~/.codex/AGENTS.md` | Same MCP tools, shared index, continuity prompts |
 
 All three share the same LanceDB index, and all three setup scripts now install a managed RecallNest continuity block so fresh windows are instructed to call `resume_context` and `checkpoint_session` at the right times.