Why RecallNest?

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 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

Query   : deploy rollback
Hits    : 5

#  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

Three things in that block carry most of the design:

• 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.

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.

Core Capabilities

Access & Setup

Recall & Continuity

Memory Lifecycle & Governance

Reasoning & Structure

Visibility & Operations

Architecture

  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

Internal Design

• 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

Full architecture deep-dive: docs/architecture.md

Who Can Connect

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.

Two consequences worth stating plainly:

• 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.

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.

AI apps on a phone: the read-only gateway

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:

openssl rand -hex 32 > ~/.config/recallnest/gateway-token
chmod 600 ~/.config/recallnest/gateway-token

bun run api        # local API on :4318
bun run gateway    # read-only gateway on :8791 → forwards to :4318

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.

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}'

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.

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 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.

Quick Start

Option A: Claude Code Plugin (recommended)

/plugin marketplace add AliceLJY/recallnest
/plugin install recallnest@AliceLJY

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.

The Claude Code plugin and npm package share one release version and are updated together.

Requires: Bun. Dependencies install on first start.

Option B: npm install

npx recallnest --help          # run directly
# or
npm install -g recallnest      # install globally
recallnest doctor

Works with Node.js 22+ (via tsx) or Bun. No git clone needed.

Option C: Manual setup

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

bun run api
# → RecallNest API running at http://localhost:4318

Try it

# 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 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

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

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:

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 (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

Examples live in integrations/examples/:

# Search & explore
bun run src/cli.ts search "your query"
bun run src/cli.ts explain "your query" --profile debug
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 --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

# Conflict management
bun run src/cli.ts conflicts list
bun run src/cli.ts conflicts list --attention resolved
bun run src/cli.ts conflicts list --group-by cluster --attention resolved
bun run src/cli.ts conflicts audit
bun run src/cli.ts conflicts audit --export --format md
bun run src/cli.ts conflicts escalate --attention stale
bun run src/cli.ts conflicts show af70545a
bun run src/cli.ts conflicts resolve af70545a --keep-existing
bun run src/cli.ts conflicts resolve af70545a --merge
bun run src/cli.ts conflicts resolve --all --keep-existing --status open

# Memory health & visualization
bun run src/cli.ts lint                         # memory quality report
bun run src/cli.ts lint --scope project:myapp   # lint a specific scope
bun run src/cli.ts graph --open                 # export & open knowledge graph
bun run src/cli.ts graph --max-nodes 50         # smaller graph

# Ingestion & diagnostics
bun run src/cli.ts ingest --source all
bun run src/cli.ts doctor

Web UI

Dashboard — total count, category distribution, health score, and growth trends at a glance.

Search Workbench — hybrid search with topic tag filtering, 4 retrieval profiles, Skills browser, and asset management.

Knowledge Graph — interactive force-directed visualization with semantic bridges revealing cross-domain connections.

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.

Multilingual Support

RecallNest works out of the box with English. For multilingual memory (Chinese, Japanese, Thai, and 20+ more), install babel-memory with the language packs you need:

# Chinese
npm install babel-memory jieba-wasm

# Japanese
npm install babel-memory @sglkc/kuromoji

# Thai
npm install babel-memory wordcut

# European languages (German, French, Spanish, Russian, etc.)
npm install babel-memory snowball-stemmers

# Multiple languages at once
npm install babel-memory jieba-wasm @sglkc/kuromoji snowball-stemmers

RecallNest auto-detects babel-memory at startup — no configuration needed. Without babel-memory, RecallNest still works perfectly with standard BM25 text search.

Project Status & Roadmap

RecallNest is actively maintained. All major architecture phases are complete — see the full Roadmap for current priorities and future plans.

Maintainers: see Publishing RecallNest for the npm Trusted Publishing, validation, and recovery process.

Relationship to memory-lancedb-pro

RecallNest started as a fork of 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 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

Special thanks to Qin Chao (@win4r) and the CortexReach team for the foundational work.

License

MIT