Rekal
This page describes the current main branch. Native memory integration,
literal search pagination and query --ref are unreleased changes; the
v1.0.2 installation does not include them. See the changelog for release status.
Rekal is a command-line tool that captures your AI coding sessions at every git
commit, stores them in your repo, and lets any agent recall the reasoning behind
a past decision — including the approaches that were tried and rejected.
Once that work merges, it travels to your teammates over the same git push
and git fetch you already run — so their agents start from your reasoning, not
from nothing. No server, no account, no memory service in the middle.
Quick start · Commands · How it works · Team memory · Benchmarks · Docs · Paper · Discord
📄 Research published: "Why Git Is the Memory Solution for the Agentic Development Lifecycle" on arXiv (2607.14390)
Memory that lives in git — shared by your team, personally adaptive as you recall. Works with Claude Code, Cursor, Copilot, Codex, Gemini, Kiro, and OpenCode.
Every AI session settles decisions: why this approach, what got tried and thrown away. Then the session ends and that reasoning is gone. Rekal captures it at every commit, stores it raw in git, indexes and embeds it locally in the background, and shares it across your team when the work merges. There is no memory SaaS and no external memory service. Embedding is local, and the whole store is a .rekal/ directory in your repo. Your agent recalls the conversation behind any change: the reasoning, the dead-ends already ruled out, the exact decision, in ~7.5K context tokens and a few seconds, from git.
- Know why, not just what — the conversation behind every change, not just the diff.
- Stop re-deciding — dead-ends already ruled out stay ruled out; nobody re-proposes them.
- Team memory in git — and only merged work: an unmerged spike never leaves your machine.
- Personalised & adaptive — as you recall, the memories you keep returning to get a usage hint and a small ranking boost. On your machine only, never synced.
- Scrubbed before it's stored — transcripts pass through secret redaction (pattern + entropy) and home-path anonymization before they reach the database, let alone the wire.
Why not just…?
| Instead of | The gap | Rekal |
|---|
a MEMORY.md / CLAUDE.md notes file | rots, hand-maintained, tied to one branch | captured automatically at every commit, immutable, branch-aware |
| a hosted memory layer (Mem0, Zep, Letta) | a service and a vector tier to operate, your transcripts on someone else's box, memories distilled lossily up front | nothing to operate, nothing leaves the machine, raw sessions kept whole and reasoned over at query time |
| editor/agent memory (Cursor, Copilot, Claude Code) | per-user, per-tool, ephemeral, no team history | team-wide persistent memory, travels with the repo, one ledger every agent reads |
| a RAG index over your repo | indexes the code, the artifact, not the argument that produced it | indexes the conversation: the rejected options and the reason they lost |
git log / git blame | tell you what changed, never why | the conversation and reasoning behind the change |
Quick start
Requirements: git, and macOS on Apple Silicon or Linux (x86-64 / arm64).
Nothing else — no runtime, no Python, no API key, no service to run.
Status: 1.0. The store format, wire format, command surface and exit
codes are covered by the version number, and breaking any of them now
requires a major version. docs/compatibility.md
states exactly what that covers and what it deliberately does not —
ranking and index.db stay unfrozen so retrieval can keep improving.
The binary is ~170 MB to download and ~200 MB on disk. That is the
tradeoff for a single file: the inference engine, the embedding model, the
database, and the full-text extension all ship inside it, so there is no model
download on first run, no service to start, and recall works offline.
From Claude Code
/plugin marketplace add rekal-dev/rekal-cli
/plugin install rekal@rekal-dev
Then /rekal:install once per machine, and /rekal:init in each repo you want
memory in. Both confirm before touching anything. That's the whole setup — skip
to step 3 below.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
