Rekall Mcp

Rekall MCP

Give Claude a memory with associative recall. Three steps, five minutes.

Rekall MCP is a persistent memory system with a knowledge graph layer. It stores memories as YAML + vector embeddings, connects them with typed relationships, and retrieves context using graph-enhanced semantic search.

---

Local-First Agent Nervous System

Rekall gives local agents durable, inspectable, cross-session and cross-project memory for software work. Harness memory stores assistant preferences; Rekall stores what the work has taught the agent: decisions, root causes, procedures, danger zones, and project familiarity with provenance.

---

Install

Try it — no Docker, one command

claude mcp add rekall -- uvx rekall-mcp

That's the trial tier: stdio transport, embedded vector store at ~/.rekall/qdrant, memories as YAML at ~/.claude/memory. First run downloads the ~90 MB embedding model (progress on stderr). No hooks/auto-capture, single session at a time — upgrade below when it earns a daily slot.

Daily driver — all-in-one Docker

docker run -d -v rekall-data:/data -p 127.0.0.1:8000:8000 ghcr.io/jfr992/rekall-mcp
claude mcp add --transport http rekall http://localhost:8000

One container, embedding model baked in, data on a named volume. Verify with curl http://localhost:8000/health.

Full stack — compose (adds the cockpit UI)

git clone https://github.com/jfr992/rekall-mcp.git
cd rekall-mcp
docker compose up -d    # Qdrant (:6333) + MCP backend (:8000) + cockpit (:3333)
claude mcp add --transport http rekall http://localhost:8000

Data lives on named volumes (rekall-memory, rekall-qdrant). Existing installs with data at ~/.claude/ keep their bind mounts via docker-compose.bind-mounts.example.yaml — see [docs/MIGRATION.md](docs/MIGRATION.md). (scripts/start-rekall.sh remains for running the backend/UI on the host during development.)

> Need Docker? Get it free at docker.com/get-started

Which tier?

| Tier | Install | Transport | Hooks / auto-capture | Embedder | Storage | |---|---|---|---|---|---| | Trial | uvx rekall-mcp | stdio | no | fastembed | embedded ~/.rekall/qdrant + YAML ~/.claude/memory | | Daily (pip) | uv tool install rekall-mcp && rekall serve | HTTP loopback | yes | fastembed | same as trial | | Daily (docker) | docker run -v rekall-data:/data -p 127.0.0.1:8000:8000 ghcr.io/jfr992/rekall-mcp | HTTP loopback | yes | fastembed (baked into the image) | named volume | | Full stack | docker compose up -d | HTTP + cockpit | yes | per compose | external Qdrant container |

Trial-tier honesty: no hooks means nothing is captured automatically — you save and recall explicitly. Filtering is linear at embedded scale, and only one process can hold the embedded store (run rekall serve so sessions share one daemon). Shared-env pip install is unsupported; use isolated installs (uvx / uv tool install).

Wire Claude Code (hooks + config)

The MCP server alone gives Claude memory tools; the hooks make memory automatic. From a repo checkout:

bash claude/setup/install.sh

Idempotent, backs up ~/.claude/settings.json first. It wires four hooks and nine slash commands:

| Hook | Event | What it does | Kill switch | |---|---|---|---| | rekall-restore.sh | UserPromptSubmit | once-per-session status line, no injection | REKALL_AUTOSAVE=0 | | rekall-observe.sh | Stop | gated Haiku judge auto-saves durable observations + posts session summaries (feeds reinforcement) | REKALL_AUTOSAVE=0 | | rekall-reflex.sh | PreToolUse (Bash) | surfaces relevant memories before risky commands | REKALL_REFLEX=0 | | memory-prune.sh | SessionStart | daily gated prune housekeeping | REKALL_AUTOSAVE=0 |

Optional fifth (manual, injects a thin project capsule at session start): cp claude/hooks/session-start-memory.sh ~/.claude/hooks/ + a SessionStart entry — see [claude/INSTALL.md](claude/INSTALL.md).

