🧠 Recall MCP — Long-term Memory for AI Agents

Your agent finally remembers what it did yesterday. Cross-session, persistent, semantic memory for any MCP-compatible agent (Claude Desktop, Cursor, Cline, Continue, …).

🎯 The Problem (worth 100,000+ GitHub stars)

Every time you start a new chat with Claude, Cursor, or any AI agent, it starts from zero. It doesn't remember:

• The bug you fixed yesterday

• The architecture decisions from last week

• Your codebase conventions (tabs vs spaces, framework version, test runner)

• Your preferences ("always use TypeScript", "never commit directly to main")

• The project's gotchas ("the auth middleware is broken, bypass it for now")

This means:

• 🔁 You repeat yourself — explain the same context every session

• 🐌 Slower iteration — agent re-discovers what it already knew

• 📉 Worse quality — no accumulated knowledge

• 💸 Wasted tokens — re-reading the same files, re-asking the same questions

Related MCP server: Central Intelligence

✨ The Solution

Recall MCP gives your agent persistent, searchable memory across sessions.

# Yesterday, in chat session A:
agent.call("remember", content="User prefers tabs over spaces. Project uses Next.js 14 with App Router.")
agent.call("remember", content="Auth middleware has a known bug with session expiry; bypass for now.")

# Today, in chat session B (fresh context):
agent.call("recall", query="code style preferences")
# → [{"content": "User prefers tabs over spaces. Project uses Next.js 14 with App Router.",
#     "score": 0.95, "tags": ["coding-style"], "project": "webapp", ...}]

agent.call("recall", query="known bugs auth")
# → [{"content": "Auth middleware has a known bug with session expiry; bypass for now.",
#     "score": 0.87, ...}]

Why it's better than context-pruning approaches

They're complementary: use a pruner to fit more useful context in the current session, and use Recall so the next session doesn't have to start from scratch.

🚀 Quick Start

1. Install

Option A — pip (PyPI, recommended):

pip install recall-mcp
# After install, the `recall-mcp` command is available:
recall-mcp   # starts the MCP server on stdio

Option B — uvx (no install, run directly):

uvx recall-mcp

Option C — single-file (zero install):

curl -sSL https://github.com/eddyflores100-lang/recall-mcp/raw/main/mcp_recall.py \
  -o ~/.local/bin/recall-mcp
chmod +x ~/.local/bin/recall-mcp

No pip install step, no virtualenv, no API keys — just Python 3.10+ with stdlib.

2. Configure with your agent

If you installed via pip/uvx: use "command": "recall-mcp" with no args. If you used the single-file download: use "command": "python3" with "args": ["/path/to/mcp_recall.py"].

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "recall": {
      "command": "recall-mcp"
    }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "recall": {
      "command": "recall-mcp"
    }
  }
}

Cline / Continue / any MCP client — same pattern: set command to recall-mcp (post-install) or python3 with the script path (single-file mode).

3. Start using

Restart your agent and you'll see 8 new tools available. Try:

"Remember that I prefer functional React components over class components."

Then start a brand new chat:

"Recall what I told you about React conventions."

Your agent will pull the memory and continue where you left off.

🛠️ MCP Tools (8 total)

Tool call examples

// remember
{
  "content": "PostgreSQL connection string format: postgres://user:pass@host:5432/db",
  "tags": ["database", "postgres"],
  "project": "backend",
  "importance": 0.8
}

// recall
{
  "query": "how to connect to postgres",
  "limit": 5,
  "project": "backend",
  "min_importance": 0.3
}

// summarize_session (great for end-of-session snapshots)
{
  "messages": [
    {"role": "user", "content": "I always use pnpm, never npm."},
    {"role": "assistant", "content": "Noted. I'll use pnpm throughout."},
    {"role": "user", "content": "We decided to deploy on Vercel."}
  ],
  "project": "webapp"
}

🏗️ Architecture

