recallnest 2.6.0 → 3.0.0

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)
 
@@ -29,6 +29,55 @@
 RecallNest 的解法：**一个 LanceDB 驱动的记忆层，供你的编程 Agent 共读共写**。一个窗口存入的上下文，另一个窗口自动召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——不是简单的日志堆积。
 
 
+## 谁能接上
+
+**数据层不知道你的客户端长什么样。** RecallNest 把同一个 LanceDB 存储通过三个出口暴露出来，接法按客户端的能力选，而不是绑死在某一种协议上。
+
+| 你的客户端能做什么 | 走哪条 | 已验证 |
+|---|---|---|
+| 执行本地命令（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` | 笔记本上的四个客户端共读家里服务器上的同一个库 |
+
+两条值得直说的推论：
+
+- **不绑单一协议。** 支持填 MCP 配置的 GUI 聊天 app，接入方式和终端里的 agent 完全一样；只会发 HTTP 请求的客户端，读到的仍是同一份记忆。
+- **不绑单台机器。** 因为 MCP 传输走 stdio，启动命令由你定义——把它指向 `ssh`，每台机器上的每个客户端共用同一个真相源，而不是各自长出一个数据库。
+
+接一个新客户端不等于要改 RecallNest：够格的客户端自己写一行配置，能力受限的在 HTTP API 前面加一层薄网关。
+
+### 手机上的 AI app：只读网关
+
+HTTP API（`:4318`）只监听 `127.0.0.1`，并且会拒绝任何 Host 头不是本地的请求——这是**有意的**：它同时暴露写入路由（`/v1/store`、`/v1/checkpoint`），直接开到公网等于把写权限交出去。
+
+所以要让手机上的 AI app 读到同一份记忆，前面加一层只读网关：
+
+```bash
+openssl rand -hex 32 > ~/.config/recallnest/gateway-token
+chmod 600 ~/.config/recallnest/gateway-token
+
+bun run api        # 本机 API，:4318
+bun run gateway    # 只读网关，:8791 → 转发到 :4318
+```
+
+网关只放行读路由（`/recall`、`/search`、`/stats`、`/health`），**任何写路由一律 404**；Bearer token 常量时间比较、每分钟限流、请求与响应都有大小上限。把它放到隧道后面（Tailscale Serve/Funnel、Cloudflare Tunnel 等）即可从手机访问。
+
+```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}'
+```
+
+可选：配 `RECALLNEST_GATEWAY_FILE_ROOTS="notes=/abs/path,wiki=/abs/path"` 会多出一个 `GET /files/search`，用 ripgrep 只读检索你指定的 markdown 目录（查询词以 argv 传入，不经过 shell）。不配就没有这个路由。
+
+> 网关默认也只绑 `127.0.0.1`——把它暴露到公网是隧道的职责，请自行评估风险。
+
+作者用这条路把 iPhone 上的 [OpenMinis](https://github.com/OpenMinis/OpenMinis) 接了上来：手机 app 经 Tailscale Funnel 打到网关，能查到同一份记忆库。有意思的是它查回的是**它自己**的历史——那些对话导出后回流、被索引，于是一个每次冷启动的手机 agent 有了跨会话的记忆。
+
+
+
 ## 快速开始
 
 ### 方式 A：Claude Code Plugin（推荐）
@@ -55,7 +104,7 @@ npm install -g recallnest      # 全局安装
 recallnest doctor
 ```
 
-支持 Node.js 18+（通过 tsx）或 Bun，无需 clone 仓库。
+支持 Node.js 22+（通过 tsx）或 Bun，无需 clone 仓库。
 
 ### 方式 C：手动安装
 
@@ -96,7 +145,7 @@ curl http://localhost:4318/v1/stats
 
 ```bash
 bash integrations/claude-code/setup.sh
-bash integrations/gemini-cli/setup.sh
+bash integrations/agy/setup.sh
 bash integrations/codex/setup.sh
 ```
 
@@ -143,8 +192,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,6 +245,60 @@ bun run src/ui-server.ts
 
 ---
 
