RecallNest

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.

English | 简体中文 | Roadmap

</div>

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

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.

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.

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

Web UI

<img src="assets/dashboard.png" alt="RecallNest Dashboard" width="800" /> Dashboard — total count, category distribution, health score, and growth trends at a glance. <img src="assets/screenshots/ui-full.png" alt="RecallNest Search Workbench" width="800" /> Search Workbench — hybrid search with topic tag filtering, 4 retrieval profiles, Skills browser, and asset management. <img src="assets/knowledge-graph.png" alt="RecallNest Knowledge Graph" width="800" /> Knowledge Graph — interactive force-directed visualization with semantic bridges revealing cross-domain connections.

bun run src/ui-server.ts
# → http://localhost:4317

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)
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
Session Distiller	3-layer conversation compression: microcompact → LLM summary → knowledge extraction
Conversation Import	Import from Claude Code, Claude.ai, ChatGPT, Slack, and plaintext
Topic Tags	Intra-scope topic partitioning — auto-detected, filterable in search
Related Scope Sidecar	Opt-in `includeRelatedScopes` search over configured `scopeRelations`, shown separately from the main scoped ranking

Memory Lifecycle & Governance

Capability	Description
Memory Evolution	Supersede chains, decay scoring, LLM importance, consolidation, archival
Smart Promotion	Evidence → durable memory with conflict guards, merge resolution, and audit trail
Privacy Tiers	4-tier (`ephemeral` / `private` / `durable` / `shared`) with cascade forgetting
Admission Control	Write-time gating: noise filter, importance floor, dedup, rate limiting
Memory Lint	Contradiction, duplicate, stale, and orphan detection with health score
Offline Consolidation	`dream` command: clustering, merging, pruning of accumulated memories

Reasoning & Structure

Capability	Description
Knowledge Graph	Entity relation graph with PPR algorithm for multi-hop questions
Constructive Retrieval	Multi-source candidate expansion + grounded context reconstruction
Narrative Architecture	3-layer autobiographical metadata (life-period → general-event → specific-event)
Skill Memory	Store, retrieve, and promote executable skills from recurring patterns
Predictive Reminders	Behavioral-signal prediction engine surfaces "you might need this" suggestions
6 Categories	profile, preferences, entities, events, cases, patterns — with category-aware merge strategies

Visibility & Operations

Capability	Description
Dashboard	Web UI with stats, category distribution, growth trends, and health
Workflow Observation	Dedicated append-only workflow health records, outside regular memory
Structured Assets	Pins, briefs, and distilled summaries — not just raw logs
Data Checkup	Data quality health checks on the memory store (including source health)
Source Heartbeats	Automatic ingest health tracking per data source with staleness alerts
Export Graph	Export interactive HTML knowledge graph visualization
Batch Operations	Store up to 20 memories in a single call with dedup
Connector Framework	Standard connector-v1 format for external data sources with example adapters

New in v3.0: A Supported Runtime, and Conclusions That Can Be Used

v3.0 is a major release for one reason that shows up on install and one that shows up in how memory behaves.

The runtime boundary moved to Node 22. RecallNest had been carrying openai@4, which pulls in the deprecated formdata-node → node-domexception chain. Every openai release since v5 has zero dependencies, so the chain disappears on any upgrade — but v7 declares engines.node >= 22.0.0, which makes "raise the Node floor" and "move off a deprecated dependency chain" the same piece of work rather than two. engines.node is now >=22. This is the breaking part of the major.

**A synthesized conclusion can now reach stable mem

…

Recallnest

Installation

Configuration

How to use

README