┌──────────────┐      stdio (JSON-RPC)      ┌──────────────────┐
│  MCP client  │ ◄────────────────────────► │  mcp_recall.py    │
│ (Claude /    │                              │                  │
│  Cursor /    │                              │  ┌────────────┐  │
│  Cline …)    │                              │  │ MemoryStore│  │
└──────────────┘                              │  │   - remember│  │
                                              │  │   - recall  │  │
                                              │  │   - forget  │  │
                                              │  │   - stats   │  │
                                              │  │   ...       │  │
                                              │  └──────┬─────┘  │
                                              │         │        │
                                              │         ▼        │
                                              │  ┌────────────┐  │
                                              │  │  SQLite    │  │
                                              │  │  + FTS5    │  │
                                              │  │ (local file)│  │
                                              │  └────────────┘  │
                                              └──────────────────┘
                                              Default path:
                                              ~/.recall/memory.db

Ranking formula (for recall results):

score = bm25_rank × 1.0
      + recency_decay × 0.5         (full weight 90d, then linear fade to 0.25)
      + importance × 0.5           (user-set 0..1)
      + min(access_count × 0.05, 0.5)

This means: a memory that matches the query, was recently stored, marked as important, and accessed often will rank highest. A 6-month-old low-importance memory won't completely vanish, but it won't crowd out fresher results either.

🔒 Privacy & Security

• 100% local — every byte lives in ~/.recall/memory.db on your machine.

• Zero telemetry — no external API calls, no analytics, no phone-home.

• Auto-redacts secrets before storage. Detected patterns include:

  • GitHub tokens (ghp_…, gho_…, ghs_…, fine-grained)

  • OpenAI keys (sk-…), Anthropic keys (sk-ant-…), Gemini (AIza…)

  • AWS access keys (AKIA…)

  • JWTs (eyJ…)

  • Stripe keys, Slack tokens, Bearer tokens, private keys

  • password=… assignments

  • Connection strings with embedded credentials (postgres://user:pass@…)

  • All replaced with [REDACTED] before being written to disk.

• Per-project isolation — memories from project A don't bleed into project B's recall unless you ask for them.

• Export anytime — export_memories gives you the full database as JSON. Your data is yours.

📊 Comparison

⚙️ Configuration (env vars)

🧪 Testing

# Option A — full pytest suite (43 tests across 4 files)
git clone https://github.com/eddyflores100-lang/recall-mcp.git
cd recall-mcp
pip install -e ".[dev]"
python -m pytest tests/ -v
# Expected: 43 passed

# Option B — single-file smoke test (no pytest needed, 14 tests)
python test_recall.py
# Expected: === 14 passed, 0 failed ===

CI: GitHub Actions runs the full suite on Python 3.10–3.13 across Ubuntu, macOS, and Windows on every push and PR.

The test suite covers:

• Protocol (9 tests): initialize, ping, notifications/initialized, tools/list, invalid method, invalid tool, malformed JSON, resources/list, prompts/list

• Memory CRUD (13 tests): remember, duplicate detection, empty/long content, importance clamping, recall with filters, forget by id/query, access count bumping

• Secrets (11 tests): GitHub classic + fine-grained tokens, OpenAI, Anthropic, AWS, JWT, Stripe, connection strings, password assignments, private keys, on-disk verification

• Session & Export (10 tests): summarize_session extraction + capping, get_stats, export/import round-trip, invalid input handling, list ordering, tag filters

🗺️ Roadmap

• Optional vector embeddings (with OPENAI_API_KEY or local sentence-transformers) for true semantic search beyond FTS5

• Multi-agent memory sharing (memory namespaces)

• Web UI for browsing / searching / editing memories

• Backup to S3 / Dropbox / gists

• MCP resources endpoint (expose memories as browsable resources)

• Auto-tagging (extract dates, URLs, file paths from content)

• CLI tool (recall search "query", recall add "text")

• Plugin SDK for custom extractors in summarize_session

🤝 Why I built this

I ship MCP servers for a living (see also: context-pruner-mcp). After using agents for months, the single biggest quality boost came not from better models or bigger context windows — it came from giving the agent a way to not forget. Context pruning squeezes more juice out of the current session; long-term memory means the next session starts ahead instead of from zero.

If this saves you 10 minutes of re-explaining per session, that's roughly 40 hours a year for a daily user. Open source it so everyone gets those hours back.

📄 License

MIT — see LICENSE.

⭐ Star History

If this saved you time, please ⭐ the repo — it helps others discover it.

Author: Eddy Flores (eddyflores100-lang)

Issues / feature requests: GitHub Issues