recallnest 2.5.4 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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、集成脚本和必要文档。

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.
 
@@ -13,7 +13,7 @@ A local-first memory system backed by LanceDB that turns scattered conversation
 [![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-43_tools-blue)](https://modelcontextprotocol.io)
-[![Tests](https://img.shields.io/badge/Tests-1742_pass-brightgreen)](https://github.com/AliceLJY/recallnest)
+[![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,7 +24,7 @@ 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 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.
 
@@ -40,7 +40,11 @@ RecallNest solves this: **a single LanceDB-backed memory layer that your coding
 
 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
 
@@ -139,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 |
 
@@ -192,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.
@@ -299,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
@@ -352,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 |
@@ -474,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
 
@@ -494,7 +519,7 @@ 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 |
-| [cc-empire](https://github.com/AliceLJY/cc-empire) | Hooks/rules/methodology — the connective tissue of the whole ecosystem |
+| 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 |
 | [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 |

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-43_tools-blue)](https://modelcontextprotocol.io)
-[![Tests](https://img.shields.io/badge/Tests-1573_pass-brightgreen)](https://github.com/AliceLJY/recallnest)
+[![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,7 +24,7 @@
 
 ## 为什么需要 RecallNest？
 
-编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Gemini CLI 三个终端里，互相不通。
+编程 Agent 每开一个窗口就失忆。项目配置、调试决策、实体映射——散落在 Claude Code、Codex、Kimi、Antigravity 以及你打开的每一个终端里，互相不通。
 
 RecallNest 的解法：**一个 LanceDB 驱动的记忆层，供你的编程 Agent 共读共写**。一个窗口存入的上下文，另一个窗口自动召回。会话退出时 checkpoint，启动时 resume。记忆会衰减、演化、自组织——不是简单的日志堆积。
 
@@ -40,7 +40,11 @@ RecallNest 的解法：**一个 LanceDB 驱动的记忆层，供你的编程 Age
 
 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 安装
 
@@ -139,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 规则 |
 
@@ -192,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 加入了记忆哲学驱动的记忆行为。
@@ -253,7 +277,7 @@ v2.2 强化了检索质量；v2.3 通过标准 Connector 框架和运维健康
 │                      集成层                               │
 │  ┌─────────────────────┐  ┌────────────────────────────┐ │
 │  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  42 个工具           │  │  21 个端点                  │ │
+│  │  43 个工具           │  │  21 个端点                  │ │
 │  └─────────┬───────────┘  └──────────┬─────────────────┘ │
 └────────────┼─────────────────────────┼───────────────────┘
              └──────────┬──────────────┘
@@ -298,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 框架示例
@@ -314,7 +338,7 @@ RecallNest 提供两种接口：
 ---
 
 <details>
-<summary><strong>MCP 工具（42 个）</strong></summary>
+<summary><strong>MCP 工具（43 个）</strong></summary>
 
 | 工具 | 说明 |
 |------|------|
@@ -351,6 +375,7 @@ RecallNest 提供两种接口：
 | `store_skill` | 存储可执行技能 |
 | `retrieve_skill` | 按语义相似度检索技能 |
 | `scan_skill_promotions` | 扫描可升级为技能的候选 |
+| `manage_alias` | 新增、删除、列出或解释 BM25 用户查询别名 |
 | `list_tools` | 按层级发现工具（core/advanced/full） |
 | `batch_store` | 批量存储最多 20 条记忆 |
 | `distill_session` | 三层管线蒸馏对话为结构化知识 |
@@ -473,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），内建会话连续性、结构化资产和冲突管理。
 
 ## 致谢
 
@@ -504,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>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "recallnest",
-  "version": "2.5.4",
-  "description": "RecallNest \u2014 MCP-native, local-first memory search and distillation for AI conversations",
+  "version": "2.6.0",
+  "description": "RecallNest — MCP-native, local-first memory search and distillation for AI conversations",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -61,14 +61,14 @@
   },
   "dependencies": {
     "@lancedb/lancedb": "^0.26.0",
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
     "openai": "^4.0.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
-    "babel-memory": ">=1.0.0"
+    "babel-memory": "^2.1.1"
   },
   "repository": {
     "type": "git",

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

@@ -236,3 +236,69 @@ describe("destroy cleans cooldown", () => {
     expect(tracker.shouldReinforce("a", 0.40)).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Distinct-reader bookkeeping (Artel read fan-out) + default-config semantics
+// ---------------------------------------------------------------------------
+
+describe("default config after 2026-07-23 production fix", () => {
+  it("novelty gate is OFF by default (high-similarity hits are reinforced)", () => {
+    const tracker = new AccessTracker(createMockStore([]) as any);
+    // 生产实测修复：真实相关命中 cosine >0.65 也必须打点
+    expect(tracker.shouldReinforce("a", 0.95)).toBe(true);
+  });
+});
+
+describe("distinct-reader bookkeeping", () => {
+  it("writes readerIds and distinctReaderCount on flush", async () => {
+    const entries = [makeEntry("a")];
+    const store = createMockStore(entries);
+    const tracker = new AccessTracker(store as any, {
+      ...DEFAULT_ACCESS_TRACKER_CONFIG,
+      flushIntervalMs: 1,
+      cooldownMs: 0,
+    });
+    tracker.recordAccess(["a"]);
+    await tracker.flush();
+
+    const meta = JSON.parse(store.data.get("a")!.metadata!) as Record<string, unknown>;
+    expect(meta.accessCount).toBe(1);
+    expect(meta.readerIds).toEqual([tracker.readerId]);
+    expect(meta.distinctReaderCount).toBe(1);
+  });
+
+  it("dedups same reader and unions different readers", async () => {
+    const entries = [makeEntry("a")];
+    const store = createMockStore(entries);
+    const t1 = new AccessTracker(store as any, { ...DEFAULT_ACCESS_TRACKER_CONFIG, flushIntervalMs: 1, cooldownMs: 0 });
+    t1.recordAccess(["a"]);
+    await t1.flush();
+    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 });
+    t2.recordAccess(["a"]);
+    await t2.flush(); // second reader → 2 distinct
+
+    const meta = JSON.parse(store.data.get("a")!.metadata!) as Record<string, unknown>;
+    expect(meta.accessCount).toBe(3);
+    expect((meta.readerIds as string[]).sort()).toEqual([t1.readerId, t2.readerId].sort());
+    expect(meta.distinctReaderCount).toBe(2);
+  });
+
+  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", {
+      metadata: JSON.stringify({ accessCount: 8, readerIds: capped, distinctReaderCount: 8 }),
+    })];
+    const store = createMockStore(entries);
+    const tracker = new AccessTracker(store as any, { ...DEFAULT_ACCESS_TRACKER_CONFIG, flushIntervalMs: 1, cooldownMs: 0 });
+    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(8); // no growth past cap
+    expect(meta.distinctReaderCount).toBe(8);            // saturates, no overcount
+    expect(meta.accessCount).toBe(9);                    // access still counted
+  });
+});

package/src/__tests__/api-server-security.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  enforceLocalHttpRequestPolicy,
+  LOCAL_JSON_BODY_LIMIT_BYTES,
+} from "../http-request-policy.js";
+
+function apiRequest({
+  method = "GET",
+  host = "localhost:4318",
+  headers = {},
+  body,
+}: {
+  method?: string;
+  host?: string;
+  headers?: Record<string, string>;
+  body?: string;
+} = {}): Request {
+  return new Request("http://localhost:4318/v1/store", {
+    method,
+    headers: { host, ...headers },
+    body,
+  });
+}
+
+describe("RecallNest API local HTTP policy", () => {
+  test("keeps local CLI JSON requests without Origin usable", async () => {
+    const result = await enforceLocalHttpRequestPolicy(apiRequest({
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ text: "local CLI", scope: "test:local" }),
+    }));
+
+    expect(result).toEqual({ allowed: true });
+  });
+
+  test("allows loopback GET requests without browser headers", async () => {
+    const result = await enforceLocalHttpRequestPolicy(apiRequest());
+
+    expect(result).toEqual({ allowed: true });
+  });
+
+  test("rejects malformed or non-local Host headers", async () => {
+    const malformed = await enforceLocalHttpRequestPolicy(apiRequest({ host: "localhost@attacker.example" }));
+    const nonLocal = await enforceLocalHttpRequestPolicy(apiRequest({ host: "192.168.1.10:4318" }));
+
+    expect(malformed).toEqual({ allowed: false, status: 403, message: "Host is not allowed." });
+    expect(nonLocal).toEqual({ allowed: false, status: 403, message: "Host is not allowed." });
+  });
+
+  test("rejects opaque origins and same-site cross-origin requests", async () => {
+    const opaqueOrigin = await enforceLocalHttpRequestPolicy(apiRequest({
+      headers: { origin: "null" },
+    }));
+    const sameSite = await enforceLocalHttpRequestPolicy(apiRequest({
+      headers: { "sec-fetch-site": "same-site" },
+    }));
+
+    expect(opaqueOrigin).toEqual({ allowed: false, status: 403, message: "Origin is not allowed." });
+    expect(sameSite).toEqual({ allowed: false, status: 403, message: "Cross-site requests are not allowed." });
+  });
+
+  test("requires application/json for API POST requests", async () => {
+    const missing = await enforceLocalHttpRequestPolicy(apiRequest({
+      method: "POST",
+      body: "{}",
+    }));
+    const form = await enforceLocalHttpRequestPolicy(apiRequest({
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: "text=example",
+    }));
+
+    expect(missing).toEqual({
+      allowed: false,
+      status: 415,
+      message: "Content-Type must be application/json.",
+    });
+    expect(form).toEqual({
+      allowed: false,
+      status: 415,
+      message: "Content-Type must be application/json.",
+    });
+  });
+
+  test("rejects declared JSON bodies over the limit before route handling", async () => {
+    const result = await enforceLocalHttpRequestPolicy(apiRequest({
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "content-length": String(LOCAL_JSON_BODY_LIMIT_BYTES + 1),
+      },
+      body: "{}",
+    }));
+
+    expect(result).toEqual({
+      allowed: false,
+      status: 413,
+      message: `Request body exceeds ${LOCAL_JSON_BODY_LIMIT_BYTES} bytes.`,
+    });
+  });
+});