Recall

Recall

[](https://github.com/cashcon57/recall/releases/latest) [](https://github.com/cashcon57/recall/actions/workflows/ci.yml) [](./LICENSE) [](./tsconfig.json) [](https://workers.cloudflare.com) [](https://modelcontextprotocol.io) [](#deployment-options) [](https://ko-fi.com/cash508287)

A self-hosted MCP memory server for trustworthy agent memory: hybrid semantic + keyword search, provenance, lifecycle controls, supersession, and durable recall. Deploy to Cloudflare Workers, run locally without any cloud dependencies, or self-host with Docker.

> Not affiliated with Microsoft Windows Recall. This is an open-source memory server for AI coding assistants (Claude Code, Cursor, Windsurf, Cline, Claude Desktop, anything speaking MCP).

Give Claude, Cursor, Windsurf, or any MCP-compatible client a persistent memory that survives across sessions, projects, and devices. No SaaS, no per-token fees, no data leaving your infrastructure. Your Cloudflare account, your data, your rules.

Who is this for? Developers using AI coding assistants who are tired of re-explaining context every session. Teams who want a shared knowledge pool their agents can actually use. Anyone who wants memory without paying a subscription or shipping prompts to a third party.

flowchart TD
    subgraph Clients
        CC["Claude Code / Codex\n/ Cursor / Windsurf"]
    end

    subgraph CF["☁️  Cloudflare Workers"]
        CFW["Worker"]
        D1[("D1 SQLite")]
        VEC[("Vectorize 1024D\nbge-m3")]
        WAI["Workers AI"]
        CFW --> D1
        CFW --> VEC
        CFW --> WAI
    end

    subgraph Local["💻  Local stdio (no cloud)"]
        LST["stdio server"]
        LSQL[("SQLite +\nsqlite-vec 1024D")]
        LEMB["HF Transformers\nbge-m3"]
        LST --> LSQL
        LST --> LEMB
    end

    subgraph Docker["🐳  Docker HTTP"]
        DSV["HTTP server"]
        PG[("Postgres +\npgvector 1024D")]
        DEMB["HF Transformers\nbge-m3"]
        DSV --> PG
        DSV --> DEMB
    end

    CC -->|"HTTP /mcp"| CF
    CC -->|"stdio"| Local
    CC -->|"HTTP :8788"| Docker

Deployment Options

Three backends. Same tool surface. Choose what fits your infra:

| | Cloudflare Workers | Local stdio | Docker HTTP | |---|---|---|---| | Infrastructure | CF D1 + Vectorize + Workers AI | SQLite + sqlite-vec | Postgres + pgvector | | Embeddings | bge-m3, 1024D | bge-m3, 1024D | bge-m3, 1024D | | Internet required | Yes | No | No | | MCP transport | HTTP | stdio | HTTP | | Cost | Free tier | Free | Free | | Best for | Production, team sharing | Offline, privacy-first | Self-hosted server |

> Memory portability between backends: All three backends use the bge-m3 model (1024D embeddings). Local and Docker backends run the Xenova ONNX export with CLS pooling to match the reference recipe. Vector compatibility across backends is close in practice — semantic search works cross-backend — but exact bit-for-bit portability is not yet verified with an end-to-end smoke test. If strict portability matters, test your workload before migrating.

Docs

• [Updating Recall](./docs/UPDATING.md) — optional updater script, config preservation contract, migrations, rollback, cron, and GitHub Actions notes.
• [Hermes integration](./docs/HERMES_INTEGRATION.md) — recommended namespaces, Discord provenance, MCP wrapper config, routing rules, and cron examples for Hermes Agent.
• [Release checklist](./docs/RELEASE_CHECKLIST.md) — validation checklist for typecheck/test/deploy, MCP smoke tests, lifecycle tools, consolidation, updater, and Hermes docs.

Why Recall?

Most MCP memory servers do one of two things: dump text into SQLite with cosine similarity, or call a hosted vector DB. Recall does both — at the same time — and reranks the combined results with a cross-encoder.

• Hybrid search — Vector similarity (bge-m3, 1024D) + BM25 full-text search, fused via Reciprocal Rank Fusion. Catches both semantic paraphrases and exact keyword matches.
• Trustworthy memory metadata — Optional provenance fields (source_type, URL/path/title/hash), confidence, verification time, expiration, and status make retrieved memories auditable instead of context-free snippets.
• Lifecycle + supersession — Mark memories active/stale/superseded/deprecated, verify them, or supersede older keys without losing the historical trail that explains past behavior.
• Cross-encoder reranking — Final candidates run through bge-reranker-base for precision. Content is truncated before reranking to keep AI token usage low.
• Tiered recency decay — Three memory tiers with biological half-lives: episodic (7d, session events), semantic (69d, facts/concepts), procedural (693d, stable rules/credentials). Episodic context ages out fast; architecture decisions stay relevant for years. Tier design inspired by NornicDB.
• Auto-relationship graph — Memories with embedding similarity > 0.82 are automatically linked on store. Traverse with get_related_memories to find contextually adjacent knowledge without re-querying.
• Deduplication guard — Refuses to store memories with > 0.92 cosine similarity to existing entries under different keys.
• Weekly consolidation — A scheduled cron analyzes the store for near-duplicates and stale entries, writing a searchable report back into memory.
• Hardened by default — 1 MB body cap, constant-time HMAC auth, SHA-256 hashed rate-limit buckets, destructive tools default-disabled, weak-key warnings.
• Serverless + cheap — Runs on Cloudflare's free tier for most personal/small-team use. Sub-10ms cold start.

How it compares

| | mem0 | letta | zep | Recall | |--------------------------|:------:|:------:|:------:|:------:| | MCP native | ✓ | ✓ | ✓ | ✓ | | Self-hostable | ✓ | ✓ | ✓ | ✓ | | Hybrid (vector + BM25) | ✗ | ✗ | ✓ | ✓ | | Cross-encoder reranking | ✗ | ✗ | ✗ | ✓ | | Recency decay | partial| partial| ✓ | ✓ | | Scheduled consolidation | ✗ | ✗ | ✗ | ✓ | | Deploy complexity | docker | docker | docker | 1 command | | Monthly cost (personal) | $0–$ | $0–$ | $0–$ | $0 |

Quickstart — Cloudflare Workers

Prerequisites

1. A Cloudflare account — free. Sign up here. You do not need a custom domain. Cloudflare gives every worker a free *.workers.dev subdomain on signup, and Recall deploys to that by default. See [Custom domain (optional)](#custom-domain-optional) if you want a vanity URL.
2. Workers AI access — still free, but you must accept the terms once at dash.cloudflare.com → AI → Workers AI. First-time visit prompts you to agree. Without this, embeddings will fail.
3. Node.js 20+ — download here if you don't have it.

> Total cost for personal use: $0. Recall runs entirely within Cloudflare's free tier for Workers, D1, Vectorize, and Workers AI. See [Costs](#costs) for limits and real-world usage profiles.

Deploy

The easiest way: paste this into Claude Code.

Fetch https://raw.githubusercontent.com/cashcon57/recall/v1.1.3/SETUP_PROMPTS.md using Bash (curl -fsSL) so you get the raw markdown, not a summary. Verify it contains a section titled "Prompt 0 — First-time setup". Execute that section verbatim, step by step, adapted and optimized for my current project. Do not summarize. Do not skip. If the fetch fails or the section is missing, stop and tell me.

Claude becomes the setup wizard: inspects your project, checks your environment, walks you through Cloudflare signup if you don't have an account, handles the Workers AI terms page, deploys the worker tuned for how you actually work, wires Recall into your MCP client config, and runs a full functional smoke test (hybrid search, reranker, security gates, auth). It asks how you want to organize memory across your projects before touching anything, so a solo dev with one repo and a team with ten repos get different setups tailored to them. At the end, it prints a report showing exactly how your install was adapted.

No reading required. No copy-pasting commands. The command is pinned to the v1.1.3 release tag so it behaves identically every time.

Want to read what Claude will actually do? See [SETUP_PROMPTS.md](./SETUP_PROMPTS.md) — including a short "Why is the one-liner written that way?" explainer covering the four levers (pinning, explicit tool, integrity check, verbatim execution) that make the command deterministic.

Prefer to run the script yourself?

git clone https://github.com/cashcon57/recall.git
cd recall
./setup.sh

What the setup actually does (either path)

1. Log you in to Cloudflare if needed
2. Create a D1 database, apply the schema, and patch wrangler.toml with the generated ID
3. Create a Vectorize index (1024D, cosine) with metadata indexes on importance and author
4. Generate a cryptographically random MEMORY_API_KEY and upload it as a secret
5. Deploy the worker
6. Write the API key to a chmod 600 file (.recall-api-key) so it doesn't land in your terminal scrollback

Retrieve the key with cat .recall-api-key, move it into a secret manager, then rm .recall-api-key.

Quickstart — Local stdio

No Cloudflare account needed. Runs fully offline after the first model download.

Prerequisites

• Node.js 20+
• The sqlite-vec native extension for your platform (releases)

Steps

# 1. Clone and enter the local directory
git clone https://github.com/cashcon57/recall && cd recall/local

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Download sqlite-vec extension for your platform
# macOS (Apple Silicon):
curl -L https://github.com/asg017/sqlite-vec/releases/latest/download/sqlite-vec-macos-arm64.tar.gz | tar xz
# macOS (Intel):
# curl -L https://github.com/asg017/sqlite-vec/releases/latest/download/sqlite-vec-macos-x86_64.tar.gz | tar xz
# Linux (x86_64):
# curl -L https://github.com/asg017/sqlite-vec/releases/latest/download/sqlite-vec-linux-x86_64.tar.gz | tar xz

# 5. Test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' | \
  RECALL_DB_PATH=~/.recall/recall.db node dist/local/src/server.js

Add to your MCP client config (copy from examples/mcp-config-local.json):

{
  "mcpServers": {
    "recall-local": {
      "command": "node",
      "args": ["/absolute/path/to/recall/local/dist/local/src/server.js"],
      "env": {
        "RECALL_DB_PATH": "/Users//.recall/recall.db",
        "SQLITE_VEC_PATH": "/absolute/path/to/recall/local/sqlite-vec"
      }
    }
  }
}

> Note: The first retrieve_memory or store_memory call downloads the bge-m3 model (~570MB) from HuggingFace. Subsequent calls use the local cache. better-sqlite3 appends the platform extension (.dylib / .so) to SQLITE_VEC_PATH automatically — omit the extension in the config.

Quickstart — Docker

No Cloudflare account needed. Requires Docker and Docker Compose.

# 1. Clone
git clone https://github.com/cashcon57/recall && cd recall

# 2. Start Postgres + Recall server
cd docker
MEMORY_API_KEY=your-secret-key docker compose up -d

# 3. Verify
curl -s -X POST http://localhost:8788 \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq '.result.tools | length'
# Expected: 10

# 4. Tear down (keeps data in pgdata volume)
docker compose down

Add to your MCP client config (copy from examples/mcp-config-docker.json):

{
  "mcpServers": {
    "recall-docker": {
      "url": "http://localhost:8788",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

Add to your MCP client

Claude Code (.mcp.json)

Create or edit .mcp.json in your project root with the actual worker URL and API key hardcoded (not env var substitution). Gitignore this file so the key stays local.

{
  "mcpServers": {
    "recall": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

That's it. No source .env, no export, no shell setup. Claude Code reads .mcp.json on startup and connects automatically, just like every other MCP server.

Claude Desktop (claude_desktop_config.json)

Claude Desktop doesn't currently support direct HTTP transports, so bridge it through mcp-remote:

{
  "mcpServers": {
    "recall": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-worker.workers.dev/mcp",
        "--header",
        "Authorization: Bearer your-api-key-here"
      ]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor / Windsurf

Use the same HTTP config shape as Claude Code, in your editor's MCP config file. See your editor's docs for the exact path.

Custom domain (optional)

The default https://recall..workers.dev/mcp URL works perfectly and requires no domain. If you want a nicer URL like https://memory.yourdomain.com/mcp:

Step 1 — Add your domain to Cloudflare (if it's not already). Follow their add-a-site flow. You'll update your registrar's nameservers — one-time DNS move.

Step 2 — Add a route in wrangler.toml:

[[routes]]
pattern = "memory.yourdomain.com/*"
zone_name = "yourdomain.com"
custom_domain = true

Step 3 — Redeploy: npx wrangler deploy. Cloudflare issues the TLS cert automatically.

Claude Code vs Codex

Recall supports both Claude Code and Codex CLI. The session-start instructions differ slightly:

| Feature | Claude Code | Codex | |---|---|---| | Session instructions | initialize response instructions field | AGENTS.md in project root | | Session config | examples/CLAUDE.md → copy to your project | examples/AGENTS.md → copy to your project | | Context preservation | examples/recall-precompact.sh (PreCompact hook) | Manual — call store_memory before session ends | | MCP config | .mcp.json with mcpServers | .mcp.json with mcpServers | | Recommended backend | Any | CF Workers or Docker (HTTP transport) |

Codex setup: Copy examples/AGENTS.md to your project root (or append to your existing AGENTS.md).

See it in action

Here's what using Recall looks like in practice. Say you're debugging a citext extension issue on Neon Postgres:

Session 1 — You explain it once to Claude, Claude writes it down:

> You: The auth migration is failing because we didn't install citext before adding the email column. Now Neon is rejecting the migration on the pooled connection. > > Claude: [Calls store_memory] > > ``json > { > "key": "neon-citext-migration-order", > "content": "citext extension must be installed BEFORE creating columns of type citext. Pooled Neon connections silently reject the migration if the order is reversed. Run CREATE EXTENSION citext; in a separate migration, let it commit, then add the column in the next.", > "tags": ["database", "neon", "postgres", "migration", "gotcha"], > "importance": 0.85, > "author": "you" > } > `` > > Noted. I'll remember this for future migrations.

Session 2 — Three weeks later, different project, Claude recalls it automatically:

> You: I'm a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cashcon57
• Source: cashcon57/recall
• License: MIT

Install and usage instructions live in the source repository linked above.