Using profiles (CLAUDE_CONFIG_DIR)? The installer targets ~/.claude; repeat the settings entries in each profile's settings.json (hook files can be shared by absolute path).

Recommended agent policy for CLAUDE.md (when to recall, what to save): copy the block from [docs/CLAUDE_MEMORY_SETTINGS.md](docs/CLAUDEMEMORYSETTINGS.md).

Done. Claude now remembers things between sessions — and recalls them before risky commands.

---

How to Use

Just talk normally. Claude automatically remembers:

• Decisions - "Let's use PostgreSQL"
• Preferences - "I prefer TypeScript"
• Lessons - "That bug was caused by..."

To check memories: "What do you remember about this project?"

Python API

from memory import MemoryManager

memory = MemoryManager()

# Save (auto-links to related memories in the knowledge graph)
memory.save("Chose PostgreSQL for JSON support", type="decision", project="my-app")
memory.save("User prefers concise responses", type="preference")

# Recall (graph-enhanced: vector search + relationship traversal)
results = memory.recall("what database did we choose?")
for r in results:
    print(f"[{r['score']:.2f}] {r['content']}")

# Project context (flat or hierarchical)
context = memory.get_project_context("my-app")

CLI

# Save
python -m memory.cli save "Decided to use PostgreSQL" --type decision --project my-app

# Recall
python -m memory.cli recall "database choices"
python -m memory.cli recall "recent work" --limit 3 --days 7

# Stats
python -m memory.cli stats

Operations

| Verb | What it does | |------|-------------| | rekall doctor [--project P] [--json] | Health check — exit 0 healthy, 1 degraded, 3 unreachable | | rekall backup [--out DIR] | Tarball memory + Qdrant; streams artifact paths | | rekall migrate [--dry-run] [--no-backup] | Migrate to hybrid schema; backs up first by default | | rekall startup-preview [--project P] | Preview what the SessionStart hook would inject (approximates hook output; exit 3 if backend unreachable) | | rekall install-claude [--skills-only] [--hooks-only] [--skip-backend] | Install Claude Code bundle from a repo checkout |

Software evals: uv run --extra dev pytest tests/test_software_evals.py Utility report: uv run python scripts/utility_report.py Conflict-edge repair: QDRANT_URL=... uv run python scripts/repair_contradicts.py — re-judges unrefined contradicts edges, dry-run by default (see [docs/TUNING.md](docs/TUNING.md))

---

Knowledge Graph

Every memory is a node. Relationships are typed edges created automatically on save:

| Relation | Meaning | Example | |----------|---------|---------| | related_to | Semantically similar | Two PostgreSQL facts | | led_to | Temporal causation | Decision led to a learning | | depends_on | Structural dependency | Decision depends on requirement | | supersedes | Newer replaces older | Updated decision overwrites old | | contradicts | Opposing content | Conflicting memories |

Graph-Enhanced Recall

Recall uses a 3-phase pipeline instead of flat cosine search:

1. SEED    - Vector search (top K x 2 candidates)
2. EXPAND  - Traverse 1-hop graph neighbors of seed results
3. RANK    - Composite: vector(40%) + importance(20%) + proximity(15%) + tier(15%) + recency(10%)

This finds memories that are structurally related, not just textually similar. Falls back to pure vector search when the graph is empty.

Freshness — conflict detection at read time

When the same memory type appears in the result set, Rekall detects conflicting entries via graph edges and stored-vector cosine (θ ≥ 0.9). The recall_formatted output renders entries newest-first; outdated entries are collapsed to a stub line so the agent acts on current information only. No data is deleted — the detection is ephemeral and happens entirely at read time.

Cockpit UI

Browse the knowledge graph at http://localhost:3333/brain — the Next.js cockpit ships as a container, started by docker compose up -d alongside Qdrant and the backend. (For UI development, cd ui && npm run dev -- -p 3333 still works.) Surfaces:

