recallnest 2.6.1 → 3.0.1

package/README.md

@@ -2,17 +2,17 @@
 
 # RecallNest
 
-**Shared Memory Layer for Any MCP Client — Claude Code, Codex, Kimi, Antigravity, Gemini CLI**
+**Shared Memory Layer for Every AI Client — CLI agents, desktop apps, your own scripts**
 
-*One memory. Every terminal. Context that survives across windows.*
+*One memory. Every client. Context that survives across windows — and across machines.*
 
 A local-first memory system backed by LanceDB that turns scattered conversation history into reusable knowledge — shared across your coding agents, recalled automatically.
 
 [![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)
 
@@ -26,115 +26,38 @@ 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, 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.
+RecallNest is **one LanceDB-backed memory layer that all of them read and write**. Context stored in one window is recalled in another. Sessions checkpoint on exit and resume on start. Memory decays, evolves, and self-organizes — it is not a log you grep.
 
+### What a recall actually looks like
 
-## Quick Start
-
-### Option A: Claude Code Plugin (recommended)
+```text
+Query   : deploy rollback
+Hits    : 5
 
-```bash
-/plugin marketplace add AliceLJY/recallnest
-/plugin install recallnest@AliceLJY
+#  ID       Score Category  Tier        Source  Date        Age  Retrieval Path
+1  ee79037a 46.1% cases     peripheral  cc      2026-08-25  2d   vector
+   [assistant] Rolled back to the previous image and pinned the digest so the next…
+   prov : evidence/transcript-ingest
+   imgs : 52 agent-made in this session · read sess=dca70d4a
 ```
 
-RecallNest starts automatically with Claude Code. No manual MCP config needed.
-
-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.
+Three things in that block carry most of the design:
 
-> 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.
+- **`Source cc` · `Age 2d`** — this came out of a Claude Code window two days ago and you
+  are reading it from a different terminal, possibly on a different machine. That is the
+  premise the whole project is built on.
+- **`prov : evidence/…`** — every row states which layer it sits on. A fragment scraped out
+  of a transcript never gets to pose as a decision you actually made; moving to durable
+  memory is a separate, gated step with its own evidence requirement.
+- **`imgs : …`** — that session contained 52 images. **Not one of them is in the database.**
+  The line exists so you know there is something to go look at, and producing it cost no
+  model call, no vector, and no storage.
 
-### Option B: npm install
+That last one is the approach in miniature: **store what makes a thing findable, not
+everything that could ever be asked about it.** The full reasoning — including the two
+places where the obvious implementation was wrong — is in
+[Images: addressable, not embedded](#images-addressable-not-embedded).
 
-```bash
-npx recallnest --help          # run directly
-# or
-npm install -g recallnest      # install globally
-recallnest doctor
-```
-
-Works with Node.js 18+ (via tsx) or Bun. No git clone needed.
-
-### Option C: Manual setup
-
-```bash
-git clone https://github.com/AliceLJY/recallnest.git
-cd recallnest
-bun install
-cp config.json.example config.json
-cp .env.example .env
-# Edit .env → add your JINA_API_KEY
-```
-
-### Start the server
-
-```bash
-bun run api
-# → RecallNest API running at http://localhost:4318
-```
-
-### Try it
-
-```bash
-# Store a memory
-curl -X POST http://localhost:4318/v1/store \
-  -H "Content-Type: application/json" \
-  -d '{"text": "User prefers dark mode", "category": "preferences"}'
-
-# Recall memories
-curl -X POST http://localhost:4318/v1/recall \
-  -H "Content-Type: application/json" \
-  -d '{"query": "user preferences"}'
-
-# Check stats
-curl http://localhost:4318/v1/stats
-```
-
-### Connect your terminals
-
-```bash
-bash integrations/claude-code/setup.sh
-bash integrations/gemini-cli/setup.sh
-bash integrations/codex/setup.sh
-```
-
-Each script installs MCP access and managed continuity rules, so `resume_context` fires automatically in fresh windows.
-
-### Index existing conversations
-
-```bash
-bun run src/cli.ts ingest --source all
-bun run seed:continuity
-bun run src/cli.ts doctor
-```
-
----
-
-## Web UI
-
-<p align="center">
-  <img src="assets/dashboard.png" alt="RecallNest Dashboard" width="800" />
-  <br><em>Dashboard — total count, category distribution, health score, and growth trends at a glance.</em>
-</p>
-
-<p align="center">
-  <img src="assets/screenshots/ui-full.png" alt="RecallNest Search Workbench" width="800" />
-  <br><em>Search Workbench — hybrid search with topic tag filtering, 4 retrieval profiles, Skills browser, and asset management.</em>
-</p>
-
-<p align="center">
-  <img src="assets/knowledge-graph.png" alt="RecallNest Knowledge Graph" width="800" />
-  <br><em>Knowledge Graph — interactive force-directed visualization with semantic bridges revealing cross-domain connections.</em>
-</p>
-
-```bash
-bun run src/ui-server.ts
-# → http://localhost:4317
-```
-
----
 
 ## Core Capabilities
 
@@ -196,134 +119,251 @@ bun run src/ui-server.ts
 
 ---
 
-## New in v2.6: Reliable Cross-Process Memory and Distribution
+## Architecture
 
-v2.6 turns the development since v2.5.4 into a release-ready upgrade:
+```
+  CLIENTS                    ACCESS                      CORE ENGINE                    STORAGE
+  ──────────────────────     ───────────────────────     ────────────────────────────   ──────────────────────
+
+  Claude Code                MCP over stdio              Retriever                      LanceDB
+  Codex                ───▶  44 tools, 3 tiers    ───▶   vector + BM25 + RRF     ───▶   vector + columnar
+  Kimi · Antigravity                                     Classifier · 6 categories
+  Doubao desktop                                         Context composer
+                             HTTP API :4318              resume_context                 Jina embeddings v5
+  your scripts · cron  ───▶  21 endpoints          ───▶  Decay · Weibull half-life ─▶   1024-dim, task-aware
+                                                         Conflict · audit + merge
+  phone app            ───▶  read-only gateway     ───▶  Capture: evidence → durable
+                             :8791, token-gated
+```
 
-- **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.
+### Internal Design
 
-### Upgrading from v2.5.4
+- **L0 / L1 / L2 Dynamic Folding** — every memory stores 3 granularity layers (one-liner / bullet summary / full content); retrieval dynamically selects which layer to return based on relevance score and token budget
+- **Weibull Decay + Emotion Modulation** — memories decay along a parametric Weibull curve; importance scores modulate the half-life, and emotional salience extends it further (up to 30%)
+- **Vector Pre-filter + LLM Dedup** — 90% of dedup decisions use cheap cosine similarity (>= 0.92); only borderline cases invoke LLM judgment, keeping costs low without sacrificing accuracy
+- **Category-Aware Merge Strategies** — `profile` and `preferences` use merge-on-conflict (latest wins); `events` and `cases` use append-only (history preserved)
+- **Display Score vs Elimination Score** — dual-track retrieval: tier floor prevents core memories from ever dropping out, while decay boost lets fresh memories surface temporarily without permanently displacing stable ones
 
-- 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`.
+> Full architecture deep-dive: [`docs/architecture.md`](docs/architecture.md)
 
 ---
 
-## New in v2.1: Philosophy-Informed Memory
+## Who Can Connect
 
-v2.0 built the operational memory platform; v2.1 added philosophy-informed memory behavior.
+**The data layer does not know what your client looks like.** RecallNest exposes the same LanceDB store through three outlets, so the right one is picked per client — not per protocol.
 
-Five upgrades derived from 9 research dimensions in philosophy of memory, each mapped to concrete engineering:
+| What your client can do | Route | Verified with |
+|---|---|---|
+| Run a local command (CLI agent) | **MCP over stdio** | Claude Code, Codex, Kimi, Antigravity |
+| Run a local command (GUI app, MCP config filled by hand) | **MCP over stdio** | Doubao desktop — same shape as Cherry Studio / ChatBox |
+| Only speak HTTP | **HTTP API** | custom agents, scripts, cron |
+| Run on another machine | swap the stdio command for `ssh <host> recallnest-mcp` | four clients on a laptop reading one store on a home server |
 
-- **Emotion-Aware Decay** *(Affective Memory Theory)* — Memories with strong emotional content decay 20-30% slower. Keyword-based emotion detection computes `salience` (mnemonic significance), which feeds into the Weibull half-life formula and a rebalanced 4-factor evolution score. Zero LLM cost.
+Two consequences worth stating plainly:
 
-- **Memory Ethics Layer** *(Right to Be Forgotten / GDPR Art. 17)* — Four privacy tiers (`ephemeral` / `private` / `durable` / `shared`). Cascade forgetting engine that propagates deletion through KG triples, evolution chains, pin assets, and briefs. Full audit trail. `forget_memory` MCP tool for agent-driven deletion.
+- **Not tied to one protocol.** A GUI chat app that supports MCP config connects the same way a terminal agent does. A client that can only issue HTTP requests still reads the same memory.
+- **Not tied to one machine.** Because the MCP transport is stdio, the launch command is yours to define — point it at `ssh` and every client on every machine shares a single source of truth instead of each host growing its own database.
 
-- **Autobiographical Narrative** *(Narrative Identity Theory / Conway's 3-layer model)* — Memories are tagged with `lifePeriod → generalEvent → specificEvent` hierarchy, orthogonal to existing 6 categories. Retrieval pulls narrative siblings. Context rendering groups by life period. Rule-based tagger with EN+CN support.
+Adding a client does not mean changing RecallNest. A capable client writes one config line; a limited one gets a thin gateway in front of the HTTP API.
 
-- **Constructive Retrieval** *(Simulation Theory / Michaelian)* — Instead of returning raw stored text, RecallNest now reconstructs context from an expanded candidate set: KG neighbors + evolution chains + cluster members + narrative siblings. Source-map grounded coverage replaces lexical overlap. Contradictions are detected and flagged.
+### AI apps on a phone: the read-only gateway
 
-- **Predictive Prospective Memory** *(Mental Time Travel / Tulving)* — Heuristic prediction engine that surfaces "you might need this" reminders from behavioral signals: stale checkpoint open loops, corrected workflow observations, high-frequency dormant memories, and uncovered query topics. Zero LLM cost. Auto-expire in 7 days if unaccepted.
+The HTTP API (`:4318`) binds to `127.0.0.1` and rejects any request whose Host header is not local. That is **deliberate** — it also exposes write routes (`/v1/store`, `/v1/checkpoint`), so putting it on a public address would hand out write access.
 
----
+To let an AI app on your phone read the same memory, put a read-only gateway in front:
 
-## New in v2.2: Retrieval Quality Hardening
+```bash
+openssl rand -hex 32 > ~/.config/recallnest/gateway-token
+chmod 600 ~/.config/recallnest/gateway-token
 
-v2.1 added philosophy-informed behavior; v2.2 closes the last three engine-layer gaps identified by a frontier research scan (ACC, PI-LLM, TSM).
+bun run api        # local API on :4318
+bun run gateway    # read-only gateway on :8791 → forwards to :4318
+```
 
-- **Memory Confidence Meta-tags** *(ACC / Dual-Process UQ)* — Each memory now carries structured `ConfidenceMetadata` (score, reliability tier: `direct` / `inferred` / `hearsay`). Auto-assigned from source on write (`manual` = 0.9, `agent` = 0.7, `conversation_import` = 0.5). Retrieval scores are weighted by confidence. `resume_context` tags low-confidence items with `[低置信]`.
+The gateway allows read routes only (`/recall`, `/search`, `/stats`, `/health`); **every write route is a 404**. Bearer token compared in constant time, per-minute rate limit, hard caps on request and response size. Put it behind a tunnel (Tailscale Serve/Funnel, Cloudflare Tunnel, …) to reach it from a phone.
 
-- **Interference Detection + Active Forgetting Gate** *(PI-LLM / SleepGate)* — Semantic cluster detection identifies groups of near-duplicate memories competing for retrieval. Enhanced RIF keeps only top-K (default 3) per cluster; extras are demoted 50% instead of removed. Write-time pre-warning: when a scope accumulates ≥5 high-similarity active memories, the weakest is flagged `pending_review`. `data_checkup` reports interference density.
+```bash
+curl -X POST https://<your-tunnel>/recall \
+  -H "Authorization: Bearer $(cat ~/.config/recallnest/gateway-token)" \
+  -H 'content-type: application/json' \
+  -d '{"query":"how did we fix that deploy issue","limit":3,"allScopes":true}'
+```
 
-- **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.
+Optional: set `RECALLNEST_GATEWAY_FILE_ROOTS="notes=/abs/path,wiki=/abs/path"` to add `GET /files/search`, a read-only ripgrep search over markdown directories you name (the query is passed as an argv element, never through a shell). Leave it unset and the route does not exist.
 
-- **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.
+> The gateway also binds to `127.0.0.1` by default — exposing it is the tunnel's job. Evaluate that risk yourself.
 
----
+This is how the author connected [OpenMinis](https://github.com/OpenMinis/OpenMinis) on an iPhone: the phone app reaches the gateway over a Tailscale Funnel and queries the same memory store. The interesting part is what it reads back — its own history. Those conversations get exported, flow back, and are indexed, so a phone agent that cold-starts every time ends up with memory that survives its sessions.
 
-## New in v2.3: Connector Ecosystem + Source Health
 
-v2.2 hardened retrieval quality; v2.3 opens RecallNest to external data sources with a standard connector framework and operational health monitoring.
 
-- **Connector-v1 Standard** *(GB-2)* — A JSON format (`ConnectorOutputV1`) that any external script can produce. Obsidian vaults, emails, RSS feeds, log files — normalize once, ingest through the full dedup/embed/extract pipeline. See [`docs/connector-spec.md`](docs/connector-spec.md) for the specification and [`connectors/examples/`](connectors/examples/) for adapter skeletons (email, logs, RSS).
+## Quick Start
 
-- **Obsidian Vault Ingestion** *(GB-1)* — First-party Obsidian connector: scans `.md` files, extracts frontmatter + wikilinks, maps folder structure to tags. One command: `lm ingest --obsidian /path/to/vault`.
+### Option A: Claude Code Plugin (recommended)
 
-- **Source Health Monitoring** *(GB-3)* — Every connector ingest writes a heartbeat to `data/source-heartbeat.json`. `data_checkup` flags stale sources (>7d warning, >30d error). `doctor --ci` shows a per-source heartbeat summary with human-readable age.
+```bash
+/plugin marketplace add AliceLJY/recallnest
+/plugin install recallnest@AliceLJY
+```
 
----
+RecallNest starts automatically with Claude Code. No manual MCP config needed.
 
-## Architecture
+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
+
+```bash
+npx recallnest --help          # run directly
+# or
+npm install -g recallnest      # install globally
+recallnest doctor
 ```
-┌──────────────────────────────────────────────────────────┐
-│                     Client Layer                          │
-├──────────┬──────────┬──────────┬──────────────────────────┤
-│ Claude   │ Gemini   │ Codex    │ Custom Agents / curl     │
-│ Code     │ CLI      │          │                          │
-└────┬─────┴────┬─────┴────┬─────┴──────┬──────────────────┘
-     │          │          │            │
-     └──── MCP (stdio) ───┘     HTTP API (port 4318)
-                │                       │
-                ▼                       ▼
-┌──────────────────────────────────────────────────────────┐
-│                   Integration Layer                       │
-│  ┌─────────────────────┐  ┌────────────────────────────┐ │
-│  │  MCP Server         │  │  HTTP API Server           │ │
-│  │  43 tools           │  │  21 endpoints              │ │
-│  └─────────┬───────────┘  └──────────┬─────────────────┘ │
-└────────────┼─────────────────────────┼───────────────────┘
-             └──────────┬──────────────┘
-                        ▼
-┌──────────────────────────────────────────────────────────┐
-│                     Core Engine                           │
-│                                                           │
-│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐ │
-│  │ Retriever  │  │ Classifier │  │ Context Composer     │ │
-│  │ (vector +  │  │ (6 cats)   │  │ (resume_context)     │ │
-│  │ BM25 + RRF)│  │            │  │                      │ │
-│  └────────────┘  └────────────┘  └──────────────────────┘ │
-│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐ │
-│  │ Decay      │  │ Conflict   │  │ Capture Engine       │ │
-│  │ Engine     │  │ Engine     │  │ (evidence → durable) │ │
-│  │ (Weibull)  │  │ (audit +   │  │                      │ │
-│  │            │  │  merge)    │  │                      │ │
-│  └────────────┘  └────────────┘  └──────────────────────┘ │
-└──────────────────────────┬───────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────┐
-│                    Storage Layer                          │
-│  ┌─────────────────────┐  ┌────────────────────────────┐ │
-│  │ LanceDB             │  │ Jina Embeddings v5         │ │
-│  │ (vector + columnar) │  │ (1024-dim, task-aware)     │ │
-│  └─────────────────────┘  └────────────────────────────┘ │
-└──────────────────────────────────────────────────────────┘
+
+Works with Node.js 22+ (via tsx) or Bun. No git clone needed.
+
+### Option C: Manual setup
+
+```bash
+git clone https://github.com/AliceLJY/recallnest.git
+cd recallnest
+bun install
+cp config.json.example config.json
+cp .env.example .env
+# Edit .env → add your JINA_API_KEY
 ```
 
-### Internal Design
+### Start the server
 
-- **L0 / L1 / L2 Dynamic Folding** — every memory stores 3 granularity layers (one-liner / bullet summary / full content); retrieval dynamically selects which layer to return based on relevance score and token budget
-- **Weibull Decay + Emotion Modulation** — memories decay along a parametric Weibull curve; importance scores modulate the half-life, and emotional salience extends it further (up to 30%)
-- **Vector Pre-filter + LLM Dedup** — 90% of dedup decisions use cheap cosine similarity (>= 0.92); only borderline cases invoke LLM judgment, keeping costs low without sacrificing accuracy
-- **Category-Aware Merge Strategies** — `profile` and `preferences` use merge-on-conflict (latest wins); `events` and `cases` use append-only (history preserved)
-- **Display Score vs Elimination Score** — dual-track retrieval: tier floor prevents core memories from ever dropping out, while decay boost lets fresh memories surface temporarily without permanently displacing stable ones
+```bash
+bun run api
+# → RecallNest API running at http://localhost:4318
+```
 
-> Full architecture deep-dive: [`docs/architecture.md`](docs/architecture.md)
+### Try it
+
+```bash
+# Store a memory
+curl -X POST http://localhost:4318/v1/store \
+  -H "Content-Type: application/json" \
+  -d '{"text": "User prefers dark mode", "category": "preferences"}'
+
+# Recall memories
+curl -X POST http://localhost:4318/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query": "user preferences"}'
+
+# Check stats
+curl http://localhost:4318/v1/stats
+```
+
+### Connect your terminals
+
+```bash
+bash integrations/claude-code/setup.sh
+bash integrations/agy/setup.sh
+bash integrations/codex/setup.sh
+```
+
+Each script installs MCP access and managed continuity rules, so `resume_context` fires automatically in fresh windows.
+
+### Index existing conversations
+
+```bash
+bun run src/cli.ts ingest --source all
+bun run seed:continuity
+bun run src/cli.ts doctor
+```
 
 ---
 
+## Images: addressable, not embedded
+
+Conversations contain images. A text memory layer does not. The usual answer is a
+multimodal embedding model — encode every image into the same space as the text. That is
+right for photo libraries. It is the wrong shape here, for a cheap reason: **in a
+conversation an image almost never arrives alone.** It comes wrapped in "look at this
+error", and the reply right after it usually describes what was in the picture. The words
+around the image are already an index of it. What was missing was never semantic search
+over pixels — it was knowing a picture is sitting there at all.
+
+So RecallNest does not encode images. It records **how many images are in the session a
+memory came from**, and lets you decide whether to open the original transcript. Meaning
+is resolved on demand, by whatever model is asking, at the moment it matters.
+
+The cost is worth stating plainly: **no multimodal model, no re-embedding, no image
+storage, no change to any vector.** Backfilling 21,319 existing memories touched metadata
+only.
+
+Two design choices in it were not obvious, and both were wrong on the first attempt.
+
+### Session-level, on purpose
+
+The marker counts the whole session, not the turn — coarser than it first looks like it
+should be, and the coarseness is the point.
+
+A turn that is nothing but a pasted screenshot has almost no text, so it never cleared the
+length gate and never entered the store. Measured on real transcripts, **12.5% of turns
+containing a pasted image were dropped whole** — including the ones worth the most, like
+seven screenshots with no caption, or "here are the steps" attached to a picture that *is*
+the steps. A turn-level marker has nothing to attach to for exactly those. A session-level
+marker lands on that session's *other* memories, which did get stored, and those are what
+a search surfaces.
+
+The trade-off is undisguised: every memory from a session carries the same count, so the
+images may have nothing to do with the row you are looking at. The line says
+`in this session`, not `in this memory`, for that reason.
+
+### Two classes, because they answer different questions
+
+| Bucket | What it is | The question it answers |
+|---|---|---|
+| user-pasted | Pictures a human put into a message | *Where is that screenshot I sent?* |
+| agent-made | Everything else the session produced | *What did the page look like? What did I generate?* |
+
+Keeping only the first is tempting — a person searching their own memory wants their own
+screenshots. But an agent reconstructing its past work wants the other: the diagram it
+drew, the rendering it captured, the illustration it made for a post. **Of 1,767 sessions
+carrying images, 1,103 contain no human-pasted image at all.** Keep one bucket and those
+sessions go silent — precisely the ones where the agent did visual work.
+
+### The second bucket is a complement, not a list
+
+The first implementation defined agent-made images by enumeration: inside `tool_result`,
+inside `payload.output`, inside `tool.result`. Every location was real. The list was still
+wrong, because **the set of ways an image can appear only grows**, and an enumeration
+silently drops whatever it did not anticipate.
+
+So the second bucket is a complement: count every image signal in the record, subtract the
+ones positively identified as human-pasted, attribute the rest without asking where it came
+from. Across 9,619 transcripts:
+
+| | Enumerated | Complement |
+|---|---|---|
+| Agent-made images | 5,812 | **10,938** |
+| Sessions with any image | 1,507 | **1,767** |
+| Human-pasted images | 1,629 | 1,629 |
+
+**The enumeration missed 5,126 images and 376 sessions** — nearly half. The largest class
+it dropped was image *generation*, which lives in neither container the list knew about.
+Human-pasted counts are identical under both definitions, which is the check that matters:
+widening the second bucket did not contaminate the precise one. A regression test feeds the
+parser an `image_generation_call` — a shape the source never names — and asserts it lands
+in the second bucket; under the enumerated implementation that test fails.
+
+One caveat: the complement counts *signals*, not certified pictures. A single generation can
+leave both a call and a completion record and be counted twice. That direction was chosen
+deliberately — the question is "is there anything here to look at", not "exactly how many".
+
+
 ## Interfaces
 
 RecallNest serves two interfaces:
 
-- **MCP** — for any MCP client: Claude Code, Codex, Kimi, Antigravity, Gemini CLI (native tool access)
+- **MCP (stdio)** — for any client that can launch a command: CLI agents (Claude Code, Codex, Kimi, Antigravity) and GUI apps that accept an MCP config (Doubao, Cherry Studio, ChatBox)
 - **HTTP API** — for custom agents, SDK-based apps, and any HTTP client
 
 ### Agent framework examples
@@ -339,7 +379,7 @@ Examples live in [`integrations/examples/`](integrations/examples/):
 ---
 
 <details>
-<summary><strong>MCP Tools (43 tools)</strong></summary>
+<summary><strong>MCP Tools (44 tools)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
@@ -351,6 +391,7 @@ Examples live in [`integrations/examples/`](integrations/examples/):
 | `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 |
+| `promote_synthesis` | Scan dream-synthesized conclusions and promote the ones their own evidence set supports |
 | `list_conflicts` | List or inspect promotion conflict candidates |
 | `audit_conflicts` | Summarize stale/escalated conflict priorities |
 | `escalate_conflicts` | Preview or apply conflict escalation metadata |
@@ -463,6 +504,48 @@ bun run src/cli.ts doctor
 
 ---
 
+## Web UI
+
+<p align="center">
+  <img src="assets/dashboard.png" alt="RecallNest Dashboard" width="800" />
+  <br><em>Dashboard — total count, category distribution, health score, and growth trends at a glance.</em>
+</p>
+
+<p align="center">
+  <img src="assets/screenshots/ui-full.png" alt="RecallNest Search Workbench" width="800" />
+  <br><em>Search Workbench — hybrid search with topic tag filtering, 4 retrieval profiles, Skills browser, and asset management.</em>
+</p>
+
+<p align="center">
+  <img src="assets/knowledge-graph.png" alt="RecallNest Knowledge Graph" width="800" />
+  <br><em>Knowledge Graph — interactive force-directed visualization with semantic bridges revealing cross-domain connections.</em>
+</p>
+
+```bash
+bun run src/ui-server.ts
+# → http://localhost:4317
+```
+
+---
+
+## What's new
+
+**v3.0** raised the runtime floor to **Node 22** (the only breaking change — Bun users are
+unaffected) and gave synthesized conclusions a road into stable memory: a `dream` insight
+can now be promoted on the strength of its own validated evidence set, instead of being
+permanently stuck on the evidence layer where nothing downstream could lean on it.
+
+It also fixed a rate-limit reply that could trigger an unbounded request storm — measured
+at over 61,000 requests in five seconds against an endpoint asking us to slow down. Found
+by the new HTTP contract tests, which drive the real client classes against a loopback
+server instead of stubbing the SDK.
+
+Existing LanceDB data opens in place; there is no export or import step.
+
+**Full history — v3.0 through v1.0, with the upgrade notes for each — is in
+[CHANGELOG.md](CHANGELOG.md).**
+
+
 ## Multilingual Support
 
 RecallNest works out of the box with English. For multilingual memory (Chinese, Japanese, Thai, and 20+ more), install [babel-memory](https://github.com/AliceLJY/babel-memory) with the language packs you need:
@@ -492,6 +575,8 @@ RecallNest auto-detects babel-memory at startup — no configuration needed. Wit
 
 RecallNest is actively maintained. All major architecture phases are complete — see the full [Roadmap](ROADMAP.md) for current priorities and future plans.
 
+Maintainers: see [Publishing RecallNest](https://github.com/AliceLJY/recallnest/blob/main/docs/releasing.md) for the npm Trusted Publishing, validation, and recovery process.
+
 ---
 
 ## Relationship to memory-lancedb-pro
@@ -499,7 +584,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 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.
+- **RecallNest** is a standalone memory layer — it serves CLI agents, GUI chat apps and plain HTTP callers simultaneously through MCP + HTTP API, with session continuity, structured assets, and conflict management built in.
 
 ## Credit
 
@@ -520,9 +605,9 @@ Part of the **小试AI** open-source AI workflow:
 |---------|-------------|
 | [babel-memory](https://github.com/AliceLJY/babel-memory) | Multilingual preprocessing for BM25 — 27+ languages, zero deps |
 | 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-ai-bridge](https://github.com/AliceLJY/telegram-ai-bridge) | Telegram bots for Claude, Codex, Agy, and Kimi |
 | [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 |
+| [wechat-ai-bridge](https://github.com/AliceLJY/wechat-ai-bridge) | Run Claude Code / Codex 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 |