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.

Related MCP server: LumenCore

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 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.

Hooks (automatic, no user action needed):

Skills (user-invocable):

Setup — Codex CLI

One step. rekal is a standard MCP stdio server — no plugin system, no competing memory to disable (Codex memories are off by default).

Add to ~/.codex/config.toml (Codex MCP docs):

[mcp_servers.rekal]
command = "rekal"

# optional: scope all memories to a project automatically
[mcp_servers.rekal.env]
REKAL_PROJECT = "my-project"

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.

(memories = true in ~/.codex/config.toml): disable them to avoid competing memory instructions.

[features]
memories = false

Setup — OpenCode

One step. OpenCode has no built-in memory system, so rekal plugs in cleanly with no conflicts.

Add to opencode.jsonc in your project root (OpenCode MCP docs):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rekal": {
      "type": "local",
      "command": ["rekal"],
      "enabled": true,
      "environment": {
        "REKAL_PROJECT": "my-project"
      }
    }
  }
}

OpenCode does not auto-read AGENTS.md; you must list instruction files explicitly (OpenCode config docs). Add to your opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["AGENTS.md"]
}

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. No manual migration step, no data loss. 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 21 MCP tools across four categories. The three you'll use most:

Core — read and write memories:

Smart write — manage knowledge over time:

Introspection — explore what's stored:

Conversations — track session threads:

Under the hood

Storage

Everything lives in ~/.rekal/memory.db. Three subsystems share it:

• memories table — content, type, project, tags, timestamps, access counts, plus tier (durable or scratch) and optional expires_at

• FTS5 virtual table — full-text index over content+tags+project, auto-synced via triggers

• sqlite-vec virtual table — 384-dimensional vector index for semantic search

Memory links (supersedes, contradicts, related_to) are stored in a separate table. memory_supersede writes the new memory and creates a supersedes link in a single operation, so old knowledge stays queryable with explicit lineage.

Tiers. Durable memories live forever; scratch memories carry an expires_at and are hard-deleted on server start once past their TTL. Search, timeline, and topics hide expired scratch entries automatically. Use scratch for in-flight hypotheses and working notes that should not pollute the durable store.

Data model

One table does the work; everything else hangs off it.

A memory has three orthogonal axes: type (fact / preference / procedure / context / episode), tier (durable, or scratch with a TTL), and links (the graph). The full schema — every column, trigger, foreign-key note, and query lifecycle — lives in docs/data-model.md.

Embeddings

rekal uses fastembed with BAAI/bge-small-en-v1.5 (384 dimensions). Runs locally via ONNX — no API calls, no network. The model downloads once on first use (~50MB) and is cached.

Search

Every memory_search runs two parallel lookups, merges candidates, then scores:

score = w_fts × sigmoid(-BM25)                       ← keyword relevance    (default 0.4)
      + w_vec × (1 - cosine_distance)                 ← semantic similarity  (default 0.4)
      + w_recency × exp(-0.693 × days/half_life)      ← recency              (default 0.2, 30-day half-life)

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 at four levels:

Layers resolve per-key independently. A .rekal/config.yml setting w_fts and a DB override for half_life combine, and each key uses its highest-priority source.

# .rekal/config.yml
scoring:
  w_fts: 0.6
  w_vec: 0.3
  w_recency: 0.1
  half_life: 14.0

Full ranking reference — normalization, candidate retrieval, weight resolution, and a tuning guide — in docs/scoring.md.

Why SQLite?

• Single file — copy, back up, version-control, or delete to start fresh

• Zero config — no daemon, no port, no connection string

• FTS5 built-in — BM25 ranking without an external search engine

• sqlite-vec extension — vector search in the same process, no separate vector DB

• Sub-millisecond — local disk I/O, no network round-trips

Troubleshooting — Claude Code

Agent still writes to MEMORY.md

1. Check autoMemoryEnabled is false in ~/.claude/settings.json

2. Check the plugin is installed: claude plugin list should show rekal-skills

Agent doesn't call memory_build_context at session start

The SessionStart and UserPromptSubmit hooks inject a reminder at session start and on every turn. If the agent still ignores it, add to your project's CLAUDE.md:

Call memory_build_context before exploring the codebase.

Memories not being stored

Check the MCP server is running: claude mcp list should show rekal. If missing:

claude mcp add --scope user rekal -- rekal

Hooks or skills missing after a plugin update

Claude Code may serve a stale plugin cache. Clear it and reinstall (see Update the Claude Code plugin).

CLI

rekal serve    # Run as MCP server (default)
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, --memory-type TYPE, --older-than-days N, or --before "YYYY-MM-DD HH:MM:SS". Without --yes it only reports the match count.

Architecture (for contributors)

Plugin (hooks + skills)
  │
  ├── hooks/
  │   ├── handlers/session-start.py        ← SessionStart: inject context reminder
  │   ├── handlers/user-prompt-submit.py   ← UserPromptSubmit: re-assert rekal every turn
  │   ├── handlers/block-memory-writes.py  ← PreToolUse: redirect MEMORY.md writes to rekal
  │   ├── handlers/redirect-memory-reads.py ← PreToolUse: redirect MEMORY.md reads to rekal
  │   └── handlers/shared.py               ← shared path predicate + deny helper
  │
  └── skills/
      ├── rekal-init/    ← /rekal-init: bootstrap project knowledge
      ├── rekal-save/    ← /rekal-save: end-of-session capture
      ├── rekal-usage/   ← /rekal-usage: operational guide for tools
      └── rekal-hygiene/ ← /rekal-hygiene: maintenance

MCP Server (rekal)
  │ stdio (JSON-RPC)
  │
  mcp_adapter.py          ← FastMCP server, lifespan, instructions
  │
  ├── tools/core.py       ─┐
  ├── tools/introspection.py│─ thin @mcp.tool() wrappers
  ├── tools/smart_write.py  │
  └── tools/conversations.py┘
                            │
                    sqlite_adapter.py ← all SQL lives here
                            │
                            ├── SQLite (memories, conversations, tags, conflicts)
                            ├── FTS5 (full-text index)
                            └── sqlite-vec (vector index)

Instruction flow (single source per concern):

License

MIT