• /brain — force-directed graph view, nodes are memories, edges show typed relationships
• /kb — typed columns (decisions, requirements, preferences, learnings), plus an Export OKF tab that distills memory into a portable Open Knowledge Format bundle
• /continuity — resume packets and handoff summaries
• /hygiene — pressure metrics, prune flow, lifecycle backfill

---

Claude Code bundle (optional)

The three-container stack above gives Claude memory via MCP tools. The claude/ bundle adds the Claude Code integration layer — auto-save hooks, slash commands, and a recommended memory policy. All of it is opt-in; nothing auto-loads.

One-shot install

bash claude/setup/install.sh

Idempotent, backs up your existing ~/.claude/settings.json first. It:

• copies four hooks to ~/.claude/hooks/ (rekall-restore, rekall-observe, rekall-reflex, memory-prune)
• merges UserPromptSubmit, Stop, SessionStart, and PreToolUse (Bash matcher) entries into ~/.claude/settings.json (deduped; repairs a wrong/missing reflex matcher)
• copies all nine slash commands to ~/.claude/skills/
• verifies backend health

Restart your Claude Code session afterward so the slash commands load. Re-run anytime from inside Claude Code via /rekall-setup. Full manual steps and flags (--skills-only, --hooks-only, --skip-backend) are in [claude/INSTALL.md](claude/INSTALL.md).

Hooks (the auto-save layer)

• rekall-restore.sh (UserPromptSubmit) — once-per-session status line (Rekall ready — N memories…). No context injection.
• rekall-observe.sh (Stop) — a Haiku judge that auto-saves durable observations, gated by cheap signal detection (durability keywords, new git commits, or session length) so it doesn't fire on every turn. Kill switch: REKALL_AUTOSAVE=0.
• rekall-reflex.sh (PreToolUse, Bash) — surfaces relevant memories before risky commands (destructive ops, IaC, memory-data, hooks, helm). A local word-boundary cue match gates the fetch (no network on a miss), debounced once per session per cue. On a match it does a bounded curl (0.1s connect / 1s total) to /api/memory/reflex and injects a capped, untrusted-framed packet as additionalContext. It never blocks the tool call — every failure path exits 0. Kill switches: REKALL_AUTOSAVE=0 (master) or REKALL_REFLEX=0 (dedicated).

Slash commands (manual, not auto-triggering)

| Slash command | What it does | |---------------|--------------| | /memory-observe | Manual save with auto-classification | | /memory-recall | Graph-enhanced semantic search | | /memory-restore | Manual context restore (importance-ranked) | | /memory-stats | Health check + graph metrics | | /memory-rebuild | Rebuild the knowledge graph | | /memory-consolidate | Detect duplicate and contradictory memories | | /memory-skills | Show extracted skills from memory clusters | | /rekall-publish | Export memory to an OKF knowledge bundle | | /rekall-setup | Re-run the bundle installer from inside Claude Code |

Recommended CLAUDE.md policy

For the agent to use memory well — recall at session start, save conservatively — copy the policy block from [docs/CLAUDE_MEMORY_SETTINGS.md](docs/CLAUDEMEMORYSETTINGS.md) into your ~/.claude/CLAUDE.md (global) or a project CLAUDE.md. It tells Claude when to call get_cached_context(), what's worth an observe(), and how to tune recall.

---

Your Data

Everything stays on your computer in editable files:

~/.claude/memory/
  /
    2026-02-02.yaml     > ui/.env.local

---

Benchmark

Tested on LongMemEval (500 questions, 6 question types). Reproducible — runner in [benchmarks/](benchmarks/).

End-to-end effectiveness numbers — accuracy, token cost, and the workloads Rekall loses on — live in [BENCHMARKS.md](BENCHMARKS.md), with committed raw evidence.

