返回资讯中心
外部精选
软件工程
#开发者实时流

Okl – hold your agent to rules proven by checks and gated at push

Guardrails and a learning loop for AI coding agents.

Hacker News 最新emeraldleaf2026/10/18 · 2026/10/1830 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

okl — Observed Knowledge Ledger

Guardrails and a learning loop for AI coding agents.

Engineering rules, architecture decisions, 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), proven by checks you choose, and flagged before you push (or in CI) when what they govern changes. Each session's lessons are fed back in. Use it in one repo, or share one store across every repo your team runs.

🚀 Quickstart · 📘 Getting started guide · 🔬 How it works · 📊 Results · 🧪 Eval report · 🧩 Plugin

A small store of what a codebase knows — its conventions, architecture decisions and why they were made, the checks that catch mistakes already made once, and the claims its docs and diagrams make — plus a hook that hands the relevant ones to a coding agent (or a person) before they start a task. Each session can record what it learned, so the store grows with the work; it survives past a session and can be shared across a team. And it stays true: an entry is verified by running a check, and flagged when the files it governs change, whether those are code, docs or diagrams.

New here? docs/GETTING-STARTED.md walks through setup, the habit of adding to the canon as you build a feature, and keeping your docs from drifting. 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.

  1. Install the CLI (the PyPI name differs — PyPI refuses okl as confusable with oki — but everything you type afterwards is okl):

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

Needs Python 3.10+ (and git for drift detection). Tested on macOS and Linux. Windows is untested: the core should work, but the Claude Code hooks likely need fixes there (#85).

  1. Wire your repo. From the repository 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).

init wires Claude Code when the repo has a .claude/ directory or claude is on your PATH; --claude forces it and --no-claude skips it. Drift is gated locally by default: in a git repository init installs a pre-push hook that runs the drift gate and blocks a push only when lessons have drifted (--no-git-hook skips it). The GitHub Actions workflow is opt-in, because it spends a private repo's minutes and does nothing on another CI: --ci installs it instead of the hook, unless an earlier init already installed the hook, which stays (--ci --git-hook gives both), for a team that wants a gate git push --no-verify cannot skip; a repo an earlier okl gave the workflow keeps it. Later runs remember both choices. Prefer the plugin? Install it before running init — /plugin marketplace add emeraldleaf/okl, then /plugin install okl@okl in Claude Code — and init leaves the hooks to the plugin, so nothing is wired twice. (Installed after? okl doctor reports the double wiring; run okl init --uninstall, then okl init again, which leaves the Claude Code hooks to the plugin and reinstalls okl's pre-push gate; where another tool owns the pre-push hook, init prints the one line to add to it instead.)

  1. 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"

More: okl seed lists every bundled pack; /seed-from-docs has your agent propose cited records from the rules, ADRs, standards and specs you already wrote, and /seed-from-codebase from your own code. Both come with the Claude Code plugin or okl scaffold . (Seed it).

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

What a normal day looks like

You prompt as usual. 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. okl reverify re-runs each drifted lesson's stored check after you confirm. 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 AI 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 just wasn't in front of whoever needed it, at the moment they needed it.

okl fixes that with one move: the relevant lessons are read automatically at the start of a task, not looked up if someone remembers to. You record a lesson once; every future task that resembles it gets the lesson injected before the first line of code is written.

It works for a single repo on day one, and across many repos when you point them at a shared instance — so a lesson learned in one project protects the next one.

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

A store of your engineering rules, and the machinery that keeps them true.

Two things ship in the package. They are not coequal:

The knowledge layer is the product. Typed records (rules, architecture decisions, known defects, gates, tombstones, retractions) that live outside any one repo, get retrieved 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)"

okl scaffold is a starter kit for the in-repo discipline the store assumes: a lean canon file, mechanical gates, registries, a review agent, and an eval harness. It is useful on its own and it has never been measured. Use it to get a new repo to the state where a shared store has something to attach to.

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:

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.

Knowledge rots in a specific way: the code changes and everything written about the code silently stops being true. Each row below catches a different version of that, and it is worth knowing which one catches what, because they do not overlap.

This is not a novel idea, and you should know that before reading further. Agent memory is one of the most crowded categories in the field: mem0, Zep, Letta, and Cognee on the infrastructure side, with enterprise knowledge graphs such as Utopia beside them; Cursor Memories and Devin Knowledge built into the coding agents; AGENTS.md / CLAUDE.md / rules files as the convention standard everyone already uses; and the research literature (e.g. Codified Context, arXiv 2602.20478) arriving at tiered knowledge + retrieval independently. "Give the agent your team's knowledge" is the consensus position of 2026, not an insight.

So why build it anyway? Three honest reasons:

Read against the Claude Code memory plugins (claude-mem, agentmemory, ECC, beads — their source, September 2026): they are ahead on capture, retrieval engineering, install polish and reach across agents, and okl is not trying to catch them there. None re-checks that a memory is still true, ties one to the code it describes, or measures whether memory improves outcomes — claude-mem's "~10x" is a 5-query code-search benchmark, agentmemory's evals are retrieval-only. Their capture also costs model calls (claude-mem runs a model per tool

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →