Why RecallNest?

Most coding agents forget everything when you open a new window. Worse — your history is scattered across three different terminals with no shared memory.

Without RecallNest — every window starts from zero:

You (Claude Code): "The Docker config lives at /opt/app/config.json, use port 4318."

(switch to Codex)

You: "The config is at... wait, let me find it again." 😤

(next day, new Claude Code window)

You: "We already fixed this exact bug last week! The solution was..."

Agent: "I don't have context about previous sessions." 🤷

With RecallNest — context carries over:

You (Claude Code): "The Docker config lives at /opt/app/config.json, use port 4318."

(switch to Codex — same memory layer)

Agent: (auto-recalls project entities) "Using config at /opt/app/config.json, port 4318." ✅

(next day, new window)

Agent: (resume_context fires) "Continuing from yesterday — the Docker port conflict was resolved by..." ✅

That's the difference: one memory shared across terminals, with context that survives window boundaries.

What you get

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.

Requires: Bun runtime. Dependencies install on first start.

Option B: 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/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

bun run src/cli.ts ingest --source all
bun run seed:continuity
bun run src/cli.ts doctor

Architecture

┌──────────────────────────────────────────────────────────┐
│                     Client Layer                          │
├──────────┬──────────┬──────────┬──────────────────────────┤
│ Claude   │ Gemini   │ Codex    │ Custom Agents / curl     │
│ Code     │ CLI      │          │                          │
└────┬─────┴────┬─────┴────┬─────┴──────┬──────────────────┘
     │          │          │            │
     └──── MCP (stdio) ───┘     HTTP API (port 4318)
                │                       │
                ▼                       ▼
┌──────────────────────────────────────────────────────────┐
│                   Integration Layer                       │
│  ┌─────────────────────┐  ┌────────────────────────────┐ │
│  │  MCP Server         │  │  HTTP API Server           │ │
│  │  29 tools           │  │  19 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)     │ │
│  └─────────────────────┘  └────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

Full architecture deep-dive: docs/architecture.md

Integrations

RecallNest serves two interfaces:

• MCP — for Claude Code, Gemini CLI, and Codex (native tool access)
• HTTP API — for custom agents, SDK-based apps, and any HTTP client

Agent framework examples

Examples live in integrations/examples/:

Core Features

Hybrid Retrieval

Query → Embedding ──┐
                    ├── Hybrid Fusion → Rerank → Weibull Decay → Filter → Top-K
Query → BM25 FTS ──┘

• Vector search — semantic similarity via LanceDB ANN
• BM25 full-text search — exact keyword matching via LanceDB FTS
• Hybrid fusion — vector + BM25 combined scoring
• Reranking — Jina cross-encoder reranking
• Decay + tiering — Weibull freshness model with Core / Working / Peripheral tiers

Session Continuity

The killer feature for multi-window workflows:

• checkpoint_session — snapshot current work state (decisions, open loops, next actions)
• Repo-state guard — saved checkpoints strip git status / modified-file text so volatile repo state does not contaminate later handoffs
• resume_context — compose startup context from checkpoints + durable memory + pins
• Managed rules — integration scripts install continuity rules so resume_context fires automatically

Workflow Observation

RecallNest now keeps workflow observations in a dedicated append-only store instead of stuffing them into the regular memory index:

• workflow_observe — record whether resume_context, checkpoint_session, or another workflow primitive succeeded, failed, was corrected, or was missed
• workflow_health — aggregate 7d / 30d health for one workflow or show a degraded-workflow dashboard
• workflow_evidence — package recent issue observations, top signals, and suggested next actions for debugging

These records live under data/workflow-observations, not in the 6 memory categories, and they are never composed into resume_context as stable recall. Managed MCP / HTTP continuity calls now append observations automatically for resume_context and checkpoint_session, while repo-state sanitization is recorded as a corrected checkpoint observation instead of polluting durable memory.

Memory Promotion & Conflict Resolution

Raw transcripts don't silently become long-term memory:

• Evidence → durable — explicit promote_memory with canonicalKey and provenance
• Conflict guards — canonical-key collisions surface as conflict candidates
• Resolution — keep existing, accept new, or merge — with advice and cluster views
• Audit + escalation — conflicts audit --export for operational review

Retrieval Profiles

Memory Categories

Details: docs/memory-categories.md

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

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

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

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 Claude Code, Codex, and Gemini CLI 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.

Star History

Ecosystem

Part of the 小试AI open-source AI workflow:

License

MIT