recallnest 2.3.0 → 2.5.4

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+## 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

@@ -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)
+[![Tests](https://img.shields.io/badge/Tests-1742_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_CN.md) | [Roadmap](ROADMAP.md)
@@ -26,22 +26,8 @@ A local-first memory system backed by LanceDB that turns scattered conversation
 
 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.
 
-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
 
@@ -167,6 +153,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
 
@@ -233,6 +220,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 +253,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              │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -326,22 +315,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 |
@@ -417,7 +407,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
 
@@ -504,18 +494,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](https://github.com/AliceLJY/cc-empire) | 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

@@ -12,8 +12,8 @@
 [![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)
+[![Tests](https://img.shields.io/badge/Tests-1573_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)
@@ -26,22 +26,8 @@
 
 编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Gemini CLI 三个终端里，互相不通。
 
-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% 的相关上下文。
-
----
 
 ## 快速开始
 
@@ -167,6 +153,7 @@ bun run src/ui-server.ts
 | **会话蒸馏** | 3 层对话压缩：微缩 → LLM 结构化摘要 → 知识提取 |
 | **对话导入** | 支持 Claude Code、Claude.ai、ChatGPT、Slack、纯文本 |
 | **Topic Tags** | scope 内 topic 分区，自动检测，搜索时可过滤 |
+| **关联 scope 侧栏** | 显式传 `includeRelatedScopes` 时，按 `scopeRelations` 白名单额外检索，并和主 scope 排序分开展示 |
 
 ### 记忆生命周期与治理
 
@@ -233,6 +220,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 +253,7 @@ v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康
 │                      集成层                               │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  41 个工具           │  │  21 个端点                  │ │
+│  │  42 个工具           │  │  21 个端点                  │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -325,22 +314,23 @@ RecallNest 提供两种接口：
 ---
 
 <details>
-<summary><strong>MCP 工具（41 个）</strong></summary>
+<summary><strong>MCP 工具（42 个）</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` | 任务开始时主动召回 |
@@ -416,7 +406,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