rekal

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.

How it works · Quickstart · Install · Setup · Updating · Tools · Under the hood · Troubleshooting

Works with any MCP-capable agent: Claude Code, Codex CLI, OpenCode.

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

1. Store. The agent saves a durable fact with memory_store: a preference, a decision, a non-obvious discovery.
2. 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.
3. 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
}

<details> <summary><b>Why disable built-in memory, and what if I forget?</b></summary>

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