recallnest 1.4.1 → 2.2.1

package/README_CN.md

@@ -12,7 +12,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Bun](https://img.shields.io/badge/Runtime-Bun-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-29_tools-blue)](https://modelcontextprotocol.io)
+[![MCP](https://img.shields.io/badge/MCP-41_tools-blue)](https://modelcontextprotocol.io)
+[![Tests](https://img.shields.io/badge/Tests-1428_pass-brightgreen)](https://github.com/AliceLJY/recallnest)
 [![CC Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://github.com/AliceLJY/recallnest)
 
 [English](README.md) | **简体中文** | [Roadmap](ROADMAP.md)
@@ -23,52 +24,22 @@
 
 ## 为什么需要 RecallNest？
 
-大多数编程 Agent 一开新窗口就失忆。更糟的是，你的历史上下文分散在三个终端里，互相不通。
+编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Gemini CLI 三个终端里，互相不通。
 
-### 没有 RecallNest —— 每个窗口从零开始：
+RecallNest 的解法：**一个 LanceDB 驱动的记忆层，三个终端共读共写**。一个窗口存入的上下文，另一个窗口自动召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——不是简单的日志堆积。
 
-> **你（Claude Code）：**"Docker 配置在 `/opt/app/config.json`，用 4318 端口。"
->
-> *（切到 Codex）*
->
-> **你：**"配置路径是……等下让我再找找。"😤
->
-> *（第二天，新开 Claude Code 窗口）*
->
-> **你：**"这个 bug 上周刚修过！方案是……"
->
-> **Agent：**"我没有之前会话的上下文。"🤷
+### 基准测试：LongMemEval (ICLR 2025)
 
-### 有了 RecallNest —— 上下文无缝延续：
+在 6 项记忆能力、500 个问题上评估（[评测方法](https://arxiv.org/abs/2407.15168)）：
 
-> **你（Claude Code）：**"Docker 配置在 `/opt/app/config.json`，用 4318 端口。"
->
-> *（切到 Codex —— 同一套记忆层）*
->
-> **Agent：**（自动召回项目实体）"使用 `/opt/app/config.json`，端口 4318。"✅
->
-> *（第二天，新窗口）*
->
-> **Agent：**（resume_context 自动触发）"接续昨天 —— Docker 端口冲突已通过……解决。"✅
+| | RecallNest | 纯向量基线 | 差值 |
+|---|---|---|---|
+| 总体准确率 | **29.6%** | 24.2% | **+5.4pp** |
+| 用户事实 | **64.3%** | 52.9% | +11.4pp |
+| 知识更新 | **43.6%** | 42.3% | +1.3pp |
+| 弃权率 | **55.6%** | 67.8% | **-12.2pp** |
 
-核心差异：**三个终端共享一套记忆**，上下文跨窗口存活。
-
-### 能力一览
-
-| | 能力 |
-|---|---|
-| **CC Plugin** | 一行命令装入 Claude Code，无需手动配置 MCP |
-| **共享索引** | Claude Code、Codex、Gemini CLI 共用同一个 LanceDB 存储 |
-| **双通道接入** | MCP（stdio）给 CLI 工具 + HTTP API 给自定义 Agent |
-| **一键接入** | 集成脚本同时安装 MCP 和 continuity 规则 |
-| **混合检索** | 向量 + BM25 + 重排序 + Weibull 衰减 + 分层提升 |
-| **会话连续性** | `checkpoint_session` + `resume_context` 跨窗口恢复 |
-| **Workflow Observation** | 专门的 append-only 工作流观测层，不混入普通 memory |
-| **结构化资产** | Pin、Brief、Distill —— 不只是原始日志 |
-| **显式升级** | Evidence → Durable Memory，带冲突守卫和合并决议 |
-| **6 类记忆** | profile、preferences、entities、events、cases、patterns |
-| **4 套检索策略** | default、writing、debug、fact-check —— 按任务类型调优 |
-| **多源导入** | 导入三个终端已有的对话历史 |
+**全部 6 项胜出或持平**，无任何退步。混合检索管线（BM25 + 向量 + 时效性 + RIF 去重）比纯向量搜索多召回 12.2% 的相关上下文。
 
 ---
 
@@ -140,6 +111,117 @@ 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
+```
+
+---
+
+## 核心能力
+
+### 接入与安装
+
+| 能力 | 说明 |
+|---|---|
+| **CC Plugin** | 一行命令装入 Claude Code，无需手动配置 MCP |
+| **共享索引** | Claude Code、Codex、Gemini CLI 共用同一个 LanceDB 存储 |
+| **双通道接入** | MCP（stdio）给 CLI 工具 + HTTP API 给自定义 Agent |
+| **一键接入** | 集成脚本同时安装 MCP 和 continuity 规则 |
+
+### 检索与连续性
+
+| 能力 | 说明 |
+|---|---|
+| **混合检索** | 6 通道：向量 + BM25 + L0/L1/L2 多向量 + KG 图（PPR） |
+| **4 套检索策略** | default、writing、debug、fact-check —— 按任务类型调优 |
+| **会话连续性** | `checkpoint_session` + `resume_context`（full/light/summary 三种模式）+ 仓库状态守卫 |
+| **会话蒸馏** | 3 层对话压缩：微缩 → LLM 结构化摘要 → 知识提取 |
+| **对话导入** | 支持 Claude Code、Claude.ai、ChatGPT、Slack、纯文本 |
+| **Topic Tags** | scope 内 topic 分区，自动检测，搜索时可过滤 |
+
+### 记忆生命周期与治理
+
+| 能力 | 说明 |
+|---|---|
+| **记忆演化** | Supersede 链、衰减评分、LLM 重要性、聚合、归档 |
+| **显式升级** | Evidence → Durable Memory，带冲突守卫、合并决议、审计日志 |
+| **隐私分级** | 4 级（`ephemeral` / `private` / `durable` / `shared`）+ 级联遗忘 |
+| **准入控制** | 写入时门控：噪音过滤、重要性下限、去重、限流 |
+| **Memory Lint** | 矛盾、重复、过期、孤儿检测 + 健康评分 |
+| **离线整合** | `dream` 命令：聚类、合并、修剪积累的记忆 |
+
+### 推理与结构
+
+| 能力 | 说明 |
+|---|---|
+| **Knowledge Graph** | 实体关系图 + PPR 算法，支持多跳问题 |
+| **建构式检索** | 多源候选扩展 + 溯源锚定的上下文重建 |
+| **叙事架构** | 三层自传式元数据（生命阶段 → 一般事件 → 具体事件） |
+| **Skill Memory** | 存储、检索、自动提升来自重复模式的可执行技能 |
+| **预测式提醒** | 行为信号预测引擎，主动浮现"你可能需要这个" |
+| **6 类记忆** | profile、preferences、entities、events、cases、patterns —— 类别分化合并策略 |
+
+### 可视化与运维
+
+| 能力 | 说明 |
+|---|---|
+| **Dashboard** | Web UI 首页：统计卡片、类别分布、增长趋势、健康概览 |
+| **Workflow Observation** | 专门的 append-only 工作流观测层，不混入普通 memory |
+| **结构化资产** | Pin、Brief、Distill —— 不只是原始日志 |
+| **Data Checkup** | 记忆存储数据质量健康检查 |
+| **导出图谱** | 导出交互式 HTML 知识图谱可视化 |
+| **批量操作** | 单次调用存储最多 20 条记忆，自带去重 |
+
+---
+
+## v2.1 新增：记忆哲学驱动的架构升级
+
+v2.0 建立了完整的记忆操作平台；v2.1 加入了记忆哲学驱动的记忆行为。
+
+来自 9 个记忆哲学研究维度的 5 项工程升级：
+
+- **情绪感知衰减** *（情感记忆理论）* —— 带有强烈情绪的记忆衰减慢 20-30%。基于关键词的情绪检测计算 `salience`（记忆显著性），注入 Weibull 半衰期公式和重新平衡的 4 因子演化评分。零 LLM 成本。
+
+- **记忆伦理层** *（遗忘权 / GDPR 第 17 条）* —— 四级隐私：`ephemeral`（临时）/ `private`（私密）/ `durable`（持久）/ `shared`（共享）。级联遗忘引擎贯穿 KG 三元组、演化链、Pin 资产和摘要。完整审计日志。`forget_memory` MCP 工具支持 Agent 驱动的删除。
+
+- **自传叙事架构** *（叙事身份理论 / Conway 三层模型）* —— 记忆标注 `生命阶段 → 一般事件 → 具体事件` 层级，正交于现有 6 类别。检索自动拉取叙事兄弟。上下文渲染按生命阶段分组。支持中英文的规则式标注器。
+
+- **建构式检索** *（模拟理论 / Michaelian）* —— 不再返回原始存储文本，而是从扩展候选集（KG 邻居 + 演化链 + 聚类成员 + 叙事兄弟）中重建上下文。Source-map 语义覆盖率替代词汇重叠。矛盾检测与标记。
+
+- **预测式前瞻记忆** *（精神时间旅行 / Tulving）* —— 启发式预测引擎从行为信号中浮现"你可能需要这个"提醒：过期的 checkpoint 待办事项、被纠正的工作流观察、高频休眠记忆和未覆盖的查询主题。零 LLM 成本。7 天未接受自动过期。
+
+---
+
+## v2.2 新增：检索质量强化
+
+v2.1 加入了哲学记忆行为；v2.2 补齐前沿扫描（ACC、PI-LLM、TSM）发现的最后三个引擎层空白。
+
+- **记忆置信度元标签** *（ACC / 双过程不确定性量化）* —— 每条记忆携带结构化 `ConfidenceMetadata`（分数 + 可靠性层级：`direct` 用户亲述 / `inferred` LLM 推断 / `hearsay` 二手转述）。写入时根据 source 自动赋值（manual=0.9, agent=0.7, conversation_import=0.5）。检索评分加权置信度。`resume_context` 对低置信条目标注 `[低置信]`。
+
+- **干扰检测 + 主动遗忘门** *（PI-LLM / SleepGate）* —— 语义聚簇检测识别竞争检索的近重复记忆群。增强版 RIF 每簇仅保留 top-K（默认 3），多余的降权 50% 而非删除。写入时预警：scope 内累积 ≥5 条高相似活跃记忆时，最弱的标记 `pending_review`。`data_checkup` 报告干扰密度。
+
+- **时间有效性窗口** *（TSM / TiMem / Zep）* —— `store_memory` 接受 `validUntil`（过期时间）和 `eventTime`（事件发生时间）。`search_memory` 支持 `validAt`（时间点查询）和 `includeExpired`（降权 80% 而非隐藏）。auto-GC 对过期记忆施加 2 倍衰减加速。
+
+---
+
 ## 架构
 
 ```
@@ -157,7 +239,7 @@ bun run src/cli.ts doctor
 │                      集成层                               │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  29 个工具           │  │  19 个端点                  │ │
+│  │  41 个工具           │  │  21 个端点                  │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -172,7 +254,7 @@ bun run src/cli.ts doctor
 │  └────────────┘  └────────────┘  └──────────────────────┘ │
 │  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐ │
 │  │ 衰减引擎    │  │ 冲突引擎    │  │ 捕获引擎             │ │
-│  │（Weibull） │  │（审计 +    │  │（evidence → durable）│ │
+│  │（Weibull） │  │（审计 +     │  │（evidence → durable）│ │
 │  │            │  │  合并）     │  │                      │ │
 │  └────────────┘  └────────────┘  └──────────────────────┘ │
 └──────────────────────────┬───────────────────────────────┘
@@ -181,164 +263,117 @@ bun run src/cli.ts doctor
 │                      存储层                               │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │ LanceDB             │  │ Jina Embeddings v5         │ │
-│  │（向量 + 列式存储）    │  │（1024 维，任务感知）        │ │
+│  │（向量 + 列式存储）   │  │（1024 维，任务感知）       │ │
 │  └─────────────────────┘  └────────────────────────────┘ │
 └──────────────────────────────────────────────────────────┘
 ```
 
+### 内部设计
+
+- **L0 / L1 / L2 动态折叠** —— 每条记忆存储 3 个粒度层（一句话 / 要点概要 / 完整内容）；检索时根据相关性分数和 token 预算动态选择返回哪个层级
+- **Weibull 衰减 + 情绪调制** —— 记忆沿参数化 Weibull 曲线衰减；情绪显著性可额外延长半衰期最高 30%
+- **向量预筛 + LLM 去重** —— 90% 的去重决策用低成本余弦相似度（≥ 0.92）；仅临界情况调用 LLM 判断
+- **类别分化合并策略** —— `profile` 和 `preferences` 采用冲突合并（新版覆盖）；`events` 和 `cases` 采用追加（保留历史）
+- **展示分 vs 淘汰分双轨制** —— 检索使用双轨评分：tier floor 防止核心记忆被淘汰，decay boost 让新鲜记忆临时浮现而不永久挤掉稳定记忆
+
 > 完整架构详解：[`docs/architecture.md`](docs/architecture.md)
 
 ---
 
-## 集成方式
+## 接口
 
-RecallNest 提供两条接入路径：
+RecallNest 提供两种接口：
 
-- **MCP** —— 给 Claude Code、Gemini CLI、Codex 等终端工具使用
-- **HTTP API** —— 给自定义 Agent 和 SDK 应用使用
+- **MCP** —— 给 Claude Code、Gemini CLI、Codex 使用（原生工具访问）
+- **HTTP API** —— 给自定义 Agent、SDK 应用和任何 HTTP 客户端使用
 
 ### Agent 框架示例
 
-示例位于 [`integrations/examples/`](integrations/examples/)：
+示例代码位于 [`integrations/examples/`](integrations/examples/)：
 
-| 框架 | 示例文件 | 语言 |
-|------|---------|------|
+| 框架 | 示例 | 语言 |
+|------|------|------|
 | [Claude Agent SDK](integrations/examples/claude-agent-sdk/) | `memory-agent.ts` | TypeScript |
 | [OpenAI Agents SDK](integrations/examples/openai-agents-sdk/) | `memory-agent.py` | Python |
 | [LangChain](integrations/examples/langchain/) | `memory-chain.py` | Python |
 
 ---
 
-## 核心特性
-
-### 混合检索
-
-```
-查询 → 向量嵌入 ──┐
-                  ├── 混合融合 → 重排序 → Weibull 衰减 → 过滤 → Top-K
-查询 → BM25 全文 ─┘
-```
-
-- **向量搜索** —— 基于 LanceDB ANN 的语义相似度匹配
-- **BM25 全文搜索** —— 基于 LanceDB FTS 的精确关键词匹配
-- **混合融合** —— 向量 + BM25 组合评分
-- **重排序** —— Jina 交叉编码器重排
-- **衰减 + 分层** —— Weibull 时间衰减模型，Core / Working / Peripheral 三层
-
-### 会话连续性
-
-跨窗口工作流的核心能力：
-
-- **`checkpoint_session`** —— 快照当前工作状态（决策、未完成项、下一步）
-- **repo-state 守卫** —— 保存 checkpoint 前会清洗 `git status` / modified-file 文本，避免易变 repo 状态污染后续 handoff
-- **`resume_context`** —— 从 checkpoint + 长期记忆 + pin 编排启动上下文
-- **托管规则** —— 集成脚本自动安装 continuity 规则，新窗口自动触发 `resume_context`
-
-### Workflow Observation
-
-RecallNest 现在把 workflow observation 放在专门的 append-only store，而不是硬塞进普通记忆索引：
-
-- **`workflow_observe`** —— 记录 `resume_context`、`checkpoint_session` 等 workflow primitive 是成功、失败、被纠正，还是被漏掉
-- **`workflow_health`** —— 汇总单个 workflow 的 7 天 / 30 天健康度，或输出退化 workflow dashboard
-- **`workflow_evidence`** —— 打包最近 issue observation、top signals 和后续建议，方便做规则或测试收口
-
-这些记录默认落在 `data/workflow-observations`，不属于那 6 类 memory，也不会被 `resume_context` 当成 stable recall 回注。
-
-### 记忆升级与冲突决议
-
-原始 transcript 不会静默变成长期记忆：
-
-- **Evidence → Durable** —— 显式 `promote_memory`，带 `canonicalKey` 和来源追踪
-- **冲突守卫** —— canonicalKey 碰撞会生成冲突候选项
-- **决议方式** —— 保留已有、接受新的、或合并 —— 带建议和聚类视图
-- **审计 + 升级** —— `conflicts audit --export` 输出运营审查报告
-
-### 检索策略
-
-| 策略 | 适用场景 | 偏向 |
-|------|---------|------|
-| `default` | 日常回忆 | 均衡 |
-| `writing` | 写作和灵感挖掘 | 语义更宽，较旧内容也保留 |
-| `debug` | 报错、命令、修复 | 关键词优先，偏近期 |
-| `fact-check` | 证据查找 | 阈值更严，偏精确匹配 |
-
-### 记忆分类
-
-| 分类 | 说明 | 策略 |
-|------|------|------|
-| `profile` | 用户身份和背景 | 合并 |
-| `preferences` | 习惯、风格、偏好 | 合并 |
-| `entities` | 项目、工具、人物 | 合并 |
-| `events` | 发生过的事情 | 追加 |
-| `cases` | 问题 → 解决方案 | 追加 |
-| `patterns` | 可复用工作流 | 合并 |
-
-详情：[`docs/memory-categories.md`](docs/memory-categories.md)
-
----
-
 <details>
-<summary><strong>MCP 工具（29 个）</strong></summary>
+<summary><strong>MCP 工具（41 个）</strong></summary>
 
 | 工具 | 说明 |
 |------|------|
-| `workflow_observe` | 记录一条 append-only workflow observation，不写进普通 memory |
-| `workflow_health` | 查看单个 workflow 的健康度，或输出退化 workflow dashboard |
-| `workflow_evidence` | 为某个 workflow primitive 生成 evidence pack |
-| `store_memory` | 存一条可跨窗口复用的长期记忆 |
-| `store_workflow_pattern` | 把可复用工作流存成 durable `patterns` 记忆 |
-| `store_case` | 把可复用问题-解决方案存成 durable `cases` 记忆 |
-| `promote_memory` | 把 evidence 显式升级成 durable memory |
-| `list_conflicts` | 列出或查看 promotion 冲突候选项 |
-| `audit_conflicts` | 汇总 stale / escalated 冲突的优先级 |
+| `workflow_observe` | 存储 append-only 工作流观察记录 |
+| `workflow_health` | 查看工作流健康状态或降级面板 |
+| `workflow_evidence` | 构建工作流证据包 |
+| `store_memory` | 存储一条持久记忆 |
+| `store_workflow_pattern` | 存储可复用工作流模式 |
+| `store_case` | 存储问题-方案对 |
+| `promote_memory` | 显式升级 evidence 为持久记忆 |
+| `list_conflicts` | 列出或查看冲突候选 |
+| `audit_conflicts` | 汇总过期/升级的冲突优先级 |
 | `escalate_conflicts` | 预览或应用冲突升级元数据 |
-| `resolve_conflict` | 解决一条冲突候选项（保留 / 接受 / 合并） |
-| `checkpoint_session` | 把当前工作状态存成独立 checkpoint |
-| `latest_checkpoint` | 查看某个 session 或 scope 的最新 checkpoint |
+| `resolve_conflict` | 解决冲突（保留 / 接受 / 合并） |
+| `checkpoint_session` | 保存当前工作状态 |
+| `latest_checkpoint` | 查看最近的 checkpoint |
 | `resume_context` | 为新窗口编排启动上下文 |
-| `search_memory` | 在任务开始时主动回忆 |
-| `explain_memory` | 解释为什么这些记忆被命中 |
-| `distill_memory` | 把结果提炼成简报 |
-| `brief_memory` | 创建结构化 brief 并回写索引 |
-| `pin_memory` | 把一条带 scope 边界的记忆提升成 pinned asset |
-| `export_memory` | 把 distill 结果导出到磁盘 |
-| `list_pins` | 列出 pinned 记忆 |
+| `search_memory` | 任务开始时主动召回 |
+| `explain_memory` | 解释为什么这些记忆被匹配 |
+| `distill_memory` | 将结果蒸馏为精简摘要 |
+| `brief_memory` | 创建结构化摘要并重新索引 |
+| `pin_memory` | 将记忆升级为 Pin 资产 |
+| `export_memory` | 导出蒸馏摘要到磁盘 |
+| `list_pins` | 列出所有 Pin |
 | `list_assets` | 列出所有结构化资产 |
-| `list_dirty_briefs` | 预览旧规则生成的 dirty brief 资产 |
-| `clean_dirty_briefs` | 归档 dirty brief 并清理其索引行 |
+| `list_dirty_briefs` | 预览过时的 Brief 资产 |
+| `clean_dirty_briefs` | 归档过时 Brief 并移除索引 |
 | `memory_stats` | 查看索引统计 |
-| `memory_drill_down` | 查看某条记忆的完整元数据和来源追踪 |
-| `auto_capture` | 零 LLM 调用，从文本中启发式提取并存储记忆信号 |
-| `set_reminder` | 设置前瞻性记忆提醒，在未来会话中自动浮现 |
-| `consolidate_memories` | 聚类近重复记忆并合并（默认 dry-run，不直接写入） |
+| `memory_drill_down` | 查看记忆完整元数据和溯源 |
+| `auto_capture` | 启发式提取记忆信号（零 LLM） |
+| `set_reminder` | 设置前瞻记忆提醒 |
+| `consolidate_memories` | 聚类合并近似记忆（默认 dry-run） |
+| `store_skill` | 存储可执行技能 |
+| `retrieve_skill` | 按语义相似度检索技能 |
+| `scan_skill_promotions` | 扫描可升级为技能的候选 |
+| `list_tools` | 按层级发现工具（core/advanced/full） |
+| `batch_store` | 批量存储最多 20 条记忆 |
+| `distill_session` | 三层管线蒸馏对话为结构化知识 |
+| `import_conversations` | 导入 Claude Code、ChatGPT、Slack 等对话 |
+| `data_checkup` | 运行数据质量健康检查 |
+| `dream` | 离线记忆整合（聚类、合并、修剪） |
+| `memory_lint` | 记忆质量检查：矛盾、重复、过期、孤儿 |
+| `forget_memory` | 级联删除记忆 + KG 清理 + Pin 归档 + 审计 |
+| `export_graph` | 导出交互式 HTML 知识图谱 |
 
 </details>
 
 <details>
-<summary><strong>HTTP API（19 个端点）</strong></summary>
+<summary><strong>HTTP API（21 个端点）</strong></summary>
 
-基础地址：`http://localhost:4318`
+基地址：`http://localhost:4318`
 
 | 端点 | 方法 | 说明 |
 |------|------|------|
 | `/v1/recall` | POST | 快速语义搜索 |
-| `/v1/store` | POST | 写入一条新记忆 |
-| `/v1/capture` | POST | 批量写入结构化记忆 |
-| `/v1/pattern` | POST | 写入结构化 workflow pattern |
-| `/v1/case` | POST | 写入结构化 problem-solution case |
-| `/v1/promote` | POST | 把 evidence 显式升级成 durable memory |
-| `/v1/conflicts` | GET | 列出或查看冲突候选项 |
-| `/v1/conflicts/audit` | GET | 汇总冲突优先级 |
-| `/v1/conflicts/escalate` | POST | 预览或应用冲突升级元数据 |
-| `/v1/conflicts/resolve` | POST | 解决一条冲突候选项（保留 / 接受 / 合并） |
-| `/v1/checkpoint` | POST | 写入当前工作状态的 checkpoint |
-| `/v1/workflow-observe` | POST | 把 workflow observation 写到独立 store，不混入 durable memory |
-| `/v1/checkpoint/latest` | GET | 按 session 或 scope 取最新 checkpoint |
-| `/v1/workflow-health` | GET | 查看 workflow 健康度，或返回退化 workflow dashboard |
-| `/v1/workflow-evidence` | GET | 从最近 issue observation 生成 workflow evidence pack |
-| `/v1/resume` | POST | 为新窗口编排启动上下文 |
-| `/v1/search` | POST | 高级搜索，返回完整元数据 |
-| `/v1/stats` | GET | 查看记忆统计 |
+| `/v1/store` | POST | 存储一条记忆 |
+| `/v1/capture` | POST | 批量存储结构化记忆 |
+| `/v1/pattern` | POST | 存储工作流模式 |
+| `/v1/case` | POST | 存储问题-方案对 |
+| `/v1/promote` | POST | 升级 evidence 为持久记忆 |
+| `/v1/conflicts` | GET | 列出冲突候选 |
+| `/v1/conflicts/audit` | GET | 冲突审计汇总 |
+| `/v1/conflicts/escalate` | POST | 冲突升级 |
+| `/v1/conflicts/resolve` | POST | 解决冲突 |
+| `/v1/checkpoint` | POST | 保存工作检查点 |
+| `/v1/workflow-observe` | POST | 存储工作流观察 |
+| `/v1/checkpoint/latest` | GET | 获取最近检查点 |
+| `/v1/workflow-health` | GET | 工作流健康面板 |
+| `/v1/workflow-evidence` | GET | 工作流证据包 |
+| `/v1/resume` | POST | 编排新窗口启动上下文 |
+| `/v1/search` | POST | 高级搜索（含完整元数据） |
+| `/v1/stats` | GET | 记忆统计 |
+| `/v1/lint` | GET | 记忆质量报告 |
 | `/v1/health` | GET | 健康检查 |
 
 完整文档：[`docs/api-reference.md`](docs/api-reference.md)
@@ -350,12 +385,12 @@ RecallNest 现在把 workflow observation 放在专门的 append-only store，
 
 ```bash
 # 搜索与探索
-bun run src/cli.ts search "你的查询"
-bun run src/cli.ts explain "你的查询" --profile debug
-bun run src/cli.ts distill "主题" --profile writing
+bun run src/cli.ts search "your query"
+bun run src/cli.ts explain "your query" --profile debug
+bun run src/cli.ts distill "topic" --profile writing
 bun run src/cli.ts stats
 
-# Workflow observation
+# 工作流观察
 bun run src/cli.ts workflow-observe resume_context "Fresh window skipped continuity recovery." --outcome missed --scope project:recallnest
 bun run src/cli.ts workflow-health resume_context --scope project:recallnest
 bun run src/cli.ts workflow-evidence checkpoint_session --scope project:recallnest
@@ -372,6 +407,12 @@ bun run src/cli.ts conflicts resolve af70545a --keep-existing
 bun run src/cli.ts conflicts resolve af70545a --merge
 bun run src/cli.ts conflicts resolve --all --keep-existing --status open
 
+# 记忆健康与可视化
+bun run src/cli.ts lint                         # 记忆质量报告
+bun run src/cli.ts lint --scope project:myapp   # 指定 scope
+bun run src/cli.ts graph --open                 # 导出并打开知识图谱
+bun run src/cli.ts graph --max-nodes 50         # 较小的图
+
 # 导入与诊断
 bun run src/cli.ts ingest --source all
 bun run src/cli.ts doctor
@@ -379,47 +420,79 @@ bun run src/cli.ts doctor
 
 </details>
 
-<details>
-<summary><strong>Web UI（调试用）</strong></summary>
+---
+
+## 多语言支持
+
+RecallNest 开箱即用支持英文。如需多语言记忆（中文、日文、泰文及 20+ 种语言），安装 [babel-memory](https://github.com/AliceLJY/babel-memory) 及所需语言包：
 
 ```bash
-bun run src/ui-server.ts
-# → http://localhost:4317
+# 中文
+npm install babel-memory jieba-wasm
+
+# 日文
+npm install babel-memory @sglkc/kuromoji
+
+# 泰文
+npm install babel-memory wordcut
+
+# 欧洲语言（德语、法语、西班牙语、俄语等）
+npm install babel-memory snowball-stemmers
+
+# 同时安装多种语言
+npm install babel-memory jieba-wasm @sglkc/kuromoji snowball-stemmers
 ```
 
-Web UI 主要用于调试和探索，不是主要生产接口。
+RecallNest 启动时自动检测 babel-memory，无需额外配置。未安装 babel-memory 时，RecallNest 仍正常工作，使用标准 BM25 文本搜索。
 
-</details>
+---
+
+## 项目状态与路线图
+
+RecallNest 持续维护中。所有主要架构阶段已完成——完整路线图和未来计划见 [Roadmap](ROADMAP.md)。
 
 ---
 
 ## 与 memory-lancedb-pro 的关系
 
-RecallNest 最初从 [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) fork 而来，共享其混合检索、衰减建模和记忆工程化的核心思路。关键区别：
+RecallNest 起源于 [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) 的 fork，共享混合检索、衰减建模、记忆即系统的核心理念。关键区别：
 
-- **memory-lancedb-pro** 是 OpenClaw 插件 —— 为单个 OpenClaw Agent 添加长期记忆。
-- **RecallNest** 是独立记忆层 —— 同时服务 Claude Code、Codex 和 Gemini CLI，内建会话连续性、结构化资产和冲突管理。
+- **memory-lancedb-pro** 是 OpenClaw 插件——为单个 OpenClaw Agent 添加长期记忆。
+- **RecallNest** 是独立记忆层——通过 MCP + HTTP API 同时服务 Claude Code、Codex、Gemini CLI，内建会话连续性、结构化资产和冲突管理。
 
 ## 致谢
 
 | 来源 | 贡献 |
 |------|------|
-| [claude-memory-pro](https://github.com/CortexReach/claude-memory-pro) by [@win4r](https://github.com/win4r) | 检索核心思路和实现基础 |
-| Claude Code | 基础架构和早期搭建 |
+| [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) by [@win4r](https://github.com/win4r) | Fork 基础——混合检索、衰减建模、记忆架构 |
+| Claude Code | 基础搭建与早期脚手架 |
 | OpenAI Codex | 产品化和 MCP 扩展 |
 
-特别感谢秦超老师（[@win4r](https://github.com/win4r)）和 [CortexReach](https://github.com/CortexReach) 团队的基础工作。
+特别感谢秦超（[@win4r](https://github.com/win4r)）和 [CortexReach](https://github.com/CortexReach) 团队的基础性工作。
+
+<details>
+<summary><strong>生态系统</strong></summary>
+
+**小试AI** 开源 AI 工作流矩阵：
 
-## Star History
+| 项目 | 说明 |
+|------|------|
+| [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 |
+| [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 配置与记忆备份 |
+| [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 可用 |
+| [agent-nexus](https://github.com/AliceLJY/agent-nexus) | 一键安装：记忆 + 远程控制 |
+| [cc-cabin](https://github.com/AliceLJY/cc-cabin) | Claude Code 完整工作流脚手架 |
 
-<a href="https://star-history.com/#AliceLJY/recallnest&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=AliceLJY/recallnest&type=Date&theme=dark&transparent=true" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=AliceLJY/recallnest&type=Date&transparent=true" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=AliceLJY/recallnest&type=Date&transparent=true" />
-  </picture>
-</a>
+</details>
 
-## 许可证
+## License
 
 MIT

package/bin/recallnest.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * RecallNest CLI launcher — cross-runtime compatible
+ *
+ * Priority: bun (native TS, fastest) → node + tsx (fallback)
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, "..", "src", "cli.ts");
+const args = process.argv.slice(2);
+
+function hasBun() {
+  try {
+    execFileSync("bun", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function run(command, commandArgs) {
+  const child = spawn(command, commandArgs, { stdio: "inherit" });
+  child.on("close", (code) => process.exit(code || 0));
+  child.on("error", (err) => {
+    console.error(`Failed to start ${command}: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+if (hasBun()) {
+  // Native bun — fastest path
+  run("bun", ["run", cli, ...args]);
+} else {
+  // Fallback: node + tsx
+  const tsxBin = join(__dirname, "..", "node_modules", ".bin", "tsx");
+  if (existsSync(tsxBin)) {
+    run(tsxBin, [cli, ...args]);
+  } else {
+    // tsx not found in local node_modules, try global
+    try {
+      execFileSync("tsx", ["--version"], { stdio: "ignore" });
+      run("tsx", [cli, ...args]);
+    } catch {
+      console.error(`
+  RecallNest requires either Bun or tsx to run TypeScript.
+
+  Option A (recommended):
+    curl -fsSL https://bun.sh/install | bash
+
+  Option B:
+    npm install -g tsx
+
+  Then retry your command.
+`);
+      process.exit(1);
+    }
+  }
+}