context compiler for AI agents

A deterministic compiler over rectified context.

Akela turns your existing markdown knowledge base — a wiki, a references folder, a team playbook — into a bounded, reproducible context slice per task, and uses evidence from agent runs to govern what that knowledge becomes.

Three tools, three different questions:

RAG asks:: what information is probably relevant?
Agent memory asks:: what should the agent remember?
Akela asks:: what knowledge is this agent authorized to use for this task — and what evidence justifies changing that knowledge?

Read the source

MIT. No signup. No telemetry.

If you already have a RAG, keep it: retrieved results enter the slice as just another tracked source.

The audit trail is the product

Every compile opens with a manifest — what was packed and what was dropped, with reasons. This is a real one:

slice.md

---
manifest: 1
run: refund-T-4821-15816c
activity: refund
compiler: akela 0.1.4   domain: default   scoring: off
sources:
  - id: WIKI-refunds#approval   tier: must   lines: 2
  - id: LRN-20260829-01   tier: lrn   lines: 3
  - id: WIKI-refunds#method   tier: should   lines: 2
dropped:
  - id: WIKI-shipping#carriers   reason: general-scope
---

The question “was the stale rule in front of the agent?” is answered by a file, not a guess.

Three primitives

Everything in Akela is an implementation of one of these:

1 · Knowledge

What your team believes, in markdown you own. Wiki sections, proposed learnings, retrieved notes. Akela indexes it and never writes it.

2 · Compilation

What the agent is allowed to know for this task. Deterministic set logic — no embeddings, no LLM step: same inputs, same slice, byte for byte. Every compile opens with the manifest above.

3 · Evidence

What happened when the agent used that knowledge. The agent reports what it applied and what the outcome contradicted; an append-only, content-hashed log accumulates a record per rule. Rules that keep failing are flagged falsified and provably stop appearing. A curator reads the counts and decides; nothing changes your knowledge base silently.

Measured, not promised

The whole claim set was put through our experiments: three isolated agents and a deterministic grader outside the loop, run across many conditions and seeds with every result archived. The buyer's table — files / maintained wiki / RAG, each without → with Akela, same bed, same model, same grader, after the rules change:

	files	maintained wiki	RAG
accuracy	0.53 → 0.51	0.96 → 0.90	0.89 → 0.81
stale rules in context	26/26 → 21/26	17/26 → 2/26	23/26 → 21/26
context tokens / task	35,690 → 139	35,773 → 138	35,772 → 201
$ / correct answer	$2.37 → $1.48	$1.17 → $0.81	$1.45 → $1.02

Stated honestly, in the order the data forces:

Maintenance beats tooling. The biggest jump anywhere is unmaintained files → maintained wiki (0.53 → 0.96), from nothing but someone keeping the source current. Akela's job is making that affordable and provable, not replacing it.
On raw accuracy, dumping everything wins every pair by a hair — and stayed flat to 353k tokens/task in a scaling test. If today's accuracy is all you measure and tokens are free, you don't need this tool.
Akela wins everything structural, in every pair: context 257× smaller at any knowledge-base size, better cost per correct answer, and a knowledge base that is provably clean (2/26 → 0/26 stale at 10× scale) instead of attentionally lucky.
Unlearning works unattended; relearning needs the source. Corrections that arrive through the wiki are adopted without anyone being told; retrieved corrections graduate into the wiki through the promotion path.
The residual failure is epistemic, reproduced 3/3: a correct, freshly-updated rule can be retired on sincere wrong distrust. Every mechanism checks whether evidence is honest; none can check whether it is right. That is why the curator exists.

How it works

Four mechanisms, all deterministic — no model, no embeddings, no tunable scores. The same inputs always compile the same slice, and every change in what an agent sees traces to a visible edit or a counted line.

The loop: count everything, decide nothing

Akela is a clerk between your knowledge base and your agent. It reads, packs, and counts — the only hand that writes the knowledge base is the curator's, and only after reading the counts. The loop can verify that evidence is honest; only the curator can know whether it is right.

Selection: set logic over human tags

No embeddings, no similarity, no LLM step. The request declares an activity; sections declare scope and tier. The slice scales with the rules relevant to the task, not with wiki size — and everything not packed is still named in the manifest.

The life of a rule

Falsification is a recency test — contradicted in two of the last three runs that touched the rule. The capture gate is set arithmetic: a capable model can out-argue a prose rule; it cannot out-argue set intersection. Evidence is version-scoped, so a rewrite starts with a clean record.

Retrieved notes graduate

Plain RAG pastes similar text into context, forever. Akela treats every retrieved chunk as an addressable claim with a performance record — when the record is earned, the curator promotes it into the wiki: retrieval is how truth travels, while the wiki stays where truth lives.

The full picture, one diagram per mechanism: docs/how-akela-works.md

Two users, one loop

Akela has two users with different jobs: you set it up and curate; your agent operates it on every task. init generates three protocols; your agent runs the cycle, and you supply only judgment — one review table and a yes/no at each decision point.

moment	who acts	protocol
every task	agent: compile → work from the slice → log evidence	PROTOCOL.md
initial scoping, and whenever new pages appear	agent drafts scope/tier, you approve — every compile reports unscoped drift, so new pages are noticed within hours	ONBOARD.md
critical finding mid-task	agent asks whether to run the review now	PROTOCOL.md → CURATE.md
weekly, or per sprint	agent runs stats, reads the notes, hands you one review table; approved edits applied and validated	CURATE.md

The division is the design: the agent drives everything except judgment; you supply only judgment, and only when there's evidence to judge.

Quick start

1 · You, once — install and point it at your knowledge
```
npx akela init --knowledge wiki
npx akela index
```
init writes akela.json, LEARNINGS.md, and the three agent protocols (PROTOCOL, ONBOARD, CURATE). --knowledge takes any markdown folder — wiki/, docs/, kb/, notes/. RAG is not an init flag; plug yours in after, one line in akela.json.
2 · You, once — wire your agent
```
Follow akela/PROTOCOL.md for every task.
```
That line — in the instruction file your agent auto-loads (CLAUDE.md, AGENTS.md, .cursorrules) — is the entire integration. A file on disk does nothing by itself; init detects your instruction file and names it.

3 · Your agent, every task — automatically, per the protocol

akela compile --activity support --task T-123
akela log applied WIKI-refunds#under-50
akela log contradicted LRN-20260822-01 --note "…"
akela log outcome --status DONE

The slice is the agent's only source of domain knowledge; the log lines are the evidence the loop runs on.

4 · You, ten minutes a week — curate from the counts
```
akela stats
akela check
```
The counts recommend; you decide. “Follow akela/CURATE.md” turns the whole routine into an agent-drafted table you approve.

Publishing next

after the current field assessment

Blog

What the agents got wrong — the article behind the numbers on this page.

Experiments

The full program: harness, task beds, result archives, findings — reproducible.

Devlog

The running record, including the retractions.