rekal-skills

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_search("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_search (or memory_build_context). rekal blends keyword match, semantic similarity, and recency into a single score and returns the top hits.

All state is a single file: ~/.rekal/memory.db. No daemon, no cloud, no API keys. 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       # 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 — Claude Code

Three steps: add the MCP server, install the plugin, and disable built-in memory.

1. Add the MCP server — gives Claude Code the memory tools:

claude mcp add --scope user rekal -- rekal

--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) — 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 — 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 disable built-in memory, and what if I forget?

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 to a flat file with no search, no deduplication, no ranking. Disabling it (autoMemoryEnabled: false, settings docs) removes the competitor. The plugin's hooks then re-assert rekal: SessionStart restores the context injection auto memory normally provided, and UserPromptSubmit reinforces it 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.

What the plugin provides — hooks and skills