okl — the Observed Knowledge Ledger

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

Source on GitHub
One task, one model, run twice, in clean copies of the app (receipts in the repo, examples/dotnet-minimal-api). Without the briefing the client sets its own price and the tests still pass; with it, the price comes from the catalogue and the field is gone. The 43% against 8% at the end is the 2026-09-26 run across eight tasks, receipt ab-20260926-0528 in the repo: one-shot generations, judged by a second model.
Load your rules. Hold your agent to them. Keep learning as you build. Five stages: your rules, ADRs, standards and specs plus starter lessons for your stack, loaded up front; the store, one local file; a briefing in front of the agent before every task; gated as code moves, on every push; and it keeps learning as you build, with new lessons from mistakes, drift and failing tests, updates that keep their proof and retirements that keep their reason. The briefing before every task and the session-end question are Claude Code hooks; other MCP agents can call okl_check, and the push gate works with any agent. Six cards: one shape for every lesson (when you see, do, why); scope decides reach; selected, not skimmed; a stamp is evidence, and a stamp with no run behind it is unproven; stale blocks the push; corrected, not only added. It fails closed, keeps every check run, and starts in four commands: install, okl init, okl record with the files a rule governs, and okl verify with the check that proves it.Load your rules. Hold your agent to them. Keep learning as you build. Five stages: your rules, ADRs, standards and specs plus starter lessons for your stack, loaded up front; the store, one local file; a briefing in front of the agent before every task; gated as code moves, on every push; and it keeps learning as you build, with new lessons from mistakes, drift and failing tests, updates that keep their proof and retirements that keep their reason. The briefing before every task and the session-end question are Claude Code hooks; other MCP agents can call okl_check, and the push gate works with any agent. Six cards: one shape for every lesson (when you see, do, why); scope decides reach; selected, not skimmed; a stamp is evidence, and a stamp with no run behind it is unproven; stale blocks the push; corrected, not only added. It fails closed, keeps every check run, and starts in four commands: install, okl init, okl record with the files a rule governs, and okl verify with the check that proves it.

The problem

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.

What okl claims

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:

What it does

WhenWhat okl does
An agent is writing your code, docs, artifacts or diagramsthe 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 forthe same briefing carries that defect’s lesson
A few lessons keep being needed, change after changea 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 governsin 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 filein 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 finishin 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 checkokl 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 wrongthe 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 codeokl 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 replacedokl 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 reachedthe 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 nothingin 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:

Anatomy of okl. Keeps your coding agent true to your rules, specs and docs. Keeps them true to the code. Keeps learning as you build. load your rules, hold your agent to them, keep learning as you build. A ring around the store runs through six steps: lessons come in, up front from your rules, ADRs, standards and specs plus starter lessons for your stack, and as you build from new rules, mistakes, drift the gate finds, failing tests and reviews; each is written down as a lesson; okl proves it with a check you choose; it is briefed before each task (by a Claude Code hook; other MCP agents can call okl_check); when a file it covers changes, the pre-push hook holds the push until the check passes again or the code is back to what passed; then it is re-checked, fixed or retired. Below, real okl output follows the lesson 'order lookups are scoped to the signed-in customer' from okl record to a blocked push, where re-running its check caught a change that dropped the owner check. Then where a lesson lives (briefing only, watched for drift, build-breaking); what the briefing did (68 of 163 unbriefed attempts repeated a known defect against 11 of 164 briefed, over seven A/B runs on tasks built to invite one); how it ranks, what it costs, the review of lessons nothing re-checks, and where it breaks.

It starts from what was already paid for

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).

A ledger, not a memory

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).

How much of it holds today

From the thesis page, each line with its receipt in the repo:

The claim saysToday
it briefs the agent with what appliesbuilt 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 stepbuilt 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 firstpartly: 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 recordedpartly: 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 uncheckedbuilt: a lesson no check backs is marked UNCHECKED. In okl’s own store, 72 of 168 lessons had a check on 2026-11-02

Does it work?

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.

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?

How it differs

What the research says

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.

Where it came from

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.

Running on this site

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.

Status

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.

Where it’s going

The next steps are open issues, ordered by what the measurements above found weakest; the issue tracker is the full list.

Try it, and help build it

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: