Shared Memory Layer for Every AI Client — CLI agents, desktop apps, your own scripts
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.
One memory, every terminal — a shared memory layer for any MCP client.
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.
The row above comes from transcript ingest. Since 2026-10-06 that step is off by default:
ingest no longer chunks conversation records into the store, so a default setup holds only
the memories you stored, distilled entries and memory files, and raw sessions are left to a
dedicated session-search tool. To get rows like this one back, see "Index existing
conversations" below.
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
Capability
Description
CC Plugin
Install in Claude Code with one command — no manual config
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
Recall & Continuity
Capability
Description
Hybrid Retrieval
6-channel: vector + BM25 + L0/L1/L2 multi-vector + KG graph (PPR). The default mode is vector-only (since 2026-06); BM25 fusion and graph expansion are opt-in
Write-time Triggers
Each memory can carry 2–6 "how will this be asked about later" phrasings (triggers), embedded separately and used only for recall — never rendered as evidence. Borrowed from Tencent T-Mem (EMNLP 2026).
4 Retrieval Profiles
default, writing, debug, fact-check — tuned for different tasks
Session Continuity
checkpoint_session + resume_context (full/light/summary modes) with repo-state guard
Retriever: retrieval.mode defaults to "vector" (vector-only search). Setting it to "hybrid" in
config.json adds BM25 full-text search, merged with the vector results by weighted score fusion
(vectorWeight 0.7 / bm25Weight 0.3 by default).
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)
Write-time Rehearsal (Triggers) — a memory stored with triggers: ["别人的榜我们要不要也去排个名", ...] gets each phrasing embedded on the query side into a side table (memory_triggers); at recall time the query is matched against triggers, the best-matching trigger pulls its host memory into the candidate pool (max-over-triggers attribution, cosine hard gate + lexical soft gate), and the host then goes through the normal scoring chain. Triggers never appear in results — they are an entry point, not evidence. RECALLNEST_TRIGGER_RECALL=false turns it off; triggers-backfill / triggers-calibrate CLI manage existing data
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
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.
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
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.
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
Requires Bun: RecallNest does not run on Node.js. The npm launcher only hands off to Bun, and exits with install instructions if bun is not on your PATH. 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
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
Since 2026-10-06, ingest does two things by default: it reconciles memory files
(sources.memory) and moves files from the Minis drop folder into data/minis-archive. The six
conversation sources (cc / codex / kimi / gemini / desktop / minis) are not chunked, embedded or
written. To index transcripts as well, set RECALLNEST_TRANSCRIPT_INGEST=on in the environment
that runs ingest (only the exact value on counts). Minis conversations archived while the
switch was off are not picked up automatically; copy them from data/minis-archive back into
the drop folder and run ingest again.
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 (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
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
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
resolve_conflict
Resolve a stored conflict candidate (keep / accept / merge)
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
explain_memory
Explain why memories matched
distill_memory
Distill results into a compact briefing
brief_memory
Create a structured brief and re-index it
pin_memory
Promote a scoped memory into a pinned asset
export_memory
Export a distilled memory briefing to disk
list_pins
List pinned memories
list_assets
List all structured assets
list_dirty_briefs
Preview outdated brief assets created before the cleanup rules
clean_dirty_briefs
Archive dirty brief assets and remove their indexed rows
memory_stats
Show index statistics
memory_drill_down
Inspect a specific memory entry with full metadata and provenance
auto_capture
Heuristically extract and store memory signals from text (zero LLM calls)
set_reminder
Set a prospective memory reminder to surface in a future session
consolidate_memories
Cluster near-duplicate memories and merge them (dry-run by default)
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
import_conversations
Import conversations from Claude Code, ChatGPT, Slack, and more
data_checkup
Run data quality health checks on the memory store
dream
Run offline memory consolidation (clustering, merging, pruning)
memory_lint
Run memory quality checks: contradictions, duplicates, stale entries, orphans
forget_memory
Delete a memory together with its KG triples, trigger rows and the indexed copies of pins made from it, archive the pin files, read back to confirm, and write an audit entry
export_graph
Export memories as an interactive HTML knowledge graph
Base URL: http://localhost:4318
Endpoint
Method
Description
/v1/recall
POST
Quick semantic search
/v1/store
POST
Store a new memory
/v1/capture
POST
Store multiple structured memories
/v1/pattern
POST
Store a structured workflow pattern
/v1/case
POST
Store a structured problem-solution case
/v1/promote
POST
Promote evidence into durable memory
/v1/conflicts
GET
List or inspect promotion conflict candidates
/v1/conflicts/audit
GET
Summarize stale/escalated conflict priorities
/v1/conflicts/escalate
POST
Preview or apply conflict escalation metadata
/v1/conflicts/resolve
POST
Resolve a stored conflict candidate (keep / accept / merge)
/v1/checkpoint
POST
Store the current work checkpoint
/v1/workflow-observe
POST
Store a workflow observation outside durable memory
/v1/checkpoint/latest
GET
Fetch the latest checkpoint by session or scope
/v1/workflow-health
GET
Inspect workflow health or return a degraded-workflow dashboard
/v1/workflow-evidence
GET
Build a workflow evidence pack from recent issue observations
# 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 (transcripts are not ingested by default; see "Index existing conversations")
bun run src/cli.ts ingest --source all
bun run src/cli.ts doctor
Web UI
bun run src/ui-server.ts
# → http://localhost:4317
What's new
v4.0 runs on Bun only and hands its cross-process locks to the kernel. RecallNest
used to decide a lock file was stale from its pid and timestamp and then delete it — two
processes that saw the same stale file could both end up holding the lock (more than one
winner in up to 30 of 40 rounds of an eight-process race). Locks are now flock(2): the
kernel releases them when a process exits or is killed, and a stress test that kills a
writer every 15–60 ms for six seconds never sees two writers inside.
The rest of the release fixes data that could go wrong quietly: a deleted memory written
back by a concurrent update, history rows left pointing at nothing, secrets kept in
metadata and sent to the embedding API inside triggers, explicit searches such as
git push rules or #22 returning nothing, and write receipts that reported rejected
writes as stored.
Upgrading: install Bun, then stop every RecallNest process before starting v4 — old and
new lock code must not run together. A few defaults and HTTP replies changed; the list is
at the top of the v4.0.0 entry in the changelog. Existing LanceDB data opens in place.
Full history — v4.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.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Recallnest?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Recallnest einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Recallnest?
Recallnest läuft lokal über stdio.
Wann wurde Recallnest zuletzt geprüft?
Zuletzt geprüft: 2026-11-14. One memory, every terminal — a shared memory layer for any MCP client.