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.

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.

Install

pip install rekal
# or
uv tool install rekal

Requires Python 3.11+. On first run, rekal creates ~/.rekal/memory.db.

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

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? Claude Code's instruction priority is system prompt > CLAUDE.md > MCP server instructions. Built-in memory lives in the system prompt and always wins — without disabling it, the agent ignores rekal and writes to a flat file with no search, no deduplication, no ranking. The plugin's SessionStart hook replaces the context injection auto memory normally provides, so you don't lose anything.

What if I forget? The plugin's block-memory-writes hook will catch and block MEMORY.md writes as a safety net, but the agent wastes turns hitting the block. Disabling auto memory is cleaner.

Can the plugin do this automatically? No — Claude Code doesn't allow plugins to modify user settings. This manual step is the only way.

What the plugin provides

Hooks (automatic, no user action needed):

Hook	Event	What it does
session-start	SessionStart	Reminds agent to call memory_build_context before doing anything
block-memory-writes	PreToolUse on Edit/Write	Blocks writes to MEMORY.md, redirects to rekal tools

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, stale data — proposes fixes

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.

If you have enabled Codex memories (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 — 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"]
}

Tools

rekal exposes 21 MCP tools grouped into four categories.

Core — read and write memories: