okl MCP server

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 · ⚖️ How it is evaluated · 🧩 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

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
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 or the code is back to what passed; the next briefing marks the lesson STALE
A lesson turns out to be wrong	okl retire --reason keeps it, briefed as AVOID so nobody restates it; nothing is deleted
A lesson is replaced	okl retire --by <new-id>; the briefing points to the replacement
The store cannot be reached	the Claude Code hook blocks the prompt and says why; the MCP tool says it was not briefed. Never a clean "no rules apply"
A session changed files and recorded nothing	the Claude Code Stop hook asks once what was learned, and names the lessons the session touched

One lesson all the way round, in okl's own output:

Quickstart

New here? 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 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 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).¹

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 …, at the root or up to two folders down), 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, where drift is gated, and what your interests hide

Which agent, which part

	Claude Code	Any MCP agent (Cursor, Codex, Copilot …)	Any agent, or none
Briefing before each task	a hook on every prompt, automatic, fails closed	the okl_check tool, when the agent calls it	okl check in the terminal or a script
Briefing when a file is read	a hook after each Read: the lessons governing the file, once a session	okl_check with path	okl check --path
Review after writing (opt-in)	the Stop hook asks for it after okl init --review-after-writing	not yet: the list is about 20k tokens in a 300-lesson store, and the review starts a fresh sub-agent for each lesson it checks	okl check --change
Recording what was learned	the Stop hook asks once per session that changed files	the okl_record tool	okl record
Proof and drift	okl verify, okl reverify, okl drift	the same commands	the same commands
The gate	the pre-push hook	the pre-push hook	the pre-push hook, or the CI workflow (okl init --ci)

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 <id> --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 <id> 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 <id> --reason "..." keeps a wrong one briefed as AVOID, so nobody restates it; --by <new-id> takes a replaced one out of briefings, which point to the new one; --obsolete is for a lesson whose subject is gone. A fixed defect is not retired: it keeps briefing against its return.
• Proving a lesson is true is a check you run, not a flag you set: okl verify <id> --run "pytest -q tests/test_orders.py" --expect "passed".
• When code a lesson governs changes, okl drift goes red until its check passes again, or the code is put back as it was when the check passed (a lesson recorded with --files is also red until its first okl verify). The briefing says so too: such a lesson is marked STALE (or UNVERIFIED, or UNPROVEN) with the file that changed, so the agent confirms it against the code instead of trusting it blindly. A lesson that governs no files here, and was never verified or carries a stamp with no okl verify run behind it, is marked UNCHECKED; drift has no verdict on it, so nothing else would say so. The agent treats it as advice, and one line under the briefing says how many there are. okl reverify re-runs each drifted lesson's stored check after you confirm. Drift notices that what a lesson watches changed; it does not find every break. Of 52 patches written to break the lessons it watched in this repo, a judge confirmed 36 as breaks, and drift caught 14 of those 36; most of the misses changed a file one step from the ones the lesson watches (REPORT §4af). So list every file a lesson's claim depends on, and read a green drift as "nothing it watches moved". With the GitHub workflow (okl init --ci), CI reads a committed snapshot, okl-drift.json, which okl verify creates the first time a lesson with --files is verified and keeps current after that: commit it after the code change it verifies. Until then CI warns "Drift not checked", which is expected. Without the workflow, okl verify writes no snapshot unless one is already committed.
• Headless runs (claude -p, scripts, CI agents) set OKL_DISABLED_HOOKS=encode, or the end-of-session question replaces the printed answer.

The problem it solves

A team, or an agent, fixes a subtle bug, learns why it happened, and writes a rule to prevent it. Weeks later, in a different file or a different repository, the same class of bug comes back, because the person or agent doing the new work never saw that rule. The knowledge existed; it was not in front of whoever needed it, at the moment they needed it. And when it was, it was often out of date: the code it described had moved on.

okl answers both. The relevant lessons are read automatically at the start of a task, not looked up if someone remembers to, and a lesson stays true or goes stale loudly: each is proven by a check you choose and re-opened when the code it covers changes.

This is a v0 starter, not production-hardened. It ships an end-to-end test suite (pytest -q shows the suite and its result in your environment). The core is stdlib-only with zero required dependencies.

What okl is

A store of your engineering lessons, and the machinery that keeps them true. Typed records (rules, architecture decisions, known defects, gates, tombstones, retractions) that are briefed into an agent's context before a task and go stale loudly when the code they describe moves on. Everything measured in evals/REPORT.md measures this.

It is worth being precise about what that store fills up with, because "lessons a codebase has learned" invites the picture of a bug database. In the 183-record corpus in seed/ it is mostly not that: 110 Rules, 20 Decisions and 7 Gates against 36 Defects — conventions the code follows and trade-offs already settled, not a ledger of things that broke. Count it yourself:

python3 -c "import json,glob,collections; c=collections.Counter(
  n['type'] for f in glob.glob('seed/*.json') for n in json.load(open(f))['nodes']); print(c)"

A second, optional thing ships in the package: okl scaffold, a starter kit for the in-repo discipline the store assumes (a lean rules file, mechanical gates, a review agent, an eval harness). It has never been measured; use it to get a new repo to the state where a store has something to attach to.

What okl is not for

okl holds lessons: what an agent would see or do (the symptom), what to do instead (the fix), why, and where it can be proven, the check. Most of a good agent setup is other things, and they work better elsewhere:

If it is…	Put it in	Why not okl
a rule every session needs, whatever the task	CLAUDE.md / AGENTS.md	those load in full every time; a briefing picks lessons per task
a procedure: how to release, migrate or set up	a skill, runbook or script	a procedure is read whole and in order; a briefing hands over a few short records
commands, and "for X, read Y" pointers	CLAUDE.md / AGENTS.md, or a skill	it is a map the agent needs on every relevant task
formatting and code style	a formatter or linter	a tool enforces it on every line; a lesson can only remind
a bug that is still open	your issue tracker	the tracker owns open work; okl keeps what was learned once it is fixed
secrets, credentials, personal data	nowhere near okl	the store is shared and its lessons are copied into agent context

Everything with a symptom and a fix belongs here: a convention the code follows, a decision made on purpose, a defect class you have already paid for. The getting-started guide has the same split from the side of recording.

Footnotes

1. The PyPI name differs because PyPI refuses okl as confusable with oki; everything you type afterwards is okl. ↩