Soul

July 22, 2026 · View on GitHub

Two problems. Everything flows from them.

1. Intent has no ledger

Code has git. Every line, every change, every author — recorded forever.

But the reasoning behind the code has nothing. The conversations where a developer and an AI explored a problem, debated approaches, rejected alternatives, and arrived at a decision — those vanish the moment the session ends.

The code says what. The intent says why. And the why has no permanent, shared, immutable record.

Rekal is that record.

An append-only intent ledger. Distributed through git. Shared across the team. Immutable once written. Every decision, every rejected alternative, every dead end — captured at the moment it happens and preserved exactly as it was. No one can edit it. No one can delete it. The record is the record.

This is not a feature of Rekal. This is the first reason Rekal exists.

2. Agents can't remember

An AI agent starts every session blank. It reads the code. It does not know why the code looks the way it does. It does not know what was tried and rejected last week. It does not know that the team already explored and abandoned the approach it's about to suggest.

Humans have institutional memory — imperfect, fading, but real. Agents have none.

Rekal gives agents memory. Not general knowledge. Not search results. Recall — the precise prior context for the problem the agent is working on right now, delivered in structured form, bounded to a token budget, scored by relevance.

The agent is the reader. Not the human. Every decision about output format, query interface, and context loading puts the agent first.

This is not a feature of Rekal. This is the second reason Rekal exists.

Beliefs

Immutable. Immutability is the foundation of a ledger and the basis of trust. If anyone can edit the record, no one can trust it. If no one can trust it, there is no basis for sharing. Append-only is not a technical constraint — it is what makes the whole system work.
Intent lives next to the code. The code says what. The intent says why. They belong together — not in separate systems, not behind someone else's service.
Thin on the wire, rich on the machine. Git is the transport and every byte costs. Strip what git already has, compress what remains. Indexes, embeddings, search — all computed locally. When there's a trade-off between wire size and local compute, local compute wins every time.
Secure by design. The data never leaves git and the local machine. No servers. No APIs. No telemetry. The security model is simple: there is nothing to breach because there is nothing to connect to.
Simple. Zero dependencies. Single binary, everything embedded. Nothing to install, nothing to configure, nothing to break.
Transparent. The user sees everything that was created and can remove all of it. One command to install, one command to uninstall. No sticky tape allowed.
Agent first. The agent is the consumer. Every decision — output format, query interface, context loading, invisibility, ease of setup — favors the agent. Humans benefit as a side effect.

The skill

The skill is how the agent meets Rekal. It must make the agent stronger, not smaller.

The skill enables; it does not prescribe. It orients the agent — where the answer lives — hands it memory and tools, and trusts its reasoning. Tools remove toil, never thought. A skill that scripts the agent's steps has traded reasoning for obedience.
Thin on the route, rich on arrival. One thin route is always loaded; everything rich is pulled on demand. This is thin on the wire, rich on the machine turned inward. The token budget follows from getting this right — it is not a cap to enforce.
Three homes: function, knowledge, judgment.
- Function belongs in a script. A script does deterministic, mechanical work and hands back deterministic data for the agent's judgment to act on. It computes and reports; it does not decide. A rule the agent must remember and then perform is a script waiting to be written — this is how rule-accretion stops.
- Knowledge belongs in rich prose, loaded on demand. It informs the agent's judgment. It never makes it.
- Judgment belongs to the agent's reasoning. Weighing, interpreting, deciding under ambiguity stays with the agent — never frozen into a script, never frozen into a rule. Scripts surface signals; reasoning reads them.
- No tuned constant decides. A magic threshold that separates signal from noise — a score floor, a confidence cut, a corpus-calibrated number — is judgment frozen as a scalar. It fits the corpus it was measured on and misreads the next. A script may gate on a value the engine calibrates to be corpus-invariant by construction (a saturating transform is a property, not a fit); it may not gate on a number an author read off one dataset. When no invariant signal exists, the script reports the raw signal and the agent judges. The value changes per repo; the judgment does not belong in the file.
Every rule is an unwritten spec for a tool that doesn't exist yet. Close a gap by moving capability down to function, not by adding prose. The skill shrinks as it sharpens.
General, beholden to no single corpus. A tenet that can't be stated without naming a dataset is overfit. A constant that can't be defended without naming the corpus it was tuned on is the same overfit, one layer down.
Dogfood. Ask Rekal before changing the skill. The reasoned answer returns to the ledger.

Character

Rekal is quiet. It runs in the background and never interrupts. The agent doesn't need to think about it.

Rekal is precise. It captures exactly what matters and discards everything else. Thin on the wire.

Rekal is honest. The record is the record. Immutable. No silent updates. No rewriting history.

Rekal is opinionated. Fewer choices, fewer things that break. Simple.

Rekal is patient. It captures context today that might not matter for months. It trusts that the agent will know what to ask for when the time comes.

Voice

When Rekal speaks — in CLI output, error messages, docs — it sounds like a competent colleague. Short sentences. Plain words. Say what happened, say what to do, stop.

rekal: not a git repository (run this inside a project)
rekal: captured 3 sessions, 847 turns
rekal: pushed to rekal/alice@example.com (291 bytes added)
rekal: no sessions match "JWT expiry" in src/auth/

No exclamation marks. No emoji. No "oops." Just the facts, clearly stated, with enough context to act on.

Decisions

When facing a choice, we ask:

Does it preserve immutability?
Does the intent stay next to the code?
Is it thin on the wire?
Does the data stay within git and the local machine?
Is it simple — zero dependencies, zero config?
Is it transparent — can the user see and remove everything?
Does the agent get what it needs?
Does it enable the agent's reasoning rather than replace it?

If the answer to any of these is no, we find another way.

Refusals

We don't rewrite history. The ledger is immutable.

We don't store what git already has. Thin on the wire.

We don't depend on external infrastructure. Secure by design.

We don't phone home. Not even crash reports. Secure by design.

We don't add options where a good default exists. Simple.

We don't leave residue. Transparent.

We don't optimize for human reading at the expense of agent consumption. Agent first.

We don't add a rule where a function would do. The skill.

We don't put judgment in a script. The skill.

We don't freeze a corpus-tuned constant in a skill script. A number read off one dataset overfits the next; gate only on a signal the engine calibrates to be corpus-invariant, else report the signal and let the agent judge. The skill.

The soul in practice

Real decisions where the beliefs broke the tie.

Belief	Decision	Why
Immutable	Append-only wire format	No byte is ever modified after written. Immutability is a structural guarantee, not a policy.
Intent next to code	Git orphan branch transport	Share context through standard git push/fetch. No sync server. Works with any remote.
Thin on the wire	99% payload reduction	A 2–10 MB session becomes ~300 bytes. Strip everything git already has. Indexes and embeddings computed locally. A year of team context fits in 200 KB.
Secure by design	No external calls	Embedding model ships inside the binary. No API keys. No accounts. Data touches only git and the local filesystem.
Simple	Single binary, embedded everything	Database engine, embedding model, compression dictionary — all inside one file. Download it and you're done.
Transparent	Clean install/uninstall	`init` creates `.rekal/` and a hook. `clean` removes both completely. No hidden state anywhere else on the system.
Agent first	Hybrid ranked search, agent-readable output	Three-signal ranking. Agent controls the token budget. Compact agent-readable text by default (cheapest for an LLM to reason over), structured JSON on opt-in for programs — the agent is the reader; not human formatting.