

Keeps your coding agent true to your rules, specs and docs. Keeps them true to the code. Keeps learning as you build.
PythonSQLite / PostgresFastAPIMCPClaude CodeGitHub ActionsEval harness


A coding agent lets a team down in three ways, and each needs its own answer.
The agent drifts from your rules. A team fixes a subtle bug, learns why it happened and writes a rule to prevent it. Weeks later the same class of bug is back, in a different file or a different repository, because the agent doing the new work never saw the rule, or saw it in a rules file loaded whole and gave it no weight. A model starts every session with no memory of what this codebase has already been burned by, and it writes code faster than anyone can review it back into line. A prompt can only advise; nothing holds the line.
Your rules, specs and docs drift from the code. The rule is found and applied, but the code it governs moved months ago, so what gets handed over is confident, specific and wrong. The same rot reaches everything a repository says about itself: a README describing a flag that was renamed, a diagram showing a service that was merged away, a figure quoting a run whose receipts were never committed. All of it reads as current, because nothing marks it as anything else, and nothing ever proved it held in the first place.
What a session learns is lost. The agent finds why a test failed, a reviewer catches a pattern, a rule turns out to be wrong. The session ends and the lesson goes with it. Or it is written down once and never corrected, so a wrong rule keeps being restated and a replaced one keeps being followed.
okl answers each in turn. It briefs the agent with the lessons that apply before each task, and blocks a push when one of them has drifted. It proves each lesson with a check you choose, flags it when what it covers changes, and marks the ones nothing proves. And it keeps learning: in Claude Code it asks at the end of each session what was learned, and every correction or retirement keeps its reason.
Three sentences, held to their evidence on the thesis page, which says how much of each holds today and how the claim has changed:
Keeps your coding agent true to your rules, specs and docs. Keeps them true to the code. Keeps learning as you build.
Before each task, okl briefs the agent with what applies. When something you maintain falls out of step with what it describes, okl notices and has the agent bring it back, telling you or asking first. Each session’s lessons are recorded, so the next starts from more. Every claim is backed by a check you choose, or marked unchecked.
Two rules hold throughout:
okl review runs one only when you run it, and the scaffold’s optional CI review step only
if you name one.| When | What okl does |
|---|---|
| An agent is writing your code, docs, artifacts or diagrams | the briefing puts your matching lessons in front of it before it writes, selected by the task’s words and, in Claude Code, by the files it reads |
| The agent is about to repeat a defect you already paid for | the same briefing carries that defect’s lesson |
| A few lessons keep being needed, change after change | a repo names up to ten as standing lessons (okl standing), and every task briefing lists them, one line each, whatever its words |
| The agent reads a file a lesson governs | in Claude Code, the lesson arrives beside what it read, before any edit, found by the files it names rather than by words |
| The agent edits a file | in Claude Code, the lesson checks you approved (okl on-edit add) run after each edit, those of the file’s own lessons first, and a failing one goes back to the agent beside its edit; okl verify and okl reverify time each check they run, and okl on-edit add --quick offers to approve the ones quick enough to run after every edit |
| The agent has written the code and is about to finish | in Claude Code, okl check --change has it pick the ten lessons its change most likely breaks and check each in its own fresh sub-agent, on Sonnet, the model it was measured with, which since 0.19.0 first lists every path the lesson’s rule covers, fixing any it breaks; a long list comes in pages, each short enough to arrive whole; on by default since 0.17.0, by my decision; on 43 graded past bugs in this repository it gained 0.244 over no review, just under the bar set in advance, with an interval that includes it (okl init --no-review-after-writing turns it off), and since 0.18.0 okl recap --reviews reports, across real sessions, how often it ran, what it checked, how often a check was followed by an edit and, since 0.19.0, whether every page reached the agent (from the store okl writes to, not through a shared service) |
| Code a lesson covers changes after its last check | okl drift goes red; the pre-push hook holds the push (or CI fails) until the check passes again, and the next briefing marks the lesson STALE |
| A lesson nothing re-checks may have gone wrong | the briefing marks it UNCHECKED, and okl review, when you run it, has a model check it against the repo |
| A change renames or deletes a file a lesson names, or moves its code | okl changes reads the change with git alone, no model, and proposes the update to the lesson’s files for you to confirm |
| A lesson turns out to be wrong, or is replaced | okl retire keeps it with the reason: a wrong one is briefed as one to avoid, a replaced one points to its successor |
| The store cannot be reached | the Claude Code hook blocks the prompt with the reason, and the MCP tool says it was not briefed: never a clean “no rules apply” |
| A session changed files and recorded nothing | in Claude Code, the end-of-session question asks once what was learned, and names the lessons the session touched |
Underneath are typed records (rules, decisions, past defects, gates), keyword search and
one-step links, in one local file or a shared store. A lesson reaches every repo that shares
the store, or only its own, by scope, so a .NET quirk never fires in a Python service.
okl init detects the stack and loads starter lessons for it, so the first prompt is
briefed. In Claude Code, hooks brief every prompt, brief a file’s lessons when the agent
reads it, and ask the end-of-session question; any agent that speaks MCP can ask for the same
briefings, and okl is listed on the official MCP Registry. The push gate works whichever agent wrote the code.
It holds what has a symptom, a fix and a check: a convention the code follows, a decision
made on purpose, a defect class already paid for. A rule every session needs belongs in
CLAUDE.md or AGENTS.md, a procedure in a skill or runbook, code style in a linter, and an
open bug in the tracker.
One lesson followed all the way round, in okl’s own output:
A new store is not empty. okl ships twelve seed packs: real, dated lessons mined from
NextAurora, the riparian pipeline, the Quartzose eval work and other
production codebases, including the ones that cost the most to learn, with a Python canon whose
every lesson cites the sources that agree on it. Most of it is not a list of bugs: 110 Rules,
20 Decisions and 7 Gates against 36 Defects, the conventions code follows and the trade-offs
already settled. okl init detects your stack and loads the packs that fit, so the first
prompt is briefed.
Your own rules come in the same way. Given a CLAUDE.md, ADRs, standards and specs, in Claude
Code /seed-from-docs has the agent read them and propose lessons that each cite the line they
came from, into a file you review before anything is imported
(Load your rules).
The name says what it keeps. Observed: a lesson counts as proven only after a check you
chose ran and passed. okl record --verified is refused, and every run of a check, pass or
fail, is kept. Ledger: nothing is deleted. An update keeps the lesson’s proof, a retirement
keeps its reason and what replaced it, okl recap --report reads back what a session was
briefed on, recorded, retired and checked, and okl recap --reviews how often the review after
writing ran, what it checked and how often a check was followed by an edit.
Across an organisation the ledger is a git repository of packs. A lesson enters it the way code does, as a pull request whose diff shows the symptom, the fix and the check. Every repo that loads a pack proves it again on its own code, so verified means this repo’s check ran, not that the reviewer believed it. Each repo’s store stays local, and nothing in the loop calls a service (Across an org).
From the thesis page, each line with its receipt in the repo:
| The claim says | Today |
|---|---|
| it briefs the agent with what applies | built for lessons whose subject the task names or that name a file the agent reads; not yet for a lesson that applies to what the code does and names no such file, which takes a channel that reads the change. On eight tasks written to invite defects the store already knew, 68 of 163 unbriefed attempts repeated one against 11 of 164 briefed: 42% → 7%, pooled over seven A/B runs. On real work, 0 of 2 lessons that applied by what the code did reached the agent |
| it notices when something you maintain falls out of step | built for lessons that name files and carry a check, including docs a lesson names; not yet for docs, diagrams, specs and reports in general (#317, #314) |
| it has the agent bring it back, telling you or asking first | partly: a drifted lesson blocks the push or fails CI, and the briefing marks it STALE; telling or asking for other artifacts is still to come |
| each session’s lessons are recorded | partly: in Claude Code, the end-of-session question asks what was learned once per session, so a long-running session can go a day of work unasked (#391) |
| every claim is backed by a check, or marked unchecked | built: a lesson no check backs is marked UNCHECKED. In okl’s own store, 72 of 168 lessons had a check on 2026-11-02 |
The briefing results below were measured on authored tasks. On real work, two lessons that applied were missed by every retrieval arm that ran, and none of those measurements could have shown it. The standard okl is now held to says where each claim stands against it. Measurements on real pull requests have started, and their results stay in the report, marked as model-judged, until a person has audited the judge.
Held-fixed A/Bs, with the method and every raw receipt committed in the repo
(evals/REPORT.md): eight authored tasks, three samples per arm, and a different model
judging than generating.
okl review shipped, a registered run
mixed planted wrong details and lessons known to be current in blind. The judge caught 8 of 10
planted wrong details and wrongly flagged 1 of 10 current lessons, both exactly at the bars
set in advance. On okl’s own store it questioned 9 of the 80 unchecked lessons that make a
claim, and all 9 were confirmed and corrected.What it does not show, stated in the report as plainly as here: the tasks were authored to
invite defect classes the store encodes, so the A/B measures what a briefing does when a
directly relevant lesson exists. Not general code quality, and not retrieval at scale. n is
small. It’s a pilot with receipts, not a benchmark.
The methods behind okl’s tests on real defects and past changes, with their pilot results, are written up as a methods paper: Does a lesson change what a coding agent writes?
CLAUDE.md, AGENTS.md): a briefing selects the few lessons that
match the task; a rules file loads whole, every time, and nothing re-checks it.okl came out of frustration on real projects. The research came after, across about two dozen coding-agent tools and published setups and the year’s papers on agent memory, and it kept saying three things:
The papers went further this year, from three directions. One group found that a memory layer still left 57.5% of a user’s applicable preference checks violated, and that compiling corrections into checks the agent must pass cut repeated violations from 100% to 37.6% on held-out tasks. Another showed a self-improving agent harness inventing a guardrail for a failure that provably never happened in 15 of 60 runs, and that only accepting a rule when a real violation warrants it keeps the invented ones out. A third found that what carries between codebases is the abstract lesson and the validation routine, and that raw traces are the weakest form. Those are the three things okl is built around: the check rather than the note, no stamp without a run, and lessons recorded as rules, decisions and gates rather than transcripts. The papers, with figures read from the PDFs and a column saying where okl stands beside each, are in docs/RELATED-WORK.md, and in The papers caught up.
Every surface in the encoding loop stops at the repo boundary: canon, tombstones, audits, gates and reviewers each protect the repo they live in and nothing else. This is what carries a lesson past that boundary, and proves it again where it lands.
This site is built with okl wired in, so it is a user of the tool and not only a page about it. A prompt-submit hook briefs every coding session before work starts, and it fails closed: if the store cannot be reached, the prompt is blocked rather than answered with no lessons. The store holds 70 lessons from building this site, 47 of them org-scoped because nothing about them is particular to it: a CSP that silently blocked the webfonts in production while the dev server showed them fine, an Astro whitespace rule that deletes spaces next to tags, a grid minimum that overflows a phone.
Running it here also found defects in okl itself. The install instructions named a package PyPI refuses, the tag vocabulary was compiled into the package so this repo’s lessons would not import, and the hooks found their config by walking up from the working directory, so a session whose shell had moved elsewhere had every prompt blocked against a store that was fine. The first two were fixed in 0.5.0 and the third in 0.6.0.
pipx install 'observed-knowledge-ledger[mcp]' installs it, and the command is okl; PyPI
refuses okl as a name. In Claude Code its hooks and MCP tools can also come from the plugin
(/plugin marketplace add emeraldleaf/okl, then /plugin install okl@okl), which still
needs the CLI. MCP clients can add its server from the official MCP Registry, where it is
io.github.emeraldleaf/okl. The current release is on
PyPI, and the
changelog lists every change.
Still a v0: flat retrieval by decision, with optional local models that the measurements did not make the default, a small store and one author. It is published because the bet is legible and the receipts are checkable, not because it is finished.
The next steps are open issues, ordered by what the measurements above found weakest; the issue tracker is the full list.
okl verify times each check it runs, and okl offers the quick ones. Next, measure whether they
catch real breaks at the edit rather than at the push
(#435).
Lessons that point at real code to imitate
(#436) and files that ask you before an
edit (#437) come after it.okl command
and flag in the README and docs is checked against the CLI, but other claims only in the
README and the getting-started guide
(#314).okl review runs when you run it; next, on
a schedule, and when a file a lesson names changes
(#357).AGENTS.md for agents that never ask (#96).Starting a new repository? Set up a repository from scratch builds the CI, linters and tests okl’s checks point at, for Python, .NET or TypeScript, then wires and seeds okl and shows how to prompt it. Already have rules, ADRs and standards? Load your rules turns them into lessons.
It is MIT-licensed and open to contributors. The most useful help right now:
git clone
(discussion #106).