+## v3.0 新增：一个受支持的运行时，和终于能被用起来的结论
+
+v3.0 是大版本，原因有两个：一个在安装时看得见，一个在记忆的行为里。
+
+**运行时边界提到了 Node 22。** RecallNest 一直带着 `openai@4`，它拽着
+`formdata-node` → `node-domexception` 这条弃用链。openai 从 v5 起每个版本都是零依赖，
+所以升到哪一版这条链都会消失 —— 但 v7 自己声明 `engines.node >= 22.0.0`，于是
+「抬 Node 边界」和「甩掉弃用依赖链」变成同一件事，而不是两件。`engines.node` 现在是
+`>=22`。这是本次大版本里唯一的破坏性改动。
+
+**合成出的结论终于能进稳定记忆。** `dream` 把 cluster insight 和 cross-memory pattern
+写在 evidence 层是有意的 —— 模型对自己记忆的再加工是通往源头的线索，不是压过源头的
+权威 —— 但稳定记忆的选取对 evidence 层一律拒收。后果是绝对的：一条合成结论无论证据
+多充分，下游都没法靠它。`promote_synthesis`（MCP）与 `recallnest promote-synthesis`
+（CLI）给了它一条路，判据是这条结论自己那份经过校验的证据集，而不是「重复出现几次」
+—— 合成物本身就是跨条目聚合，要求它重复是把一件事数了几次。合成行本身一个字不改；
+晋升写的是另一条 durable 记录，带 `promotedFrom` 指回去，走的是和其他晋升同一条通道、
+同一套 `canonicalKey` 去重。
+
+本次还有：
+
+- **retrieve 审计行会说清服务了什么。** 它以前只记查询词和命中数。而信念是就地修订的
+  —— id 不变、版本号加一、旧正文作为 `superseded` 行留下 —— 所以「memory X 被检索了」
+  这句话跨过任何一次信念变更都是有歧义的。现在每条结果的 id、版本、生命周期状态和
+  boundary 都记下来；列表有上限，而且**被截断时会说自己被截断了**。
+- **embeddings 与 chat completions 有了 HTTP 契约测试。** 此前所有测试都把 SDK client
+  换成桩函数，没有一条碰过 socket，传输层的回归会全绿着放过去。新测试驱动真的类、经真的
+  SDK、打到本地回环服务器，覆盖成功 / 错误 / 超时三态，以及默认 OpenAI 形态加上 Jina、
+  Qwen 兼容端点。零出网、零凭据。
+- **修复：被限流时反而会猛打对方。** 是上面那批测试当场查出来的。embedder 遇到
+  context-length 错误会分块重试，而分块器对短文本原样返回，判定「这是 context 错误」的
+  那条正则又会命中限流措辞 —— 于是一个 429 会拿同一段文本无限重打。实测 5 秒 61,000 多
+  个请求，对着一个正在叫我们慢一点的端点。现在失败是有界的。
+- **一个已知的召回缺口变成了能跑的回归。** 一条又长、又旧、很少被读的记忆，可能用它自己
+  正文里的原话都召不回，而短的、新的、被频繁读的条目排在它前面。这是排序问题不是过滤
+  问题 —— 那条记忆过了所有阈值，然后排最后一名。复现已经进仓；排序的修复不在本次。
+- **MCP 工具 44 个**（三层），此前 43 个。
+
+### 从 v2.6 升级
+
+- **需要 Node 22 或更新版本。** 用 Bun 的不受影响。这是本次唯一的破坏性改动。
+- 已有 LanceDB 数据原地打开，不需要导出导入。
+- `promote_synthesis` 默认 dry-run，不传 `dryRun=false` 不写任何东西。
+- `audit.jsonl` 里检索那类行变大了（它现在列出服务了哪几条）。轮转仍是手动的，接近
+  50 MB 时归档一下。
+
+### 关于 npm 历史的一句说明
+
+npm 上的 `recallnest@2.6.1` 是一次维护发布，发布时这个包还没有配置 Trusted Publishing，
+所以它不带构建 provenance。这是它当时怎么发的一个事实，不是包本身的缺陷，而且**无法追认**
+—— 同一个 npm 版本不能为了补 provenance 再发一次。
+
+---
+
 ## v2.6 新增：跨进程一致性与可靠分发
 
 v2.6 把 v2.5.4 以来的开发整理成一版可升级、可安装、版本口径一致的正式候选：
@@ -277,7 +380,7 @@ v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康
 │                      集成层                               │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  43 个工具           │  │  21 个端点                  │ │
+│  │  44 个工具           │  │  21 个端点                  │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -322,7 +425,7 @@ v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康
 
 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 +441,7 @@ RecallNest 提供两种接口：
 ---
 
 <details>
-<summary><strong>MCP 工具（43 个）</strong></summary>
+<summary><strong>MCP 工具（44 个）</strong></summary>
 
 | 工具 | 说明 |
 |------|------|
@@ -350,6 +453,7 @@ RecallNest 提供两种接口：
 | `store_case` | 存储问题-方案对 |
 | `promote_memory` | 显式升级 evidence 为持久记忆 |
 | `promote_scan` | 扫描近期 evidence，自动晋升合格记忆为持久存储 |
+| `promote_synthesis` | 扫描 dream 合成出的结论，把自身证据集撑得住的那些晋升为持久记忆 |
 | `list_conflicts` | 列出或查看冲突候选 |
 | `audit_conflicts` | 汇总过期/升级的冲突优先级 |
 | `escalate_conflicts` | 预览或应用冲突升级元数据 |
@@ -498,7 +602,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 +622,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.

package/integrations/agy/README.md

@@ -0,0 +1,73 @@
+# Antigravity CLI (agy) Integration
+
+> agy 接入指南：一键配 MCP + continuity 规则，让 agy 在新窗口里主动恢复稳定上下文。
+
+> **Note on naming.** Google retired the standalone `gemini` CLI for personal
+> accounts on 2026-06-18; the [Antigravity CLI](https://antigravity.google)
+> (`agy`) is its successor. This integration targets `agy`. If you are on a
+> Code Assist Standard/Enterprise plan and still run the legacy CLI, point the
+> same MCP entry at whatever config file your build reads.
+
+## Quick Start
+
+```bash
+bash integrations/agy/setup.sh
+```
+
+## What It Does
+
+- Adds RecallNest as an MCP server in `~/.gemini/config/mcp_config.json`
+- Installs a managed RecallNest block in `~/.gemini/config/GEMINI.md`
+
+## Continuity Rules
+
+The managed block comes from [agy-md-snippet.md](agy-md-snippet.md) and tells agy to:
+
+- call `resume_context` at the start of fresh windows or continuity-sensitive tasks
+- run lightweight `search_memory` on task pivots inside the same project before repo exploration drifts
+- reuse known `scope` / `sessionId` and the resolved scope returned by `resume_context` in follow-up recall calls
+- treat recalled or startup-hook repo state as unverified until this window explicitly checks the repo
+- save `checkpoint_session` before leaving resumable work
+- do not inspect repo state just to enrich a close-window checkpoint unless the user explicitly asked for repo state
+- do not write unverified repo-state claims into `checkpoint_session`
+- capture durable facts with `store_memory` and reusable workflows with `store_workflow_pattern`
+
+## Shared Index
+
+agy shares the same LanceDB index as Claude Code, Codex and Kimi. Memories ingested from any source are searchable by all of them.
+
+## Manual Setup
+
+Add to `~/.gemini/config/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "recallnest": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "RECALLNEST_PATH/src/mcp-server.ts"]
+    }
+  }
+}
+```
+
+Replace `RECALLNEST_PATH` with your actual path.
+
+Then copy [agy-md-snippet.md](agy-md-snippet.md) into `~/.gemini/config/GEMINI.md` if you are not using `setup.sh`.
+
+## Tool Permissions
+
+agy gates tool calls separately from MCP registration. In non-interactive mode
+(`agy -p`) it cannot prompt, so permission-requiring tools are auto-denied and
+the agent silently returns nothing. If RecallNest tools appear registered but
+never fire, set `toolPermission` in `~/.gemini/antigravity-cli/settings.json`,
+or pass `--dangerously-skip-permissions` for a single run.
+
+## Verify
+
+```bash
+agy -p "resume my context for RecallNest continuity work" --print-timeout 180s </dev/null
+```
+
+If `resume_context` or `search_memory` is called, you're set.

package/integrations/agy/setup.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# RecallNest — Antigravity CLI (agy) MCP setup (idempotent)
+# Usage: bash integrations/agy/setup.sh
+#
+# Google retired the standalone Gemini CLI for personal accounts on 2026-06-18.
+# Its successor is the Antigravity CLI (`agy`), which reads MCP servers from
+# ~/.gemini/config/mcp_config.json — not the old ~/.gemini/settings.json.
+
+set -euo pipefail
+
+AGY_CONFIG_DIR="$HOME/.gemini/config"
+AGY_MCP_CONFIG="$AGY_CONFIG_DIR/mcp_config.json"
+AGY_MD="$AGY_CONFIG_DIR/GEMINI.md"
+RECALLNEST_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+MCP_ENTRY="$RECALLNEST_DIR/src/mcp-server.ts"
+RULES_SNIPPET="$RECALLNEST_DIR/integrations/agy/agy-md-snippet.md"
+RULES_HELPER="$RECALLNEST_DIR/integrations/shared/install-managed-block.sh"
+
+if [[ ! -f "$MCP_ENTRY" ]]; then
+  echo "ERROR: $MCP_ENTRY not found. Run this from the recallnest repo root."
+  exit 1
+fi
+
+if [[ ! -f "$RULES_HELPER" ]]; then
+  echo "ERROR: $RULES_HELPER not found."
+  exit 1
+fi
+
+if ! command -v agy >/dev/null 2>&1; then
+  echo "WARNING: 'agy' not found on PATH. Install the Antigravity CLI first:"
+  echo "  https://antigravity.google"
+  echo "Continuing anyway — the config will be written for when agy is installed."
+  echo ""
+fi
+
+mkdir -p "$AGY_CONFIG_DIR"
+if [[ ! -f "$AGY_MCP_CONFIG" ]]; then
+  echo '{"mcpServers":{}}' > "$AGY_MCP_CONFIG"
+  echo "Created $AGY_MCP_CONFIG"
+fi
+
+# Check if already configured
+if bun -e "
+  const c = JSON.parse(require('fs').readFileSync('$AGY_MCP_CONFIG','utf8'));
+  process.exit(c.mcpServers?.recallnest ? 0 : 1);
+" 2>/dev/null; then
+  echo "RecallNest MCP already configured in $AGY_MCP_CONFIG — skipping."
+else
+  bun -e "
+    const fs = require('fs');
+    const c = JSON.parse(fs.readFileSync('$AGY_MCP_CONFIG','utf8'));
+    if (!c.mcpServers) c.mcpServers = {};
+    c.mcpServers.recallnest = {
+      type: 'stdio',
+      command: 'bun',
+      args: ['run', '$MCP_ENTRY']
+    };
+    fs.writeFileSync('$AGY_MCP_CONFIG', JSON.stringify(c, null, 2) + '\n');
+  "
+  echo "Added RecallNest MCP to $AGY_MCP_CONFIG"
+fi
+
+. "$RULES_HELPER"
+install_managed_markdown_block "$RULES_SNIPPET" "$AGY_MD" "recallnest-continuity"
+echo "Installed RecallNest continuity rules in $AGY_MD"
+
+echo ""
+echo "Setup complete. Restart agy to activate, then verify with:"
+echo "  agy -p 'List your available MCP tools' --print-timeout 180s </dev/null"
+echo ""
+echo "Continuity baseline seed:"
+echo "  (cd \"$RECALLNEST_DIR\" && bun run seed:continuity)"
+echo ""
+echo "Managed snippet source:"
+echo "  $RULES_SNIPPET"

package/integrations/setup-all.sh

@@ -19,7 +19,7 @@ bash "$SCRIPT_DIR/codex/setup.sh"
 echo ""
 
 echo "--- Gemini CLI ---"
-bash "$SCRIPT_DIR/gemini-cli/setup.sh"
+bash "$SCRIPT_DIR/agy/setup.sh"
 echo ""
 
 echo "======================================"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recallnest",
-  "version": "2.6.0",
+  "version": "3.0.0",
   "description": "RecallNest — MCP-native, local-first memory search and distillation for AI conversations",
   "license": "MIT",
   "type": "module",
@@ -54,21 +54,23 @@
     "seed:continuity": "bun run seed:patterns && bun run seed:cases && bun run seed:memories",
     "smoke:claude-continuity": "bash integrations/claude-code/smoke-continuity.sh",
     "ui": "bun run src/ui-server.ts",
-    "api": "bun run src/api-server.ts"
+    "api": "bun run src/api-server.ts",
+    "gateway": "bun run src/gateway-server.ts"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22"
   },
   "dependencies": {
+    "@hono/node-server": "1.19.17",
     "@lancedb/lancedb": "^0.26.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
-    "openai": "^4.0.0",
+    "openai": "^7.5.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
-    "babel-memory": "^2.1.1"
+    "babel-memory": "^2.1.2"
   },
   "repository": {
     "type": "git",

package/src/__tests__/access-tracker-novelty.test.ts

@@ -268,6 +268,12 @@ describe("distinct-reader bookkeeping", () => {
   });
 
   it("dedups same reader and unions different readers", async () => {
+    // 2026-08-23 语义订正：同进程内的多个 AccessTracker 现在共享一个 readerId。
+    // 旧版每个实例各随机一个，与本文件测的那句注释（access-tracker.ts:63
+    // "one stdio MCP server process ≈ one CC session"）直接矛盾——components 按
+    // profile 缓存，同一个会话开两个 profile 就凭空多出一个"读者"，
+    // 把 distinctReaderCount 抬高、进而虚抬 skill-promotion 的 readBoost。
+    // 所以「不同读者」这一半改用显式 readerId 表达（跨进程/跨会话的真实形态）。
     const entries = [makeEntry("a")];
     const store = createMockStore(entries);
     const t1 = new AccessTracker(store as any, { ...DEFAULT_ACCESS_TRACKER_CONFIG, flushIntervalMs: 1, cooldownMs: 0 });
@@ -276,9 +282,9 @@ describe("distinct-reader bookkeeping", () => {
     t1.recordAccess(["a"]);
     await t1.flush(); // same reader twice → still 1 distinct
 
-    const t2 = new AccessTracker(store as any, { ...DEFAULT_ACCESS_TRACKER_CONFIG, flushIntervalMs: 1, cooldownMs: 0 });
+    const t2 = new AccessTracker(store as any, { ...DEFAULT_ACCESS_TRACKER_CONFIG, flushIntervalMs: 1, cooldownMs: 0 }, "r-second99");
     t2.recordAccess(["a"]);
-    await t2.flush(); // second reader → 2 distinct
+    await t2.flush(); // genuinely different reader → 2 distinct
 
     const meta = JSON.parse(store.data.get("a")!.metadata!) as Record<string, unknown>;
     expect(meta.accessCount).toBe(3);
@@ -286,6 +292,20 @@ describe("distinct-reader bookkeeping", () => {
     expect(meta.distinctReaderCount).toBe(2);
   });
 
+  it("does not inflate distinct readers when one session builds several trackers", async () => {
+    // 这是上面那条订正保护的东西：同一会话的两个 profile 不该被数成两个读者。
+    const entries = [makeEntry("a")];
+    const store = createMockStore(entries);
+    const cfg = { ...DEFAULT_ACCESS_TRACKER_CONFIG, flushIntervalMs: 1, cooldownMs: 0 };
+    for (const tracker of [new AccessTracker(store as any, cfg), new AccessTracker(store as any, cfg)]) {
+      tracker.recordAccess(["a"]);
+      await tracker.flush();
+    }
+    const meta = JSON.parse(store.data.get("a")!.metadata!) as Record<string, unknown>;
+    expect((meta.readerIds as string[]).length).toBe(1);
+    expect(meta.distinctReaderCount).toBe(1);
+  });
+
   it("saturates readerIds at READER_ID_CAP without growing the array", async () => {
     const capped = Array.from({ length: 8 }, (_, i) => `r-cap${i}`);
     const entries = [makeEntry("a", {