recallnest 2.3.0 → 2.6.0

package/CHANGELOG.md

@@ -0,0 +1,187 @@
+# Changelog
+
+## v2.6.0 — Cross-process consistency and reliable distribution (2026-08-13)
+
+### Added
+
+- Claude Code marketplace installation now registers the RecallNest MCP server and continuity skill instead of shipping metadata only. Jina credentials use sensitive plugin configuration; generated config and LanceDB data live under `${CLAUDE_PLUGIN_DATA}` and survive plugin updates.
+- Kimi, AGY/Antigravity, and minis transcript sources are recognized across ingestion, memory-boundary policy, and term resolution.
+- Retrieval audit logging is connected to the live retriever, and the opt-in layer-admission shadow/enforcement pipeline is available through `RECALLNEST_LAYER_ADMISSION=observe|on`.
+
+### Changed
+
+- `package.json` is now the single version source for CLI output, MCP server metadata, HTTP health responses, npm metadata, and the Claude Code marketplace. All public surfaces report `2.6.0`.
+- LanceDB uses strong cross-process read consistency by default. `RECALLNEST_READ_CONSISTENCY_INTERVAL=<seconds>` selects bounded staleness; `off` restores the legacy unchecked handle behavior.
+- Belief changes preserve prior rows as `superseded`; procedural memories avoid time decay; cold-start scoring, length normalization, and short single-token queries have safer retrieval behavior.
+- `dream` adds failure classification, wall-clock budgeting, vector refill before clustering, and output assertions so a successful status means useful work was produced.
+- `@modelcontextprotocol/sdk` is updated to 1.30.0, with both npm and Bun lockfiles aligned.
+
+### Fixed
+
+- Empty legacy LanceDB tables now receive schema migrations before their first new write.
+- Long-lived retrievers now see writes committed by CLI ingest and other processes without a restart.
+- Runtime and maintenance scripts resolve the configured database path consistently instead of silently opening a second database.
+- Local HTTP access is constrained to the intended loopback boundary, and tracked credential scans cover release contents without printing secret values.
+- Per-cluster LLM timeouts no longer abort an entire `dream` scope; failures are counted, single-scope runs emit the same metrics contract as automatic runs, and the launch wrapper no longer fails after successful work because of an undefined log-file variable.
+
+### Upgrade notes
+
+- v2.5.4 databases open in place; no export/import step is required. The schema migration also covers empty tables.
+- Plugin users need Bun and will be prompted for a Jina API key on first install. Existing manual-clone installations keep their current configuration and data path.
+- Retrievals now add audit rows. `audit.jsonl` has no automatic rotation; archive it when it approaches 50 MB.
+- Layer admission remains off by default. Use `observe` before enabling enforcement on an existing memory corpus.
+
+### Verification
+
+- 2,152 tests pass across 152 files.
+- A database written by the remote v2.5.4 release was opened, read, and extended by v2.6.0 in an isolated upgrade smoke test.
+- An isolated Claude Code installation connected to the plugin MCP server with all 43 tools; packed npm installs reported `2.6.0` from both `recallnest` and the legacy `local-memory` alias.
+
+## v2.5.4 — npm 发布边界修复 (2026-07-17)
+
+- package.json 改为严格 files 白名单，只发布运行所需源码、示例配置、UI、集成脚本和必要文档。
+- 新增实际 tarball 内容检查：环境文件、运行配置、日志、会话、数据库、密钥材料和开发工作树一旦进入包即失败。
+- npm publish 前自动执行同一检查，CI 也验证最终包清单，避免本地运行数据再次随包发布。
+- 补齐 npm 包中的 UI 资源与 README 引用文档，并将中文 README 的 MCP 工具数对齐为 43。
+- 清理历史可视化 HTML 中遗留的两段 provider-shaped token，并增加只报路径/行号的 tracked-file 凭据扫描。
+- `doctor` 不再显示 API key 前缀，只报告是否已设置。
+
+> **CHANGELOG gap notice**: v1.3.1 (2026-03-12) → v2.5.2 (2026-05-27) 中间有较长开发期未更新 CHANGELOG。v2.5+ 系列以下开始恢复跟踪。历史 v1.4 - v2.4 间的变更见 git log。
+
+## v2.5.3 — 诊断工具失明 + 失效功能 + score 显示 三批修复 (2026-05-29)
+
+一轮临床向审查(CC 多 agent + Codex trio 二审)发现的一组修复:诊断工具在生产给虚假健康信号、三个功能完全失效、检索 score 显示失去区分度。
+
+### Fixed
+
+- **三处让功能完全失效的 bug**:
+  - `distill_session` MCP tool 引用未声明的 `llmClient` → 调用必抛 ReferenceError、工具 100% 不可用(SDK 接住转错误响应,server 不崩但永远 distill 不了)。改用模块级已初始化的 `llm`。
+  - `ingest --no-llm` 空操作:commander 把 `--no-llm` 解析成 `options.llm=false`,代码却读 `options.noLlm`(恒 undefined)→ 想跳过 LLM 实际仍全程调用。改读 `options.llm===false`,Gemini/memory 两源同步遵守。
+  - `tool-output-compressor` 正则 lookahead 末项 `\z` 在 JS 中是字面字符 z(非锚点)→ 末尾工具输出漏压缩、在字面 z 处误截断。改为 `(?![\s\S])`。
+- **`memory_lint` / `data_checkup` 因空向量假报健康** — `store.list()` 为性能返回 `vector:[]`,而矛盾/去重/维度/干扰检查全靠向量算相似度 → cosine 恒 0 → 静默失效(实测 contradictions=0/duplicates=0、维度检查把"全 0 维"假报 OK)。现在经 `store.getVectors()`(已加分批)补回真实向量再检查;维度检查排除取不到向量的条目、空库才判 ok。真实库验证:矛盾 0→174、重复 0→1473。
+- **诊断扫描截断不透明** — `memory_lint`/`data_checkup` 只扫最近 10000 条(库 9 万+),新增 `scanLimited`/`totalAvailable` 截断披露。
+- **检索 score 显示失去区分度** — `memory-output` 的 search/brief/full 三处用 `toFixed(0)`/`round` 把 score 取整(0.996 与 1.0 都显示 100%),改为 `toFixed(1)`。`search_memory` MCP description 从 "by semantic similarity" 改为明确 "fused ranking score, NOT pure cosine similarity"。
+
+### Internal
+
+- 修测试 mock 失真:`memory-lint` / `data-checkup` / `source-heartbeat` 三个测试的 mock store 原本直接返回带向量 entry(与生产 `vector:[]` 不符,正是它放过了诊断哑火 bug),改为复刻真实行为(list 空向量 + getVectors 补回)。
+- 基线 1525 tests / 0 fail。
+
+## v2.5.2 — store.delete(prefix) bug fix (2026-05-27)
+
+Codex trio review (2026-05-27, ref `~/Desktop/codex-v2.5.1-fix-review-20260527.md`) 发现的独立非阻塞 bug。
+
+### Fixed
+
+- **`store.delete(prefix)` 在 90K+ 库下可能漏删** — 旧实现先 `.select(["id","scope"]).limit(1000).toArray()` 再 app-layer filter，若目标 entry 不在前 1000 行就漏查。现在改成和 `store.getById` 对齐的 SQL LIKE：`where("id LIKE 'prefix%'").limit(2)`，ambiguous prefix 通过 `limit(2)` 检测并 throw。**不影响 `forget_memory` 主路径**（`forget-engine` 走 `store.get(memoryId)` 解析成完整 entry.id 再 `store.delete(entry.id)`），是 direct prefix delete caller 的潜在风险修补。
+- 基线 1523 / 0 fail（修补未引入新 test，依赖 Codex 上轮 LanceDB LIKE 临时验证 + 全量回归测试不破坏）
+
+## v2.5.1 — P0 production path: API exposure surface fixes (2026-05-27)
+
+Fresh CC session 第一次真用 `store_skill → workflow_observe(skillId=prefix) → retrieve_skill` 链路就**死锁**——返回 `Skill 1d9420b2 → not updated (skill_not_found)`。诊断出 3 处 API 暴露面割裂。
+
+Codex trio 二审评分 **8.5/10**，子 agent production smoke 验证 successCount 0→1 真递增 ✅。
+
+### Fixed
+
+- **`store.getById` 加 8+ hex prefix lookup** — 之前只接完整 UUID，与 `store.update / store.delete` 行为不一致；现在通过 SQL `LIKE 'prefix%' limit(2)` 检测歧义并返回 null。现有 caller（access-tracker / persistSkill / capture-engine 等 13 处）全部传完整 UUID，向后兼容零隐患（Codex 全仓库 grep 验证）。
+- **`store_skill` MCP handler 返回加 `Skill ID: <full UUID>` 行** — 之前只显示 `Stored skill <8 hex prefix>` 截断到 8 位，agent 拿不到完整 UUID 后续没法传给 `workflow_observe`。保留 short prefix 显示给人看。
+- **`retrieve_skill` MCP handler markdown 加 `**ID**:` + `**Outcome counts**: success=N failure=M [(last: ISO)]`** — 之前不暴露 id / successCount / failureCount / lastRefinedAt，agent 看不到反馈循环效果。
+- **`recordSkillOutcome` 用 `entry.id` 调 `store.update`** — 之前用 caller-provided skillId（可能 prefix）直接调 store.update，ambiguous prefix 在写操作风险翻倍；改用 getById 已 disambiguated 的完整 entry.id。
+
+### Notes
+
+- **8-char prefix 全库碰撞数学**: 4.3 亿组合 vs 90K 条记录，生日悖论 P(any collision) ≈ 61%；但 P(specific prefix collides) ≈ 0.002% (1/47,722)。**首选 full UUID 输入**，8-char prefix 作为兼容；歧义时返回 `skill_not_found`，不会误更新。
+- **Codex 5 步 smoke troubleshooting**: 见 `~/Desktop/codex-v2.5.1-fix-review-20260527.md` line 186-192。
+
+### Tests
+
+- 基线 1521 → 1523 / 0 fail（+2 prefix lookup case：`resolves 8+ hex prefix to full UUID and bumps successCount` / `returns skill_not_found for ambiguous prefix`）
+
+## v2.5.0 — SkillImplementationType schema 收缩 (2026-05-27)
+
+brgsk《agent memory: an anatomy》借鉴审计 + Codex trio 二审建议 "P1 选收缩 / 删承诺，不接 evaluator"。
+
+### Changed (Breaking)
+
+- **`SkillImplementationTypeSchema` 收缩到 `["instruction_sequence"]` 唯一值** — 原 enum 含 `bash` / `python` / `mcp_tool_chain` / `instruction_sequence` 四种，但 `implementation` 字段**从未真执行**（无 evaluator，仅作 context 给 agent 读）——是 schema 撒谎暗示可执行。现在明确 skill 是 **agent-readable runbook** 而非可执行物。
+- **`implementation` 字段 describe**: `"Executable content"` → `"Agent-readable runbook content: markdown steps, natural language workflow, or structured procedure. RecallNest does NOT execute this — it stores runbooks for agents to read and follow as context."`
+- **`store_skill` MCP tool description** 更新强调 "agent-readable skill runbook" + "RecallNest does NOT execute skills"。
+
+### Migration
+
+- 新写入受新 schema 约束，`bash` / `python` / `mcp_tool_chain` 会被拒。
+- **`parseSkillFromEntry` 用 type cast 不走 schema 校验** — 历史 `bash` / `python` skill records 仍可 retrieve（backward-compat path）。
+- production 库 2026-05-27 实测**无真实 skill 数据**（3 条 category=skills 是历史抓取噪声），破坏面接近 zero。
+
+### Tests
+
+- 基线 1520 → 1521 / 0 fail（删 1 个 "accepts all 4 types"，加 2 个 "accepts only instruction_sequence" / "rejects pre-v2.5 implementationType values"）
+
+## v2.5.0-pre — workflow_observe ↔ skill outcome 绑定 (2026-05-27)
+
+P0 反馈闭环：让 skill 的 `successCount` / `failureCount` 真有真实使用回流。commit `09dec62`，后由 v2.5.0 schema 收缩 + v2.5.1 API 暴露面 + v2.5.2 store.delete 补丁一起构成完整 P0 工作。
+
+### New
+
+- **`WorkflowObservationInputSchema` 加可选 `skillId` 字段** — `workflow_observe` 带 skillId + outcome 时自动 bump skill 的 successCount/failureCount，回写 lastRefinedAt。
+- **`recordSkillOutcome()` 导出函数** — `skill-engine.ts`，二分映射：`success` → successCount +1；`failure` / `corrected` / `missed` → failureCount +1。返回结构化结果不抛错，skill_not_found / not_a_skill / metadata_missing 静默跳过。
+- **`mcp-server.ts workflow_observe` + `api-server.ts /v1/workflow-observe`** 接 recordSkillOutcome。
+
+### Deployment
+
+- **新增 `RECALLNEST_MCP_TIER=full` 环境变量需求** — `workflow_observe` 在 TOOL_TIERS 标 governance，需 full tier 才暴露给 MCP ToolSearch。MacBook + mini × CC + Codex 4 处 config 已加（args inline / [env] 段）。
+
+### Tests
+
+- 基线 1486 → 1520 / 0 fail（+13 新 case 覆盖 outcome 映射 + 错误路径 + 元数据完整性 + 时间戳；+1 顺手修 workflow-observation.test.ts dashboard 漏传 now 参数 pre-existing bug）
+
+## v1.3.1 — Upstream Sync (2026-03-12)
+
+Synced with [CortexReach/memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) master (v1.1.0-beta.6+).
+
+### Changed
+
+- **Retriever**: Added `source` field to `RetrievalContext` — access reinforcement now only fires on manual retrieval, preventing auto-recall from strengthening noise memories (synced from upstream beta.2 design).
+- **Noise filter**: Added Chinese meta-question patterns (`你记得`, `记不记得`, `还记得…吗`, `上次…说`, `之前…提到`) and diagnostic artifact filter (synced from upstream beta.3).
+- **README**: Updated upstream credit link from `win4r/memory-lancedb-pro` to `CortexReach/memory-lancedb-pro`, added CortexReach team acknowledgement.
+
+## v1.2.0 — First Distributable Release (2026-03-08)
+
+The goal of this release: a new user can go from `git clone` to first search result in 15 minutes.
+
+### New
+
+- **`lm doctor`** — one-command pre-flight check for Bun, config, API key, data directory, transcript paths, and index health. Supports `--ci` mode for GitHub Actions.
+- **`lm demo`** — run sample queries to see RecallNest in action before writing your own.
+- **`config.json.example`** — ships with absolute `~/.recallnest/data/lancedb` path. New users copy this instead of editing the tracked config.
+- **GitHub Actions CI** — runs `doctor --ci` and TypeScript check on every push.
+- **Ingest pre-validation** — embedding API is tested before processing any files. Invalid Jina key now fails fast with a clear message instead of crashing mid-ingest.
+
+### Changed
+
+- **README rewritten** — added Prerequisites table (Bun + Jina key), 5-step quickstart with expected output, Troubleshooting section.
+- **Gemini support marked "coming soon"** — README, config example, and doctor all honestly reflect that Gemini CLI sessions are encrypted protobuf and not yet parseable. The `lm ingest` command prints a clear skip message instead of silently failing.
+- **Config path robustness** — default `dbPath` changed from relative `./data/lancedb` to absolute `~/.recallnest/data/lancedb` in config example. Auto-detect failure messages now include the user's actual home path.
+- **`config.json` untracked** — added to `.gitignore` so user config is not overwritten by `git pull`.
+
+### Fixed
+
+- Auto-detect hint in `doctor` now shows a real example path based on the current user's home directory.
+- `findConfigPath()` error message now suggests `cp config.json.example config.json` when the example file exists.
+
+## v1.1.0 — Hybrid Retrieval + MCP + UI (2026-02)
+
+- Hybrid retrieval: LanceDB vector + BM25 keyword search with configurable weights
+- Retrieval profiles: `default`, `writing`, `debug`, `fact-check`
+- MCP server with 9 tools: search, explain, distill, brief, pin, list assets/pins, export, stats
+- Local web workbench UI at `http://localhost:4317`
+- Multi-source ingest: Claude Code transcripts, Codex sessions, Gemini sessions, markdown notes
+- Asset system: pin, brief, export with re-indexing
+- Time-aware scoring with configurable decay
+
+## v1.0.0 — Initial Release (2026-01)
+
+- Basic vector search over Claude Code transcripts
+- LanceDB storage with Jina embeddings
+- CLI interface

package/README.md

@@ -2,9 +2,9 @@
 
 # RecallNest
 
-**Shared Memory Layer for Claude Code, Codex, and Gemini CLI**
+**Shared Memory Layer for Any MCP Client — Claude Code, Codex, Kimi, Antigravity, Gemini CLI**
 
-*One memory. Three terminals. Context that survives across windows.*
+*One memory. Every terminal. Context that survives across windows.*
 
 A local-first memory system backed by LanceDB that turns scattered conversation history into reusable knowledge — shared across your coding agents, recalled automatically.
 
@@ -12,8 +12,8 @@ A local-first memory system backed by LanceDB that turns scattered conversation
 [![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)
 [![LanceDB](https://img.shields.io/badge/LanceDB-Vector+FTS-orange)](https://lancedb.com)
-[![MCP](https://img.shields.io/badge/MCP-41_tools-blue)](https://modelcontextprotocol.io)
-[![Tests](https://img.shields.io/badge/Tests-1486_pass-brightgreen)](https://github.com/AliceLJY/recallnest)
+[![MCP](https://img.shields.io/badge/MCP-43_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)
 
 **English** | [简体中文](README_CN.md) | [Roadmap](ROADMAP.md)
@@ -24,24 +24,10 @@ A local-first memory system backed by LanceDB that turns scattered conversation
 
 ## Why RecallNest?
 
-Coding agents forget everything between windows. Your context — project configs, debugging decisions, entity mappings — is scattered across Claude Code, Codex, and Gemini CLI with no shared memory.
+Coding agents forget everything between windows. Your context — project configs, debugging decisions, entity mappings — is scattered across Claude Code, Codex, Kimi, Antigravity — and every other terminal you open — with no shared memory.
 
-RecallNest solves this: **a single LanceDB-backed memory layer that all three terminals read and write**. Context stored in one window is auto-recalled in another. Sessions checkpoint on exit and resume on start. Memory decays, evolves, and self-organizes — not just raw log storage.
+RecallNest solves this: **a single LanceDB-backed memory layer that your coding agents read and write**. Context stored in one window is auto-recalled in another. Sessions checkpoint on exit and resume on start. Memory decays, evolves, and self-organizes — not just raw log storage.
 
-### Benchmark: LongMemEval (ICLR 2025)
-
-Evaluated on 500 questions across 6 memory abilities ([methodology](https://arxiv.org/abs/2407.15168)):
-
-| | RecallNest | Vector-only baseline | Delta |
-|---|---|---|---|
-| Overall Accuracy | **29.6%** | 24.2% | **+5.4pp** |
-| User Facts | **64.3%** | 52.9% | +11.4pp |
-| Knowledge Update | **43.6%** | 42.3% | +1.3pp |
-| Abstention Rate | **55.6%** | 67.8% | **-12.2pp** |
-
-Wins or ties in **all 6 categories**, with no regression. The hybrid retrieval pipeline (BM25 + vector + recency + RIF dedup) surfaces 12.2% more relevant context than vector-only search.
-
----
 
 ## Quick Start
 
@@ -54,7 +40,11 @@ Wins or ties in **all 6 categories**, with no regression. The hybrid retrieval p
 
 RecallNest starts automatically with Claude Code. No manual MCP config needed.
 
-> **Requires:** [Bun](https://bun.sh) (recommended) or Node.js 18+. Dependencies install on first start.
+Claude Code prompts for a Jina API key during installation. The key is stored through Claude Code's sensitive plugin configuration, while the generated config and LanceDB database live in the plugin's persistent data directory rather than the versioned plugin cache.
+
+> The Claude Code plugin and npm package share one release version and are updated together.
+>
+> **Requires:** [Bun](https://bun.sh). Dependencies install on first start.
 
 ### Option B: npm install
 
@@ -153,7 +143,7 @@ bun run src/ui-server.ts
 | Capability | Description |
 |---|---|
 | **CC Plugin** | Install in Claude Code with one command — no manual config |
-| **Shared Index** | One LanceDB store for Claude Code, Codex, and Gemini CLI |
+| **Shared Index** | One LanceDB store shared by every terminal that speaks MCP |
 | **Dual Interface** | MCP (stdio) for CLI tools + HTTP API for custom agents |
 | **One-Click Setup** | Integration scripts install MCP access and continuity rules |
 
@@ -167,6 +157,7 @@ bun run src/ui-server.ts
 | **Session Distiller** | 3-layer conversation compression: microcompact → LLM summary → knowledge extraction |
 | **Conversation Import** | Import from Claude Code, Claude.ai, ChatGPT, Slack, and plaintext |
 | **Topic Tags** | Intra-scope topic partitioning — auto-detected, filterable in search |
+| **Related Scope Sidecar** | Opt-in `includeRelatedScopes` search over configured `scopeRelations`, shown separately from the main scoped ranking |
 
 ### Memory Lifecycle & Governance
 
@@ -205,6 +196,26 @@ bun run src/ui-server.ts
 
 ---
 
+## New in v2.6: Reliable Cross-Process Memory and Distribution
+
+v2.6 turns the development since v2.5.4 into a release-ready upgrade:
+
+- **Cross-process visibility** — LanceDB now checks for external commits on every read by default, so resident MCP/API/UI processes see writes from CLI ingestion without a restart. Set `RECALLNEST_READ_CONSISTENCY_INTERVAL=<seconds>` for bounded staleness or `off` for the legacy unchecked behavior.
+- **Safer memory evolution** — belief changes preserve the old row as `superseded`; procedural memories avoid time decay; cold-start and length-normalization behavior no longer suppress short entity queries or stable memories.
+- **More reliable consolidation** — `dream` now distinguishes failure classes, honors wall-clock budgets, refills vectors before semantic clustering, and asserts that successful runs actually produced work.
+- **Broader conversation coverage** — Kimi, AGY/Antigravity, and minis sources are recognized across ingestion, scope boundaries, and term resolution.
+- **One public version** — npm metadata, CLI `--version`, MCP handshakes, HTTP health responses, and the Claude Code marketplace all follow the `2.6.0` release contract.
+- **Installable Claude Code plugin** — installation now registers the 43-tool MCP server and continuity skill, asks for the Jina key through sensitive plugin configuration, and keeps config plus LanceDB data in Claude Code's persistent plugin data directory.
+
+### Upgrading from v2.5.4
+
+- Existing LanceDB data is opened in place. Legacy tables missing newer fields are migrated automatically, including empty tables.
+- Plugin data survives plugin updates because it is stored outside the versioned cache. A manual clone continues to use its existing `config.json` and database path.
+- Retrieval auditing now includes read operations. `audit.jsonl` has no automatic rotation yet; consider archiving it if it approaches 50 MB.
+- `RECALLNEST_LAYER_ADMISSION` remains opt-in (`observe` or `on`); the default is `off`.
+
+---
+
 ## New in v2.1: Philosophy-Informed Memory
 
 v2.0 built the operational memory platform; v2.1 added philosophy-informed memory behavior.
@@ -233,6 +244,8 @@ v2.1 added philosophy-informed behavior; v2.2 closes the last three engine-layer
 
 - **Temporal Validity Windows** *(TSM / TiMem / Zep)* — `store_memory` accepts `validUntil` (expiration) and `eventTime` (when the event actually happened). `search_memory` supports `validAt` (point-in-time query) and `includeExpired` (demote 80% instead of hide). Auto-GC applies 2× decay acceleration to expired memories.
 
+- **Usage-Adjusted Auto-GC** *(off by default)* — `RECALLNEST_USAGE_DECAY=true` enables a GC-only cold-memory penalty when constructive retrieval is also active. Cold memories discount the frequency component instead of changing online retrieval ranking.
+
 ---
 
 ## New in v2.3: Connector Ecosystem + Source Health
@@ -264,7 +277,7 @@ v2.2 hardened retrieval quality; v2.3 opens RecallNest to external data sources
 │                   Integration Layer                       │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  41 tools           │  │  21 endpoints              │ │
+│  │  43 tools           │  │  21 endpoints              │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -310,7 +323,7 @@ v2.2 hardened retrieval quality; v2.3 opens RecallNest to external data sources
 
 RecallNest serves two interfaces:
 
-- **MCP** — for Claude Code, Gemini CLI, and Codex (native tool access)
+- **MCP** — for any MCP client: Claude Code, Codex, Kimi, Antigravity, Gemini CLI (native tool access)
 - **HTTP API** — for custom agents, SDK-based apps, and any HTTP client
 
 ### Agent framework examples
@@ -326,22 +339,23 @@ Examples live in [`integrations/examples/`](integrations/examples/):
 ---
 
 <details>
-<summary><strong>MCP Tools (41 tools)</strong></summary>
+<summary><strong>MCP Tools (43 tools)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
-| `workflow_observe` | Store an append-only workflow observation outside regular memory |
+| `workflow_observe` | Store an append-only workflow observation outside regular memory; accepts `idempotencyKey` for retry-safe writes |
 | `workflow_health` | Inspect workflow observation health or show a degraded-workflow dashboard |
 | `workflow_evidence` | Build an evidence pack for a workflow primitive |
 | `store_memory` | Store a durable memory for future windows |
 | `store_workflow_pattern` | Store a reusable workflow as durable `patterns` memory |
 | `store_case` | Store a reusable problem-solution pair as durable `cases` memory |
 | `promote_memory` | Explicitly promote evidence into durable memory |
+| `promote_scan` | Scan recent evidence and auto-promote qualifying memories into durable storage |
 | `list_conflicts` | List or inspect promotion conflict candidates |
 | `audit_conflicts` | Summarize stale/escalated conflict priorities |
 | `escalate_conflicts` | Preview or apply conflict escalation metadata |
 | `resolve_conflict` | Resolve a stored conflict candidate (keep / accept / merge) |
-| `checkpoint_session` | Store the current active work state outside durable memory |
+| `checkpoint_session` | Store the current active work state outside durable memory; accepts `idempotencyKey` for retry-safe writes |
 | `latest_checkpoint` | Inspect the latest saved checkpoint by session or scope |
 | `resume_context` | Compose startup context for a fresh window |
 | `search_memory` | Proactive recall at task start |
@@ -362,6 +376,7 @@ Examples live in [`integrations/examples/`](integrations/examples/):
 | `store_skill` | Store an executable skill with trigger conditions and verification |
 | `retrieve_skill` | Retrieve matching executable skills by semantic similarity |
 | `scan_skill_promotions` | Scan cases/patterns for promotion candidates to skills |
+| `manage_alias` | Add, remove, list, or explain user query aliases for BM25 retrieval |
 | `list_tools` | Discover available tools by tier (core/advanced/full) |
 | `batch_store` | Store up to 20 memories in a single call with dedup |
 | `distill_session` | Distill a conversation into structured knowledge via 3-layer pipeline |
@@ -417,7 +432,7 @@ 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-observe resume_context "Fresh window skipped continuity recovery." --outcome missed --scope project:recallnest --idempotency-key smoke-2026-06-26
 bun run src/cli.ts workflow-health resume_context --scope project:recallnest
 bun run src/cli.ts workflow-evidence checkpoint_session --scope project:recallnest
 
@@ -484,7 +499,7 @@ RecallNest is actively maintained. All major architecture phases are complete
 RecallNest started as a fork of [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) and shares its core ideas around hybrid retrieval, decay modeling, and memory-as-engineering-system. The key difference:
 
 - **memory-lancedb-pro** is an OpenClaw plugin — it adds long-term memory to a single OpenClaw agent.
-- **RecallNest** is a standalone memory layer — it serves Claude Code, Codex, and Gemini CLI simultaneously through MCP + HTTP API, with session continuity, structured assets, and conflict management built in.
+- **RecallNest** is a standalone memory layer — it serves any MCP client (Claude Code, Codex, Kimi, Antigravity, Gemini CLI) simultaneously through MCP + HTTP API, with session continuity, structured assets, and conflict management built in.
 
 ## Credit
 
@@ -504,18 +519,14 @@ Part of the **小试AI** open-source AI workflow:
 | Project | Description |
 |---------|-------------|
 | [babel-memory](https://github.com/AliceLJY/babel-memory) | Multilingual preprocessing for BM25 — 27+ languages, zero deps |
-| [content-alchemy](https://github.com/AliceLJY/content-alchemy) | 5-stage AI writing pipeline |
-| [content-publisher](https://github.com/AliceLJY/content-publisher) | Image generation + layout + WeChat publishing |
-| [wechat-ai-bridge](https://github.com/AliceLJY/wechat-ai-bridge) | Run Claude Code / Codex / Gemini in WeChat with session management |
+| cc-empire *(private)* | Hooks/rules/methodology — the connective tissue of the whole ecosystem |
 | [telegram-ai-bridge](https://github.com/AliceLJY/telegram-ai-bridge) | Telegram bots for Claude, Codex, and Gemini |
-| [telegram-cli-bridge](https://github.com/AliceLJY/telegram-cli-bridge) | Telegram CLI bridge for Gemini CLI |
-| [openclaw-tunnel](https://github.com/AliceLJY/openclaw-tunnel) | Docker ↔ host CLI bridge (/cc /codex /gemini) |
-| [openclaw-config](https://github.com/AliceLJY/openclaw-config) | OpenClaw bots configuration and memory backup |
+| [tg-bridge-channel](https://github.com/AliceLJY/tg-bridge-channel) | Sister Telegram bridge using Claude Agent View background sessions |
+| [wechat-ai-bridge](https://github.com/AliceLJY/wechat-ai-bridge) | Run Claude Code / Codex / Gemini in WeChat with session management |
+| [openclaw-tunnel](https://github.com/AliceLJY/openclaw-tunnel) | Docker ↔ host CLI bridge (maintenance mode — LanceDB test only) |
 | [digital-clone-skill](https://github.com/AliceLJY/digital-clone-skill) | Build digital clones from corpus data |
 | [claude-code-studio](https://github.com/AliceLJY/claude-code-studio) | Multi-session collaboration platform for Claude Code |
-| [cc-genius](https://github.com/AliceLJY/cc-genius) | Web-based Claude chat client (PWA) — self-hosted, iPad-ready |
-| [agent-nexus](https://github.com/AliceLJY/agent-nexus) | One-command installer for memory + remote control |
-| [cc-cabin](https://github.com/AliceLJY/cc-cabin) | Complete Claude Code workflow scaffold |
+| [workflow-orchestrator](https://github.com/AliceLJY/workflow-orchestrator) | Natural-language pipeline orchestrator for Claude Code |
 
 </details>
 

package/README_CN.md

@@ -2,18 +2,18 @@
 
 # RecallNest
 
-**面向 Claude Code、Codex、Gemini CLI 的共享记忆层**
+**面向任意 MCP 客户端的共享记忆层 —— Claude Code、Codex、Kimi、Antigravity、Gemini CLI**
 
-*一套记忆，三个终端，上下文跨窗口延续。*
+*一套记忆，每个终端，上下文跨窗口延续。*
 
-基于 LanceDB 的本地优先记忆系统，把散落在三个终端的对话历史沉淀为可复用知识，跨终端共享，自动召回。
+基于 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)
 [![LanceDB](https://img.shields.io/badge/LanceDB-Vector+FTS-orange)](https://lancedb.com)
-[![MCP](https://img.shields.io/badge/MCP-41_tools-blue)](https://modelcontextprotocol.io)
-[![Tests](https://img.shields.io/badge/Tests-1486_pass-brightgreen)](https://github.com/AliceLJY/recallnest)
+[![MCP](https://img.shields.io/badge/MCP-43_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)
 
 [English](README.md) | **简体中文** | [Roadmap](ROADMAP.md)
@@ -24,24 +24,10 @@
 
 ## 为什么需要 RecallNest？
 
-编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Gemini CLI 三个终端里，互相不通。
+编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Kimi、Antigravity 以及你打开的每一个终端里，互相不通。
 
-RecallNest 的解法：**一个 LanceDB 驱动的记忆层，三个终端共读共写**。一个窗口存入的上下文，另一个窗口自动召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——不是简单的日志堆积。
+RecallNest 的解法：**一个 LanceDB 驱动的记忆层，供你的编程 Agent 共读共写**。一个窗口存入的上下文，另一个窗口自动召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——不是简单的日志堆积。
 
-### 基准测试：LongMemEval (ICLR 2025)
-
-在 6 项记忆能力、500 个问题上评估（[评测方法](https://arxiv.org/abs/2407.15168)）：
-
-| | 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** |
-
-**全部 6 项胜出或持平**，无任何退步。混合检索管线（BM25 + 向量 + 时效性 + RIF 去重）比纯向量搜索多召回 12.2% 的相关上下文。
-
----
 
 ## 快速开始
 
@@ -54,7 +40,11 @@ RecallNest 的解法：**一个 LanceDB 驱动的记忆层，三个终端共读
 
 RecallNest 随 Claude Code 自动启动，无需手动配置 MCP。
 
-> **前置要求：** [Bun](https://bun.sh)（推荐）或 Node.js 18+。首次启动自动安装依赖。
+安装时 Claude Code 会提示填写 Jina API key。密钥由 Claude Code 的敏感插件配置保存；自动生成的配置和 LanceDB 数据库则放在插件持久数据目录，不会混进按版本更新的插件缓存。
+
+> Claude Code 插件与 npm 包共用同一个发布版本，并随版本发布同步更新。
+>
+> **前置要求：** [Bun](https://bun.sh)。首次启动自动安装依赖。
 
 ### 方式 B：npm 安装
 
@@ -153,7 +143,7 @@ bun run src/ui-server.ts
 | 能力 | 说明 |
 |---|---|
 | **CC Plugin** | 一行命令装入 Claude Code，无需手动配置 MCP |
-| **共享索引** | Claude Code、Codex、Gemini CLI 共用同一个 LanceDB 存储 |
+| **共享索引** | 所有支持 MCP 的终端共用同一个 LanceDB 存储 |
 | **双通道接入** | MCP（stdio）给 CLI 工具 + HTTP API 给自定义 Agent |
 | **一键接入** | 集成脚本同时安装 MCP 和 continuity 规则 |
 
@@ -167,6 +157,7 @@ bun run src/ui-server.ts
 | **会话蒸馏** | 3 层对话压缩：微缩 → LLM 结构化摘要 → 知识提取 |
 | **对话导入** | 支持 Claude Code、Claude.ai、ChatGPT、Slack、纯文本 |
 | **Topic Tags** | scope 内 topic 分区，自动检测，搜索时可过滤 |
+| **关联 scope 侧栏** | 显式传 `includeRelatedScopes` 时，按 `scopeRelations` 白名单额外检索，并和主 scope 排序分开展示 |
 
 ### 记忆生命周期与治理
 
@@ -205,6 +196,26 @@ bun run src/ui-server.ts
 
 ---
 
+## v2.6 新增：跨进程一致性与可靠分发
+
+v2.6 把 v2.5.4 以来的开发整理成一版可升级、可安装、版本口径一致的正式候选：
+
+- **跨进程即时可见** —— 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 的持久插件数据目录。
+
+### 从 v2.5.4 升级
+
+- 现有 LanceDB 数据原地打开；缺少新字段的旧表会自动迁移，空表也覆盖。
+- 插件数据位于版本缓存之外，更新插件不会清空；手动 clone 仍沿用现有 `config.json` 与数据库路径。
+- 检索操作现已写入审计日志。`audit.jsonl` 暂无自动轮转，接近 50 MB 时建议人工归档。
+- `RECALLNEST_LAYER_ADMISSION` 仍是显式开启项（`observe` 或 `on`），默认 `off`。
+
+---
+
 ## v2.1 新增：记忆哲学驱动的架构升级
 
 v2.0 建立了完整的记忆操作平台；v2.1 加入了记忆哲学驱动的记忆行为。
@@ -233,6 +244,8 @@ v2.1 加入了哲学记忆行为；v2.2 补齐前沿扫描（ACC、PI-LLM、TSM
 
 - **时间有效性窗口** *（TSM / TiMem / Zep）* —— `store_memory` 接受 `validUntil`（过期时间）和 `eventTime`（事件发生时间）。`search_memory` 支持 `validAt`（时间点查询）和 `includeExpired`（降权 80% 而非隐藏）。auto-GC 对过期记忆施加 2 倍衰减加速。
 
+- **Usage-adjusted Auto-GC** *（默认关闭）* —— `RECALLNEST_USAGE_DECAY=true` 且建构式检索 use 信号开启时，GC 专用分支才会对 cold 记忆的 frequency 项打折；在线检索排序不读取这个分支。
+
 ---
 
 ## v2.3 新增：Connector 生态 + 数据源健康
@@ -264,7 +277,7 @@ v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康
 │                      集成层                               │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  41 个工具           │  │  21 个端点                  │ │
+│  │  43 个工具           │  │  21 个端点                  │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -309,7 +322,7 @@ v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康
 
 RecallNest 提供两种接口：
 
-- **MCP** —— 给 Claude Code、Gemini CLI、Codex 使用（原生工具访问）
+- **MCP** —— 给任意 MCP 客户端使用：Claude Code、Codex、Kimi、Antigravity、Gemini CLI（原生工具访问）
 - **HTTP API** —— 给自定义 Agent、SDK 应用和任何 HTTP 客户端使用
 
 ### Agent 框架示例
@@ -325,22 +338,23 @@ RecallNest 提供两种接口：
 ---
 
 <details>
-<summary><strong>MCP 工具（41 个）</strong></summary>
+<summary><strong>MCP 工具（43 个）</strong></summary>
 
 | 工具 | 说明 |
 |------|------|
-| `workflow_observe` | 存储 append-only 工作流观察记录 |
+| `workflow_observe` | 存储 append-only 工作流观察记录；支持 `idempotencyKey` 防重复写入 |
 | `workflow_health` | 查看工作流健康状态或降级面板 |
 | `workflow_evidence` | 构建工作流证据包 |
 | `store_memory` | 存储一条持久记忆 |
 | `store_workflow_pattern` | 存储可复用工作流模式 |
 | `store_case` | 存储问题-方案对 |
 | `promote_memory` | 显式升级 evidence 为持久记忆 |
+| `promote_scan` | 扫描近期 evidence，自动晋升合格记忆为持久存储 |
 | `list_conflicts` | 列出或查看冲突候选 |
 | `audit_conflicts` | 汇总过期/升级的冲突优先级 |
 | `escalate_conflicts` | 预览或应用冲突升级元数据 |
 | `resolve_conflict` | 解决冲突（保留 / 接受 / 合并） |
-| `checkpoint_session` | 保存当前工作状态 |
+| `checkpoint_session` | 保存当前工作状态；支持 `idempotencyKey` 防重复写入 |
 | `latest_checkpoint` | 查看最近的 checkpoint |
 | `resume_context` | 为新窗口编排启动上下文 |
 | `search_memory` | 任务开始时主动召回 |
@@ -361,6 +375,7 @@ RecallNest 提供两种接口：
 | `store_skill` | 存储可执行技能 |
 | `retrieve_skill` | 按语义相似度检索技能 |
 | `scan_skill_promotions` | 扫描可升级为技能的候选 |
+| `manage_alias` | 新增、删除、列出或解释 BM25 用户查询别名 |
 | `list_tools` | 按层级发现工具（core/advanced/full） |
 | `batch_store` | 批量存储最多 20 条记忆 |
 | `distill_session` | 三层管线蒸馏对话为结构化知识 |
@@ -416,7 +431,7 @@ bun run src/cli.ts distill "topic" --profile writing
 bun run src/cli.ts stats
 
 # 工作流观察
-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-observe resume_context "Fresh window skipped continuity recovery." --outcome missed --scope project:recallnest --idempotency-key smoke-2026-06-26
 bun run src/cli.ts workflow-health resume_context --scope project:recallnest
 bun run src/cli.ts workflow-evidence checkpoint_session --scope project:recallnest
 
@@ -483,7 +498,7 @@ RecallNest 持续维护中。所有主要架构阶段已完成——完整路线
 RecallNest 起源于 [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) 的 fork，共享混合检索、衰减建模、记忆即系统的核心理念。关键区别：
 
 - **memory-lancedb-pro** 是 OpenClaw 插件——为单个 OpenClaw Agent 添加长期记忆。
-- **RecallNest** 是独立记忆层——通过 MCP + HTTP API 同时服务 Claude Code、Codex、Gemini CLI，内建会话连续性、结构化资产和冲突管理。
+- **RecallNest** 是独立记忆层——通过 MCP + HTTP API 同时服务任意 MCP 客户端（Claude Code、Codex、Kimi、Antigravity、Gemini CLI），内建会话连续性、结构化资产和冲突管理。
 
 ## 致谢
 
@@ -514,7 +529,7 @@ RecallNest 起源于 [memory-lancedb-pro](https://github.com/CortexReach/memory-
 | [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 完整工作流脚手架 |
+| cc-empire *(private)* | Claude Code 完整工作流脚手架 |
 
 </details>