Long-term memory for LLMs. One SQLite file, no cloud, no API keys.
rekal is an MCP server that gives AI coding agents persistent memory across sessions. Memories are stored locally in SQLite and retrieved with hybrid search (BM25 keywords + vector semantics + recency decay). Nothing leaves your machine.
Session 1: "I prefer Ruff over Black" → memory_store(...)
Session 47: "Set up linting" → memory_build_context("formatting preferences")
← "User prefers Ruff over Black" (0.92)
Sets up Ruff without asking.
How it works
Store. The agent saves a durable fact with memory_store: a preference, a decision, a non-obvious discovery.
Index. rekal writes it to SQLite and builds two indexes over it: a BM25 keyword index and a 384-dimensional vector embedding, both computed locally with no network calls.
Recall. In a later session the agent calls memory_build_context. rekal blends keyword match, semantic similarity, and recency into a single score and returns the top hits above a relevance floor.
All state is a single file: ~/.rekal/memory.db. For the scoring formula, schema, and embedding model, see Under the hood.
Quickstart (Claude Code)
uv tool install rekal # 1. install rekal (or: pip install rekal)
claude mcp add --scope user rekal -- rekal mcp # 2. register the MCP server (all projects)
claude plugin marketplace add janbjorge/rekal # 3. add the plugin marketplace
claude plugin install rekal-skills@rekal # 4. install the plugin
Then add "autoMemoryEnabled": false to ~/.claude/settings.json so Claude Code's built-in memory doesn't compete with rekal.
Restart Claude Code and the agent has persistent memory. For what each step does, the other agents (Codex CLI, OpenCode), and the rationale behind disabling built-in memory, read on.
Install
pip install rekal
# or
uv tool install rekal
Requires Python 3.11+. On first run, rekal creates ~/.rekal/memory.db. To upgrade an existing install later, see Updating.
Setup for Claude Code
Three steps: add the MCP server, install the plugin, and disable built-in memory.
1. Add the MCP server. This gives Claude Code the memory tools:
claude mcp add --scope user rekal -- rekal mcp
--scope user registers rekal for all your projects. Without it, claude mcp add defaults to local scope and the server loads only in the project where you ran it (MCP scopes), and memory should follow you everywhere. The -- separates Claude Code's own flags from the command that launches the server; stdio is the default transport.
2. Install the plugin. This teaches Claude Code when to use those tools and prevents conflicts with built-in memory:
claude plugin marketplace add janbjorge/rekal
claude plugin install rekal-skills@rekal
3. Disable built-in auto memory. Add "autoMemoryEnabled": false to ~/.claude/settings.json:
{
"autoMemoryEnabled": false
}
Why is this required? Left enabled, Claude Code's built-in auto memory competes with rekal. It loads its own memory into the agent's context (context layout) and the agent favors it, writing everything to a flat file that cannot be searched, deduplicated, or ranked. Disabling it (autoMemoryEnabled: false, settings docs) removes the competitor. The plugin's hooks then re-assert rekal: SessionStart establishes that memory lives in rekal, and UserPromptSubmit injects prompt-matched memories on every turn.
What if I forget? The plugin's block-memory-writes and redirect-memory-reads hooks catch flat-file memory access (MEMORY.md/.txt, memories.*) and redirect the agent to rekal as a safety net, but it wastes turns hitting them. Disabling auto memory is cleaner.
Can the plugin do this automatically? No. Claude Code only lets a plugin's settings.json set the agent and subagentStatusLine keys (plugin settings); it cannot touch autoMemoryEnabled. This manual step is the only way.
Hooks (automatic, no user action needed):
Hook
Event
What it does
session-start
SessionStart
rekal hook session-start injects a directive that memory lives only in rekal. It deliberately injects no memories: with no prompt yet there is nothing to match against, and recency-ordered recall was usually the wrong topic
user-prompt-submit
UserPromptSubmit
rekal hook user-prompt-submit recalls memories matching the submitted prompt (hybrid search, in-process) and injects the top matches under ## rekal memory, so recall re-anchors to what you just asked on every turn
pre-compact
PreCompact (auto)
Runs a subagent that saves durable facts to rekal before context is compacted, so nothing is lost to summarization
session-end
SessionEnd
rekal hook session-end spawns a detached headless claude -p that saves durable facts to rekal when the session ends (agent hooks cannot run at SessionEnd — the REPL is already tearing down)
block-memory-writes
PreToolUse on Edit/Write
Denies writes to flat-file memory (MEMORY.md/.txt, memories.*) with a reason redirecting to rekal tools
redirect-memory-reads
PreToolUse on Read
Denies reads of flat-file memory and tells the agent to call memory_build_context instead, so a missing file no longer reads as "no memory exists"
Skills (user-invocable):
Skill
Trigger
What it does
rekal-init
/rekal-init
Scans codebase and bootstraps rekal with project knowledge
rekal-save
/rekal-save or auto on session end
Deduplicates and stores durable knowledge from the conversation
rekal-usage
/rekal-usage
Teaches agents how to use rekal effectively
rekal-hygiene
/rekal-hygiene
Finds conflicts, duplicates, and stale data, then proposes fixes
The recall hooks run the released rekal from PyPI via uvx --from rekal==<version> rekal hook <event> (uv must be available; no separate rekal on the PATH needed). The pin matches the version this plugin commit was released as, so hooks and plugin stay in lockstep. uvx fetches the package once per version and caches the environment (tool environments are cached and reused across invocations), so nothing is built from the plugin copy, the warm path never resolves dependencies or touches the network, and the same command works on macOS, Linux, and Windows. Recall never blocks a session: a failed fetch (for example, offline first run) fails that hook non-blockingly and retries on the next one, and a missing DB, load error, or empty result degrades to injecting the directive alone.
Project and database scoping belong in your shell or settings env, not the MCP env block.REKAL_PROJECT and REKAL_DB_PATH set under the MCP server's env apply only to the MCP server process. The recall hook is a separate subprocess and does not inherit them, so it would read the default database with no project scope while the MCP tools use your configured scope. Set these in your shell environment or in Claude Code settings.jsonenv so both the server and the hooks see the same values.
Setup for Codex CLI
One step. rekal is a standard MCP stdio server, with no plugin system and no competing memory to disable (Codex memories are off by default).
One step. rekal is a standard MCP stdio server, and Cursor has no competing memory to disable. The CLI shares the editor's MCP config, so this also enables rekal in the Cursor editor (Cursor CLI MCP docs).
Add to ~/.cursor/mcp.json (global, all projects) or .cursor/mcp.json (project-only) (Cursor MCP docs):
The env block is optional; drop it for global (unscoped) memory. Then enable and verify:
agent mcp enable rekal
agent mcp list
Instruct the agent to call memory_build_context at session start. Add to your project's AGENTS.md:
Call memory_build_context with your current task before exploring the codebase.
Updating
Update rekal (the MCP server)
pip install -U rekal
# or
uv tool upgrade rekal
Restart your agent so it relaunches the server. The SQLite schema migrates automatically on the next start: new columns are added in place and existing memories are preserved, so you never run a migration by hand. To start fresh instead, delete ~/.rekal/memory.db (rekal recreates it on next run).
Update the Claude Code plugin
Third-party marketplaces have auto-update off by default (auto-update docs), so refresh manually, then reload:
claude plugin marketplace update rekal # refresh the catalog
claude plugin install rekal-skills@rekal # reinstall to pull the update
If hooks or skills are still missing afterward, Claude Code is serving a stale plugin cache. Clear it, restart Claude Code, then reinstall (official remedy):
rm -rf ~/.claude/plugins/cache
Tools
rekal exposes exactly three MCP tools. A small surface keeps the tool schemas
cheap in the agent's context and leaves no ambiguity about which tool to call:
Tool
Purpose
memory_build_context
Recall: hybrid search over stored memories. Results below the relevance floor (min_score, default 0.25) are dropped
memory_store
Store a distilled durable memory with project and tags. Pass replaces=<old_id> to update an existing memory instead of creating a near-duplicate
memory_delete
Remove a memory by ID
Setting REKAL_READONLY=1 in the server's environment registers only
memory_build_context, for sessions that should recall but never write.
In read-only sessions the injected memory block also points the agent at
rekal recall --query in the shell, so it can pull stored knowledge
mid-task without any MCP tool mounted.
Admin operations live in the CLI, not the tool surface:
Command
Purpose
rekal health
Database stats: total, counts by project, date range
rekal export
Dump all memories as JSON
rekal prune
Bulk-delete by scope (project / age); dry-run by default
rekal recall
Print memories for a query (what the hooks inject)
Under the hood
Storage
Everything lives in ~/.rekal/memory.db. Three tables share it:
FTS5 keyword index over content+tags+project, trigger-synced
memory_vec
sqlite-vec 384-dim embedding, 1:1 with memories (synced in Python, no trigger)
memory_store(replaces=<old_id>) stores the new memory and deletes the old
one in a single operation, so a topic is only ever covered by one memory
and stale versions never show up in search.
The schema is deliberately minimal. Earlier versions carried conversation
graphs, memory links, a scratch tier, memory types, and access counters;
benchmarks showed the structure cost tokens (fatter payloads, fatter
instructions) without earning them back. The full schema and the
auto-migration from older databases live in
docs/data-model.md. Existing DBs migrate in place
on first open, keeping content and embeddings.
Embeddings
rekal uses fastembed with BAAI/bge-small-en-v1.5 (384 dimensions). It runs locally via ONNX and makes no network calls. The model downloads once on first use (~50MB) and is cached.
Search
Every recall runs two parallel lookups, merges candidates, then scores:
Why three signals? Keywords miss synonyms ("deploy" vs "ship to prod"). Vectors miss exact identifiers. Recency alone buries important old knowledge. The blend covers all three failure modes.
All weights and half-life are configurable:
Priority
Source
Set by
Persists?
1 (highest)
.rekal/config.yml
Checked into version control
Yes, shared with team
2 (lowest)
Hardcoded defaults
Built into rekal
Always: 0.4 / 0.4 / 0.2, 30-day half-life
Layers resolve per-key independently: a config file setting only w_fts keeps the defaults for everything else.
min_relevance (default 0.0, off; env REKAL_MIN_RELEVANCE overrides)
gates what the recall hooks inject. It floors the recency-free part of the
score (keywords + vectors only), so freshness can never push a weak match
into your context: when the best hit falls below the floor, the hook injects
nothing at all rather than a tangential memory. Benchmarking confirmed that
off-topic injection can be worse than none, but harmful and useful recalls
overlapped at the same relevance scores. The calibrated global default
therefore stays off; see the calibration.
Full ranking reference, covering normalization, candidate retrieval, weight resolution, and a tuning guide, is in docs/scoring.md.
Why SQLite?
One file you can copy, back up, version-control, or delete to start fresh
There is no daemon, port, or connection string to configure
FTS5 gives BM25 ranking without an external search engine
sqlite-vec runs vector search in the same process, so there is no separate vector DB
Queries hit local disk and return in under a millisecond
Troubleshooting for Claude Code
Agent still writes to MEMORY.md
Check autoMemoryEnabled is false in ~/.claude/settings.json
Check the plugin is installed: claude plugin list should show rekal-skills
Session starts with no memory injected
The UserPromptSubmit hook recalls memory in-process (rekal hook user-prompt-submit) and injects prompt-matched hits, so memory should be present without the agent calling a tool (SessionStart injects only a directive; memories arrive with your first prompt). If nothing shows up, confirm uv is available to Claude Code's hook subprocesses, and that any REKAL_PROJECT / REKAL_DB_PATH you rely on is set where the hook subprocess sees it (shell or settings.jsonenv, not the MCP env block). See Recall hooks: environment scoping.
Memories not being stored
Check the MCP server is running: claude mcp list should show rekal. If missing:
rekal mcp # Run the stdio MCP server (what Claude Code connects to)
rekal recall # Print memories for hook context injection (--query, --project, --format)
rekal health # Database health report
rekal export # Export all memories as JSON
rekal prune # Bulk-delete memories by scope (dry-run unless --yes)
rekal prune requires at least one filter: --project NAME, --older-than-days N, or --before "YYYY-MM-DD HH:MM:SS". Without --yes it only reports the match count.