okl — Observed Knowledge Ledger

okl — 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.

It guards against drift both ways: your agent drifting from your rules, and your rules, specs and docs drifting from the code.

Your rules, architecture decisions, past defects, documentation and diagrams: recorded once, briefed to your agent before every task (by a hook in Claude Code; any MCP agent can ask for the same briefing), each proven by a check you choose, flagged before you push (or in CI) when what it covers changes, and corrected or retired as you build. Prompts advise; the gate enforces. Use it in one repo, or share one store across every repo your team runs.

Under the hood: typed records, keyword search and one-step links. No model runs by default, okl calls no generative model unasked, and nothing is captured automatically. Three local models are optional, measured and off until you turn them on: an embedding arm, a reranker and a warm embedding model, okl warm (REPORT §4q, §4t, §4z). The scaffold's optional review step runs a generative model only if you name one, and okl review, which checks the lessons nothing re-checks, runs one only when you run it (REPORT §4ai). A lesson is written on purpose and proven by a check. The claim in full, how much of it holds today and how it has changed: docs/THESIS.md.

🚀 Quickstart · 📘 Getting started · 📥 Load your rules · 🔬 How it works · 📊 Results · 🧪 Eval report · 🧩 Plugin

pipx install 'observed-knowledge-ledger[mcp]'   # the command it installs is `okl`

okl init --repo my-repo # hooks, MCP server, push gate, starter lessons

42% → 7%. On eight tasks written to invite defects the store already knew about, 68 of 163 unbriefed attempts repeated one against 11 of 164 briefed, pooled over seven A/B runs with a different model judging than generating (the receipts, §5 finding 7). Small sample, one-shot code on bait tasks; what it does and does not show.

What goes wrong, and what catches it

Quickstart

New here? [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) walks through setup and the

habit of adding lessons as you build a feature. Already have a CLAUDE.md, ADRs, standards or

specs? [Load your rules](docs/LOAD-YOUR-RULES.md) shows how to load them, prove the ones

that matter, and keep them current.

Starting from an empty folder? [Set up a repository from scratch](docs/FROM-SCRATCH.md)

builds the CI, linters and tests okl's checks point at, for Python, .NET or TypeScript.

1. Install the CLI. Python 3.11+ (0.8.9 is the last release for 3.10), git for drift. macOS and Linux; Windows is untested (#85).[^name]

pipx install 'observed-knowledge-ledger[mcp]'

2. Wire your repo, from its root:

okl init --repo my-repo --dry-run   # lists every file it would write; writes nothing

okl init --repo my-repo # config, Claude Code hooks, MCP server, pre-push drift gate, starter lessons

init detects your stack (*.csproj, package.json, pyproject.toml …), sets the repo's interests from it, and fills the store with 20 starter lessons that hold on almost any codebase plus the bundled packs for your stack, so the first prompt is already briefed (--interests chooses your own subjects; --no-seed leaves the store empty). It wires Claude Code when the repo has a .claude/ directory or claude is on your PATH (--claude / --no-claude), installs a pre-push hook that blocks a push only when lessons have drifted (--no-git-hook skips it; --ci installs the GitHub workflow instead, --ci --git-hook both), and remembers both choices. Every path it writes, and what each is for: What okl init writes. With a branch rule that requires code-owner review, --owner @you makes each change to the thesis need your approval; okl doctor says whether GitHub enforces it, and the rule and the agent's own identity are yours to set up: Give your agent its own identity.

3. Add a rule of your own. The starter lessons are generic; what pays is what only your codebase knows. Tell your agent — *"record an okl rule for this repo: order lookups are scoped to the signed-in customer; governs app/orders.py"* — and it records the lesson with okl's okl_record MCP tool (in Claude Code, /record drafts it and asks you first). Underneath, that is one CLI call you can also run yourself:

okl record --type Rule --scope repo --id order-owner-scope \

--title "Order lookups are scoped to the signed-in customer" \ --symptom "an endpoint fetches an order by id with no owner filter" \ --fix "filter by the caller's customer id in the query; return 404 on no match"

Then prove it: okl verify order-owner-scope --run "pytest -q tests/test_orders.py" --expect passed. Loading the rules, ADRs and specs you already wrote, and the bundled packs, is Seed it.

4. Check it works:

okl check --task "add an endpoint that returns an order for the logged-in user"

okl doctor # flags other memory tools, double wiring, and where drift is gated

Which agent, which part

The hooks are Claude Code's; everything else is a command or an MCP tool and works anywhere. Setting up another agent: Getting started.

What a normal day looks like

• You prompt as usual. In Claude Code, the pre-task hook runs okl check on what you typed and puts the relevant lessons in the agent's context before it starts, and shows you one line — *okl · briefed 9 lesson(s): …* — so you can see it working (OKL_QUIET=1 hides it).
• When you learn something worth keeping — a decision, a convention the agent broke, a bug you fixed — say so and the agent records it (okl_record, or okl record), with the files it governs. In Claude Code the Stop hook also asks once, at the end of a session that changed files, what was learned, and names the lessons the session was briefed on and those whose files it changed, so the agent can propose correcting or retiring one (you approve).
• Using another agent? The briefing and recording are MCP tools (okl mcp); register them and add one line to your AGENTS.md: *before each task call okl_check*. The hooks that do this automatically are Claude Code's; see Getting started.
• When a lesson needs correcting, take its [id] from the briefing and change only what is wrong: okl update --fix "..." (or the okl_update tool) keeps the rest, including its proof, unless you change its governed --files: then it needs verifying again, and okl reverify re-runs its stored check. okl show prints the whole lesson, with how often its check has passed and failed: every run of okl verify and okl reverify is kept, so a check that caught a change leaves a record. Recording an existing id again is refused, because it used to replace the lesson and wipe its proof.
• When a lesson is wrong or replaced, retire it with a reason; nothing is deleted. okl retire --reason "..." keeps a wrong one briefed as