These are R@5 retrieval-recall numbers — "was the correct memory in the top 5 retrieved" — with no LLM at any stage. They are not end-to-end QA-accuracy and are not comparable to the QA-accuracy figures other systems (mem0, Zep) publish on LongMemEval. MemPalace's raw retrieval baseline (96.6% R@5) uses the same metric and is the closest comparison point.

Measured 2026-07-02 on v1.7.0 (main, 5-weight recall ranking). Hybrid (BM25 + dense) has been the product's default recall path since 2026-07-17 — the "Hybrid" rows below now describe what recall actually runs. The BM25 vocab is maintained via POST /api/memory/resparse (see [docs/TUNING.md](docs/TUNING.md)); drift is surfaced in the doctor's bm25 block.

| Mode | R@5 | R@10 | |------|-----|------| | Dense (semantic only) | 91.7% | 96.2% | | Hybrid (BM25 + dense) | 93.6% | 97.4% | | Hybrid + graph | 93.6% | 97.4% |

Hybrid search catches entity-specific queries (ticket IDs, error codes) that pure semantic search misses. No LLM required, no API calls, runs entirely local. R@5 measures retrieval, not answer quality — a system can retrieve well and still answer poorly.

# Reproduce (runs against the isolated test Qdrant on :6334 — production data untouched)
bash benchmarks/download_data.sh
docker compose --profile test up -d qdrant-test
PYTHONPATH=src:. uv run python -m benchmarks.longmemeval_runner \
    benchmarks/data/longmemeval_s_cleaned.json --mode all

---

How Search Works

Memories are converted to embeddings (vectors that capture meaning) for semantic search:

"Use PostgreSQL" -> [0.12, 0.45, 0.78, ...]  
How It Works

### The Flow

You say something important | Claude saves it -> YAML file + Qdrant vector + Knowledge Graph node | Auto-linker finds related memories -> Creates typed edges | Later: Claude recalls by meaning + follows graph relationships

### Example

You: "Let's use PostgreSQL for JSON support" AI: saves to memory, creates embedding, auto-links to related memories

[3 days later]

You: "What database did we choose?" AI: vector search finds the memory graph expansion surfaces the related requirement and learnings "We chose PostgreSQL for its JSON support"

### Memory Types

| Type | Example | AI Behavior | Importance |
|------|---------|-------------|------------|
| `requirement` | "Must use Python 3.11+" | **Must** follow | 1.0 |
| `decision` | "Chose PostgreSQL" | Reference, can revisit | 0.85 |
| `preference` | "Prefers Terraform" | Suggest, offer alternatives | 0.75 |
| `learning` | "JWT bug fix" | Apply to similar cases | 0.65 |
| `fact` | "Project uses AWS" | Background context | 0.55 |
| `note` | "General observation" | Low-priority context | 0.35 |
| `session` | Session summary | Continuity context | 0.25 |

`summary` is also a valid type — generated by memory compaction (`POST /api/memory/compact`), not saved by hand.

### MCP Tools

| Tool | Purpose |
|------|---------|
| `observe(summary)` | Auto-classify and save (accepts caller `cwd` for project scope) |
| `recall_memories(query, task_hint?, session_id?)` | Graph-enhanced semantic search; `task_hint` (2+ words) surfaces memories matching your current task first |
| `recall_across_projects(query, current_project)` | Cross-project transfer recall across current, related, and global memory |
| `close_loop(memory_id, note?)` | Close an open loop: appends a RESOLVED stamp, drops it from the Open Loops capsule bucket |
| `save_memory(content, type)` | Manual save with explicit type |
| `memory_detail(memory_id)` | Single memory + neighbors + scope |
| `memory_kb(project)` | Typed slices (decisions / requirements / preferences / learnings) |
| `memory_pressure(project)` | Pressure metrics + flagged candidates |
| `memory_pres

…

## Source & license

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

- **Author:** [jfr992](https://github.com/jfr992)
- **Source:** [jfr992/rekall-mcp](https://github.com/jfr992/rekall-mcp)
- **License:** Apache-2.0

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