okl — Observed Knowledge Ledger

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%。 ストアがすでに把握していた不具合を誘発するよう設計された 8 つのタスクでは、 ブリーフィングなしの試行 163 回中 68 回で不具合が繰り返されたのに対し、ブリーフィングありでは 164 回中 11 回でした。 異なるモデルを判定と生成に用いた 7 回の A/B 実行を合算した結果です（詳細な記録、§5 調査結果 7）。 サンプル数は少なく、誘導的なタスクでの一発限りのコード生成です。この結果が示すこと、示さないことをご覧ください。

## 何が問題になり、何がそれを検知するのか

状況	okl の動作
エージェントが、すでに代償を払った不具合を繰り返そうとしている	タスクの言葉に基づいて選ばれた教訓を、タスクの前にブリーフィングで提示します
最後のチェック後に、教訓の対象となるコードが変更された	okl drift が赤になり、チェックに再び合格するか、コードが合格時の状態に戻るまで、プッシュ前フックがプッシュを止めます（または CI が失敗します）。次のブリーフィングでは、その教訓に STALE と表示されます
教訓が誤りだと判明した	okl retire --reason で教訓を残したまま、AVOID としてブリーフィングします。誰もその教訓を言い直さないようにします。削除はされません
教訓が置き換えられた	okl retire --by <new-id> を実行します。ブリーフィングで置き換え先を示します
ストアに接続できない	Claude Code フックがプロンプトをブロックし、理由を伝えます。MCP ツールはブリーフィングされていないことを伝えます。「適用されるルールはありません」と誤って表示することはありません
セッション中にファイルが変更されたのに、何も記録されなかった	Stop フックが一度だけ、何を学んだかを尋ね、セッションで触れた教訓を示します

クイックスタート

初めての方へ。docs/GETTING-STARTED.md では、セットアップと機能の構築に合わせて教訓を追加する習慣について説明しています。すでに CLAUDE.md、ADR、標準または仕様をお持ちですか？ ルールを読み込む では、それらを読み込み、重要なものを検証し、最新の状態に保つ方法を紹介しています。

1. CLI をインストールします。 Python 3.11 以降（0.8.9 は 3.10 向けの最終リリース）、ドリフト検出には git が必要です。 macOS と Linux に対応しています。Windows は未テストです （#85。¹

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

2. リポジトリを設定します。ルートから実行します。

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 はスタック（*.csproj、package.json、pyproject.toml など）を検出し、それに基づいてリポジトリの関心分野を設定します。また、ほぼすべてのコードベースで役立つスターター教訓 20 件と、スタックに対応する同梱パックをストアに追加するため、最初のプロンプトからブリーフィングされます（--interests で独自のテーマを選べます。--no-seed を指定するとストアは空のままになります）。リポジトリに .claude/ ディレクトリがある場合、または PATH 上に claude がある場合は Claude Code を設定します（--claude／--no-claude）。教訓にドリフトがある場合にのみプッシュをブロックするプッシュ前フックをインストールします（--no-git-hook でスキップできます。代わりに GitHub ワークフローをインストールするには --ci を指定し、両方をインストールするには --ci --git-hook を指定します）。どちらの選択も記憶されます。書き込まれるすべてのパスと、それぞれの用途については、 What okl init writes をご覧ください。

3. 独自のルールを追加します。 スターター教訓は汎用的なものです。役立つのは、あなたのコードベースだけが知っていることです。エージェントに「このリポジトリの okl ルールを記録して。検索はサインイン中の顧客に限定する。対象は app/orders.py」と伝えると、okl の okl_record MCP ツールを使って教訓を記録します（Claude Code では、/record が下書きを作成して、先に確認を求めます）。 その仕組みは、次のように自分で実行することもできる CLI 呼び出しです。

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"

次に、検証します。okl verify order-owner-scope --run "pytest -q tests/test_orders.py" --expect passed を実行します。すでに作成したルール、ADR、仕様、および同梱パックの読み込みについては、 シードデータを追加するをご覧ください。

4. 動作を確認します。

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

エージェントと機能の対応

	Claude Code	あらゆる MCP エージェント（Cursor、Codex、Copilot …）	あらゆるエージェント、またはエージェントなし
各タスクの前のブリーフィング	すべてのプロンプトで自動実行されるフック。失敗時は処理を止めます	エージェントが呼び出したときに使う okl_check ツール	ターミナルまたはスクリプトで実行する okl check
学んだことの記録	ファイルを変更したセッションごとに一度だけ尋ねる Stop フック	okl_record ツール	okl record
検証とドリフト	okl verify、okl reverify、okl drift	同じコマンド	同じコマンド
ゲート	プッシュ前フック	プッシュ前フック	プッシュ前フック、または CI ワークフロー（okl init --ci）

フックは Claude Code の機能です。それ以外はすべてコマンドまたは MCP ツールで、どこでも動作します。 別のエージェントを設定する方法については、Getting startedをご覧ください。

普段の作業の流れ

• いつもどおりプロンプトを入力します。 タスク開始前のフックが、入力内容に対して okl check を実行し、開始前に関連する教訓をエージェントのコンテキストに追加します。また、動作を確認できるように、okl · briefed 9 lesson(s): … と1行表示します（OKL_QUIET=1 を設定すると非表示になります）。
• 残しておく価値のあることを学んだとき — 判断、エージェントが破った規約、自分で修正したバグなど — その旨を伝えると、エージェントが適用対象のファイルとともに記録します（okl_record または okl record）。Claude Code では、ファイルに変更があったセッションの終了時に Stop フックも一度だけ質問します。何を学んだかを尋ね、セッション開始時に提示した教訓と、変更したファイルに適用される教訓を示すことで、エージェントが教訓の修正または廃止を提案できるようにします（承認するのはユーザーです）。
• 別のエージェントを使う場合 MCP ツールであるブリーフィングと記録の機能（okl mcp）を登録し、AGENTS.md に次の1行を追加します。各タスクの前に okl_check を呼び出す。これを自動で行うフックは Claude Code 用です。はじめにを参照してください。
• 教訓を修正する必要があるときは、 ブリーフィングからその [id] を取得し、誤っている箇所だけを変更します。okl update <id> --fix "..."（または okl_update ツール）を使うと、適用対象の --files を変更しない限り、証拠を含めて残りの内容は保持されます。変更した場合は再検証が必要になり、okl reverify で保存済みのチェックを再実行します。okl show <id> は教訓全体と、そのチェックの成功・失敗回数を表示します。okl verify と okl reverify の実行結果はすべて保持されるため、変更を検出したチェックの記録も残ります。既存の ID を再度記録することは拒否されます。以前は教訓が置き換えられ、証拠が消去されていたためです。
• 教訓が誤っている、または置き換えられた場合は、 理由を添えて廃止します。削除されることはありません。okl retire <id> --reason "..." を使うと、誤った教訓は AVOID としてブリーフィングに残り、誰もその内容を再び提示しないようにします。--by <new-id> を指定すると、置き換えられた教訓はブリーフィングから外され、代わりに新しい教訓が参照されます。対象となる事柄自体がなくなった教訓には --obsolete を使います。修正済みの不具合は廃止しません。再発を防ぐため、引き続きブリーフィングに残します。
• 教訓が正しいことの証明は、 設定するフラグではなく、実行するチェックです。 okl verify <id> --run "pytest -q tests/test_orders.py" --expect "passed"。
• 教訓が適用されるコードに変更があったときは、 チェックが再び成功するか、チェックに成功した時点の状態にコードを戻すまで、okl drift は赤になります（--files を指定して記録した教訓は、最初の okl verify が実行されるまで赤になります）。ブリーフィングにもその旨が示されます。変更されたファイルとともに教訓が STALE（または UNVERIFIED、UNPROVEN）と表示されるため、エージェントは盲目的に信頼せず、コードに照らして確認します。確認後、okl reverify でドリフトした各教訓の保存済みチェックを再実行します。GitHub ワークフロー（okl init --ci）では、CI はコミット済みのスナップショット okl-drift.json を読み取ります。このファイルは、--files を指定した教訓が初めて検証されたときに okl verify が作成し、その後は最新の状態に保ちます。検証するコード変更の後に、これをコミットしてください。それまでは CI が「Drift not checked」と警告しますが、これは想定どおりです。ワークフローを使わない場合、すでにスナップショットがコミットされていない限り、okl verify はスナップショットを書き込みません。
• ヘッドレス実行（claude -p、スクリプト、CI エージェント）では、OKL_DISABLED_HOOKS=encode を設定します。設定しないと、セッション終了時の質問によって、表示された回答が置き換えられます。

解決する問題

チームやエージェントが微妙なバグを修正し、原因を突き止め、再発を防ぐルールを書きます。数週間後、別のファイルや別のリポジトリで、同じ種類のバグが再発します。新しい作業をする人やエージェントが、そのルールを目にしていなかったからです。知識は存在していましたが、それを必要とする人が必要とするタイミングで手元にありませんでした。そして、目にした場合でも、内容が古くなっていることがよくありました。説明しているコードが変わっていたのです。

okl はこの両方を解決します。関連する教訓は、誰かが思い出したときに検索するのではなく、タスクの開始時に自動的に読み込まれます。また、教訓は正しさが保たれるか、古くなったことがはっきりわかるかのどちらかです。各教訓は選択したチェックによって検証され、対象のコードが変更されると再確認されます。

これは v0 のスターターであり、本番環境向けに強化されたものではありません。 エンドツーエンドのテストスイートが付属します（pytest -q を実行すると、お使いの環境でスイートとその結果が表示されます）。コアは標準ライブラリのみで動作し、必須の依存関係はありません。

okl とは

エンジニアリングの教訓を蓄積し、その正しさを保つ仕組みです。 型付きレコード（ルール、アーキテクチャ上の決定、既知の欠陥、ゲート、トゥームストーン、撤回）が、タスクの前にエージェントのコンテキストへブリーフィングされ、説明対象のコードが変更されると、古くなったことがはっきりわかります。これを測定する指標はすべて、evals/REPORT.md にあります。

そのストアに何が蓄積されるのかを正確に捉えておくことが大切です。「コードベースが学んだ教訓」というと、バグデータベースを想像しがちです。しかし、seed/ の183件のレコードでは、実際にはそうではありません。ルールが110件、決定が20件、ゲートが7件で、欠陥は36件です。つまり、壊れたものの記録ではなく、コードが従う規約や、すでに決着したトレードオフが中心です。自分で数えてみてください。

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

パッケージには、もう1つオプションの機能が付属しています。okl scaffold は、ストアが前提とするリポジトリ内の規律を整えるためのスターターキットです（簡潔なルールファイル、機械的なゲート、レビュ��エージェント、評価ハーネス）。効果測定は一度も行われていません。新しいリポジトリを、ストアが紐付けられる状態にするために使ってください。

okl の対象外

okl が蓄積するのは教訓です。エージェントが目にすること、または行うこと（症状）、代わりにすべきこと（修正）、その理由、そしてそれを検証できる場所（チェック）です。適切なエージェント環境を構成するものの大半は別のものであり、別の場所に置くほうがうまく機能します。

それが…の場合	置き場所	okl が適さない理由
タスクを問わず、毎回のセッションで必要なルール	CLAUDE.md / AGENTS.md	これらは毎回すべて読み込まれます。ブリーフィングではタスクごとに教訓を選びます
リリース、移行、セットアップの方法などの手順	スキル、ランブック、またはスクリプト	手順は全体を順番に読みます。ブリーフィングでは短いレコードをいくつか渡します
コマンドや、「X の場合は Y を読む」というポインター	CLAUDE.md / AGENTS.md、またはスキル	これは関連するタスクのたびにエージェントが必要とする案内図です
フォーマットやコードスタイル	フォーマッターまたはリンター	ツールならすべての行に対して強制できますが、教訓は注意を促すことしかできません
まだ未解決のバグ	イシュートラッカー	未解決の作業はトラッカーが管理します。okl は修正後に得られた知識を蓄積します
シークレット、認証情報、個人データ	okl の近くには置かない	ストアは共有され、教訓はエージェントのコンテキストにコピーされます

症状と修正があるものはすべて、ここに当てはまります。コードが従う規約、意図的に行った決定、すでに対応コストを払った欠陥の種類などです。スタートガイドでは、記録する側から見た同じ使い分けを説明しています。

何がどのように陳腐化を防ぐのか

知識は特定の形で陳腐化します。コードが変わると、そのコードについて書かれた内容がいつの間にか事実ではなくなります。以下の各行は、それぞれ異なる形の陳腐化を検出します。どれが何を検出するのかを把握しておく価値があります。それぞれの検出範囲は重複しません。

陳腐化の種類	検出するもの	仕組み	検出条件
ルールと、そのルールが適用されるコードとの不一致	okl drift --gate	レコードは適用対象のパスの glob を宣言し、okl verify はチェックに合格したコミットを記録します	そのファイルが記録されたコミットと HEAD の間で変更されている場合（記録されたコミットがない検証、またはこのクローンに存在しないコミットでの検証では、代わりにコミット時刻を比較します）、またはルールが一度も検証されておらず、新しい --files ルールが最初の okl verify まで失敗扱いになる場合、またはスタンプの根拠となる観測済みのチェックがない場合
廃止された識別子が文章中に再び現れること	check-tombstones.sh	作業ツリーのソース、ドキュメント、コメント、設定を grep して、廃止済みの名前をすべて検索します	許可リストにないものが見つかった場合
撤回された主張が再び記述されること	check-retractions.sh	作業ツリー内の Markdown を grep して、撤回レジストリにある引用済みの主張と完全一致する箇所を探します	レジストリ以外の場所に引用文が現れた場合
どこからもリンクされていないドキュメント	check-doc-orphans.sh	トップレベルの docs/ 内の各ドキュメントまたは画像が、ハブファイルか docs/*.md のいずれか（推移的ではなく、1 ホップ）に記載されているかを確認します	どこにも記載されておらず、読まれないまま陳腐化する場合
移動済みファイルを指すリンク	check-links.sh	git ls-files が列挙したすべての Markdown ファイルを読み込み、各ローカルリンクのリンク先が作業ツリーに存在するか確認します	リンク先が存在しない場合
レンダリング画像のない図のソース	check-diagram-pairs.sh	編集可能な各ソースとその書き出し画像を対応付けます。OKL_DIAGRAM_SRC_EXT／OUT_EXT によって形式に依存しません	レビュー担当者に何も表示されない場合です。ソースのない手作業の画像は記録されますが、失敗にはなりません。また、図のソースがないリポジトリでは何もせず正常終了します
検証がいつの間にか古くなること	TTL + verified_by	レコードには、最後に検証された日時と、検証を行った観測済みチェックが記録されます。TTL は --ttl-days を指定したレコードにのみ適用されます（デフォルトでは適用されません）	TTL を過ぎると、レコードは削除されず、降格された状態で表示されます

この表には、正直に認めるべき限界が 3 つあります。

• 図の 内容 の確認は、今も人の作業です。 check-diagram-pairs.sh はレンダリング画像が存在することを確認しますが、その画像が書き出し元のソースと一致することも、どちらかがコードと一致することも検証しません。その場合は、図を説明対象のコードと一緒にレコードの --files に指定してください。そうすれば、コードを変更するとドリフトゲートが失敗になり、誰かが図を再検証するまでその状態が続きます。このリポジトリでは README をその方法で管理しています。一方、パイプライン図はコードから生成され、コミット済みのレンダリング画像が一致しなくなるとテストが失敗します。
• コメントを対象にするのは tombstone ゲートだけです。 .md、.py、.ts、.tsx、.cs、.yaml、.yml、.json、.sh ファイル内の廃止された名前を検出します。retraction ゲートが読み込むのは Markdown のみです。それ以外の古いコメントは検出されません。また、okl reverify はコメントを読まずに、適用対象のファイルに再度スタンプを付けるため、コメントが述べる主張をチェックで検証しなければ、陳腐化の検出には役立ちません。
• okl drift が監視するのは、レコードが対象として宣言したものだけです。 どのレコードにも適用されないファイルは、何によっても監視されません。対象範囲をどこまでにするかは整理・選定の判断であり、何かが壊れるまでその漏れは見えません。だからこそ、上記の機械的なゲートは登録済みのものだけでなく、リポジトリ全体をスキャンします（tombstone と retraction の各ゲートは作業ツリーを grep します）。

okl との違い

• メモリレイヤー（mem0、Zep、Letta、Claude Code のメモリプラグイン）との違い：メモリレイヤーはエージェントが経験したことを思い出しますが、okl は守り続けなければならないことを保持し、選んだチェックでそれを証明します。
• ルールファイル（CLAUDE.md、AGENTS.md）との違い：ブリーフィングはタスクに合う少数の教訓を選びますが、ルールファイルは毎回すべて読み込まれ、再チェックされることはありません。
• 指示ファイルのリンターとの違い：ルールファイルに記載されたパスやコマンドが今も存在するかを確認しますが、okl は指定したチェックを実行し、コードが変更されていればプッシュをブロックします。
• ドキュメントプラットフォームとの違い：ドキュメントプラットフォームは作成とレビューを行いますが、okl は何も作成せず、プッシュをブロックします。

	最適な用途	トレードオフ
ルールファイル	すべてのセッションで必要な5つのルール	すべて読み込まれ、証明はなく、タスクごとの選択もありません
メモリレイヤー	エージェントが見てきたことの想起	使用時のモデルの判断に依存し、チェックやプッシュとは何も紐付いていません
okl	症状、修正、チェックを含む教訓	意図して自分で記述し、証明された状態を保ちます

比較表と、別のメモリツールと並行して okl を実行する方法を含む詳細版： この仕組みの位置づけ。設計上、フェイルクローズ方式です。ストアに到達できない場合はブロックするか警告し、「問題なし」とは報告しません。

2026年に研究文献で測定された内容を、論文から読み取った数値と各結果の横にある「okl の位置づけ」列とともに紹介します：関連研究。

測定された効果とその限界

条件を固定した A/B テスト（作成したタスク 8 件、各実行の各群 3 サンプル。生成モデルとブラインド判定モデルは別。手法と生の記録は evals/REPORT.md を参照）：

• 同じモデルで、ブリーフィングありとなしを比較：最初の 3 サンプル実行（2026-08-30）では、欠陥の再現率が 33% → 4%（sonnet）、38% → 12%（haiku）に低下しました。検索パイプラインの変更後の sonnet の実行では、35–50% → 4–8% でした（REPORT §4b–§4i。取り消された §4d と opus で判定した §4f を除く。最新の §4i は 43% → 8%）。§4 から §4h までのこの測定方法による 7 回の実行を、取り消された §4d を含めてまとめると、**ブリーフィングなしでは 163 回中 68 回の試行で既知の欠陥が再発（42%）したのに対し、ブリーフィングありでは 164 回中 11 回（7%）**でした。REPORT の §5 の所見 7 では、この記録と、発生率を下げるその他の方法を挙げています。ブリーフィングなしの群だけでも、何も変更していないのに実行間で 21 ポイント、§4j の境界をまたいで 26 ポイント変動しているため、ノイズフロアは少なくとも 21 ポイントです（§2b、§4m）。「再現」とされたものはすべて、このストアがすでに学習のためにコストを払った欠陥クラスです。たとえば、価格改ざん時のフォールバック、Web ストレージへのトークン保存、ピン留めされていない CI ゲート、出力を確認せず終了コード 0 を信頼するスクリプト、失敗率を先頭に表示しない評価サマリーなどであり、Lint のノイズではありません。2 件のタスク（IDOR エンドポイント、React の fetch）は、コミット済みの記録でブリーフィングなしでは一度も再現されていません（各 46～48 サンプル）。そのため、減少を示すことはできません。レートリミッターは、ブリーフィングなしでは 41 回中 1 回再現され（§4m）、ありでは 44 回中 2 回再現されました（REPORT §4d、§4m、§5 の所見 6）。
• 最初の実行から覚えておくべき結果は、ブリーフィングありの haiku（12%）が、ブリーフィングなしの sonnet（33%）を上回ったことです。これは、ブリーフィングが品質だけでなくコストにも働きかける手段であることを示唆します。組織で既知の失敗モードに関しては、より安価なモデルを、フロンティアモデルのブリーフィングなしの下限より高い水準に保てる可能性があります。ただし、2 点の留保があります。haiku の実行は再実施されておらず、sonnet の実行が haiku で判定されたのに対して、haiku の実行は sonnet で判定されました。
• 上記のすべての実行は、ブリーフィングに Decisions セクションが追加される前のものです。最近まで、枠を獲得した Decision は何も通知されずに除外されていましたが、現在は独立した見出しの下に表示されます。評価タスクのブリーフィングに Decision が含まれていたものはないため、測定した 8 件のブリーフィングは、どちらの場合もバイト単位で同一です。
• 上記のすべての実行は、ブリーフィングに含まれる各学びに [id] が付くようになる前のものでもあります。こちらはバイト単位で同一ではありません。8 件の評価ブリーフィングは 5% 大きくなりましたが、各学びの内容はすべて維持されています（REPORT §4j）。この条件での実行（2026-10-10）は 17% → 0% でしたが、ブリーフィングなしの群自体が §4i から 26 ポイント低下しており、原因は okl ではなく生成モデルにあることが示唆されます。そのため、この実行は新たな系列の開始点とし、上記の実行にはまとめていません。

この数字は、転移に関する結果でもあります。8 件のタスクはタスクのプロンプトから新たに作成したコードであり、そこで誘発される欠陥クラスは別のプロジェクトで学習されたものです。各タスクは evals/tasks.jsonl で対応する学びを示しており、それらの学びは 12 個のシードパックのうち 6 個から提供されています。あるプロジェクトでコストをかけて得た学びが、別のプロジェクト向けに書かれたコードで欠陥を防ぎました。まとめた実行では、ブリーフィングに各タスクの学びが含まれていましたが、例外が 3 件あり、その群の結果は学びがない場合のブリーフィングを測定しています。exit_code_trust の学びは、2026-10-22 に症状が追加されるまで、すべての実行で上位 12 件のカットオフに届きませんでした（REPORT §4b、§4o）。rate_limiter の学びは、取り消された §4d の実行で除外されました。また、react_fetch の学びは、このリポジトリで宣言された関心事項を使った 2 回の実行（§4h）で除外されました。これを組織全体で実行することと、学びに求められることについては、組織全体での適用 を参照してください。

この結果が示していないこと：タスクは、ストアに記録された欠陥クラスを誘発するように作成されているため、直接関連する学びがある場合にブリーフィングが何をもたらすかを測定したものであり、一般的なコード品質や大規模な検索を測定したものではありません。n は小さいため、ベンチマークではなく、記録を伴うパイロットとして扱ってください。

仕組み

上部の概要は docs/overview/okl-overview.htmlからレンダリングされます。以下の仕組みの説明では、okl 自身の出力を使って、1 つのレッスンを最初から最後まで追います。これは docs/overview/okl-anatomy.htmlからレンダリングされ、 docs/overview/anatomy-story.shを実行すると、使い捨てのリポジトリで同じ流れを確認できます。

概要は実際にどのように作られるか

okl checkは検索パイプラインです。タスクの主題語を検索し、コーパス全体を、エージェントが全文を読む 5 件以下のレコードに絞り込み、一致した残りの項目もそれぞれ 1 行で示します。主題との関連性を理由にレコードを除外する段階は 2 つありますが、それを許されているのは一方だけです。このプロジェクトが一度誤り、測定を通じて修正した違いです（REPORT §4d）。

次に判定を行います。タイトル、症状、別名、トリガーにタスクの主題語が 3 語含まれるか、あるいは 1 件のレコードにしかない語と同程度に珍しい語が 2 語含まれる場合に限り、そのレコードの概要を伝えます。トリガーはレッスンを記録するときに記述する、そのレッスンが適用される場面の言い回しです。この基準は、固有の主題を持たない実際のプロンプト 282 件を使って設定しました。そのようなプロンプトの約 20 件に 1 件だけが何らかの情報を受け取り、基準を通過するレコードは最大 5 件です。一致したほかの項目も隠されません。5 件を超えて基準を通過した項目と、先行する語数の下限によって残った項目は、それぞれ 1 行で表示されます（ID、タイトル、修正内容の冒頭。最大 12 件）。そのため、エージェントはokl show <id>でどれでも読めます（REPORT §4y）。

この判断は、決定のために構築したベンチマークで測定しました。生成クエリ 519 件、固有の主題を持たない実際のプロンプト 550 件を使い、選択を文書化した後に、保留していた半分を 1 回実行しました。以前のパイプラインとの比較は次のとおりです。

	以前のパイプライン	トリガーを含む基準
保留データの再現率	74.4%	90.0%
クエリあたりのレッスン数	11.8	4.7
主題のないプロンプトのうち概要が伝えられたもの	268 件中 149 件	268 件中 9 件

実際のプロンプトは、ベンチマークのクエリより簡潔です。人が入力したプロンプトを、記録済みレッスンのストアに対して使った場合（REPORT §4x）、この基準だけでは、適用対象となるレッスンの約 3 分の 1 しか見つけられず、以前のルールを下回りました。そのため、デフォルトでは残りもそれぞれ 1 行で示します（REPORT §4y、保留データ）：

実際のプロンプト、実際のストア、ホールドアウト	従来のルール（下限）	ラインのみ	デフォルト：2段階
適用されたレッスン数（115件中）	90	38	102（38件は全文、64件は1行）
プロンプトごとに全文表示されたレッスン数	7.7	1.8	1.8、さらに1行で7.6件
全文表示されたレッスンのうち、適用される割合	9.8%	17.8%	17.8%
ブリーフィングの中央値（トークン）	1,424	113	721

チーム独自のレッスンを最初の段階に到達させるには、トリガーが必要です。okl record はトリガーの入力を求め、okl triggers はトリガーがないレッスンを一覧表示し、/triggers は Claude Code でトリガーの草案を作成します。根拠、採用されなかった代替案（再ランキング、グラフ、クエリ時生成、会話コンテキスト）、およびそのコストについては、docs/RETRIEVAL.md、REPORT §4w、§4x、§4y をご覧ください。 --decision calibrated は最小のブリーフィングであるラインのみを返します。--decision floor は従来のルール（共通する主題語が2つ、すべての一致項目を全文表示、最大12件）を返します。

オプションのセマンティックアームを有効にすると（okl check --hybrid --decision floor）、ゲートの前に2つ目の候補ソースが加わります。タスク全体を1つのベクトルとして扱い、コサイン類似度で最も近いレコードを取得し、2つの順位を統合します。これには下限が必要です。意味だけで見つかったレコードはタスクと共通する語がないため、調整済みラインではブリーフィングに含められません。評価では、意味情報を語数に加える方法が最も良い結果を示しました。その方法では EmbeddingGemma-300m により、ホールドアウトの再現率が90.0%から95.2%に上がりましたが、プロンプトフックではプロンプトごとにモデルの読み込みに約2秒かかるため、モデルを読み込んだ状態に保つプロセスが用意されるまで保留しています（REPORT §4w）。同じジェネレーターが同じコードパスからこの機能を呼び出し、REPORT §4q では得られる効果とコストを説明しています。候補を対象とするローカルのクロスエンコーダー（okl check --rerank）も次に評価しました（REPORT §4t）。ホールドアウトの言い換えを1つ入力してバグレポートを1つ出力するため、フラグとして提供し、デフォルトでは無効にしています。

図中のすべての件数は、転記したものではなくトレースされたものです。docs/render_pipeline_diagram.py は、seed/ から初期データを投入したストアに対して、実際の briefing_terms、store.search、core._in_scope、core._live_hits、decide.select を実行します。test_pipeline_diagram_is_current は、コミット済みの図が現在ジェネレーターによって生成される内容と異なる場合に失敗します。BM25 の重みやフィルターの述語を変更すると、図もその変更を反映して赤くなります。以前は okl check が主題語方式に移行した後も、ジェネレーターが元の文全体を検索しており、そのテストでは気付けませんでした。現在はトレースを _live_hits と照合して検証します。

教訓とリンク

教訓には、次のいくつかの種類があります。

種類	記録する内容
Defect	実際に起きた特定のバグやミスと、その理由です。
Gate	ある種類の不具合を検出する自動チェックです。
Rule	従うべき標準（「X を行い、Y は決して行わない」）です。
Retraction	誤りだと判明し、撤回された主張です。
Tombstone	廃止され、再び使ってはならない識別子（名前、ファイル、エンドポイント）です。
Decision	意図的に下された選択で、後から気付かないうちに覆されないようにするものです。

それぞれに 症状 → 原因 → 修正 があります。「この状況を見たら、原因はこれです。こう対処してください」という形です。 これにより、教訓は単なる情報ではなく、実際の行動につながります。教訓同士はリンクされています。Gate は Defect を CATCHES し、Decision は以前の決定を SUPERSEDES します。そのため、検索すると関連するコンテキストも取得できます。

2 つのアクション。 check ではタスクを説明します。okl はストアを検索し、対象範囲内の教訓を残して順位付けし、具体的なアクション（FIX: … この状況を見たら … → …）を先頭に、その後に意図的に下された決定を続けるブリーフィングを返します。record では、何かを修正したり決定したりしたときに、適用対象のファイルとともに記録します。それ以降、似たタスクにはその教訓がブリーフィングされ、okl update <id> で根拠を失うことなく内容を改良できます。

スコープは、最も重要な決定です。repo:<name> はそのプロジェクト内にとどまります。org は、そのパックを読み込むすべてのプロジェクトに適用されますが、applies_to、プロジェクトの関心事、タスクが一致する場合にのみブリーフィングされます。限定された語彙（store.py の KNOWN_TAGS。okl record --type Vocabulary で追加）から選ぶ主題タグは、教訓の内容を示します。okl init --interests はリポジトリが重視する内容を示します（決定）。台帳リポジトリとプルリクエストを通じて、多数のリポジトリに org の教訓を含むパックを配布し、各リポジトリが読み込む内容を証明する方法については、組織全体での運用をご覧ください。

これらすべての選択の背景とその理由については、docs/DESIGN-CHOICES.mdをご覧ください。

データは、デフォルトではクローンごとに 1 つの SQLite ファイル .okl/okl.db に保存され、gitignore の対象です。1 つのストアを共有したい場合は、複数のリポジトリを共有サービスに接続できます（docs/SCAFFOLD.md）。

使い方

# 1. READ the relevant lessons before starting a task (the load-bearing move)
okl check --task "add an endpoint that returns an order for the logged-in user"
#   add --format actions --limit 3 for a ~350-token version (subagents, CI)

# 2. RECORD a lesson after you learn it, with an actionable symptom/cause/fix
okl record --type Defect --scope org --tags "security" \
  --title  "Trusting a client-supplied price lets the client set it to anything" \
  --symptom "a request body carries a price/amount/status/isAdmin field" \
  --body    "cause: the handler saved the client's value instead of computing it" \
  --fix     "drop those fields from the request; compute them server-side" \
  --files   "**/orders/*.py"         # prints the new record's id

# ...then prove it with a check, rather than asserting it
okl verify <id> --run "pytest -q tests/test_orders.py" --expect "passed"

# 3. SEARCH the stored lessons directly
okl search "price tampering"

# 4. LINK a check to the defect it catches (so a lookup pulls in both)
okl link <gate_id> CATCHES <defect_id>

okl record --verified は拒否されます。終了コード 2 で終了し、okl verify を案内します。スタンプは実行の証拠であり、主張ではないためです。終了コードを含むその他すべてのコマンドについては、docs/COMMANDS.mdをご覧ください。 あるステップが自らを評価することがない理由と、okl が自身のスタンプに適用する 4 段階については、docs/VERIFICATION.mdをご覧ください。

--symptom／--fix を指定すると、check は長文の説明ではなく、先頭に 「これを実行」 のアクション一覧（「FIX: … — 次の状況を見たら: …」）を出力します。--files を指定すると、教訓が適用されるソースファイルを okl に伝えることができ、これによってドリフト検出が機能します（下記）。

コスト

okl のインストールは無料ではありません。すべてのプロンプトに組み込む前に、何を導入することになるのかを正確に把握しておく価値があります。以下の数値はすべて推定ではなく実測値です。代表的なタスク（「ログイン中のユーザーの注文を返すエンドポイントを追加する」、トークン数 ≈ 文字数 ÷ 4）を使用しています。サイズは、同梱されているすべてのシードパックを含む新しいストアの 183 件のレコードから算出しました（python3 evals/briefing_size.py、計測結果は evals/results/briefing-size-20261027-0132.json）。レイテンシは、それ以前に同梱されていた 161 件のシードレコードを基にしています。 お使いのストアやタスクによって結果は異なります。

フックのインストール後、プロンプトごとのコスト：

レイテンシ	okl check プロセス全体で約0.1秒（ウォーム実行時の中央値は0.07秒）です。ローカルモードではローカルの SQLite クエリが1回実行され、ネットワーク通信はありません
コンテキスト	代表的なタスク1件で、デフォルトでは約1,390トークンです（5件のレッスンを全文で、12件の名前を1行で表示します。--decision calibrated では約730、--decision floor では約1,730です）。実際のプロンプトでは中央値が約720です（REPORT §4y）。--limit 3 でアクションリストのみ表示すると約350まで減ります

セッションごと： Stop フックはセッションの最後に一度だけ中断し、何を学んだかを尋ねます。最初の停止時のみブロックされ、この質問への回答がループにおける書き込み処理のすべてです。質問とともに、セッション中に失敗したコマンドを最大5件表示します。これらはセッション自身のトランスクリプトから読み取られた候補であり、記録ではありません。すべてのツール呼び出しでフックが実行されるわけではなく、要約のためにモデルが呼び出されることもありません。続いて okl recap は、セッションが触れたレッスンを表示します。最も頻繁に説明されたものから最大5件と、管理対象のファイルが変更されたものから最大5件が、それぞれ修正、廃止、または再証明するコマンドとともに表示されます。エージェントが1行で変更案を提示し、同意すれば一度だけ適用します。後からセッション全体を振り返るには、okl recap --report を実行します。ストア独自のログから、説明した内容、記録・廃止したレッスン、実行・失敗したチェック、コミット、そして現在古くなっている項目が一覧表示されます。

上記の測定では、完全なブリーフィングのコストは約1,390トークンです（1行のみなら約730、floor の12件では約1,730）。大きなウィンドウを持つメインセッションなら問題なく、数千トークンしか扱えないサブエージェントにとっても実質的な量です。この非対称性が重要なのは、組織のルールが失われやすいのがまさにサブエージェントだからです。1つのサブタスクに集中する作業者は、コンテキストが最も少なく、「このコードベースがすでに犯した間違い」が最も必要です。

同梱されているすべてのシードパック（183件の記録）で測定した代表的なタスク1件（測定結果）では、アクションリストのみの場合、--limit 3 で約350トークン、--limit 5 で約580トークン、--limit 12 で約1,010トークンです（1行の項目数は limit に従います）。完全なブリーフィングは約1,390トークンです。サブタスクごとに呼び出すにも十分低コストで、--decision calibrated を指定すると、最小のリストでは1行の項目が省かれます。

コンテキストウィンドウが小さいモデルでメインセッションを実行する場合も同様です。この場合、ブリーフィングは各プロンプトとともに届きます。OKL_BRIEFING_COMPACT=1 を設定すると、プロンプトフックはアクションリストのみを送信します（okl check --compact）。OKL_BRIEFING_LIMIT=3 を設定すると、5件と12件ではなく、3件を表示してさらに3件の名前を示します。上記の測定では、両方を設定すると約1,390トークンから約350トークンに減ります。エージェントの起動時にこれらを設定してください。フックはエージェントの環境を引き継ぎます。0より大きい整数ではない limit は無視され、--compact に対応していない古い okl は、プロンプトをブロックせず完全なブリーフィングを表示します。--format actions と同様に、コンパクトなブリーフィングでは省略した記録の件数は示されません。

okl check --format actions は指示のみを表示し、サイズは約半分です。--format json はスクリプト向けの生の結果を返します。--format hook は Claude Code フックが出力する形式です。--limit N は対象レコードを減らし、省略した件数を示します。

すべての設定項目、okl init が書き込む内容、一部を無効にする方法、オプトイン方式のアーキテクチャレビューについては、コストと設定項目をご覧ください。サブエージェントと小さなウィンドウについては、docs/SUBAGENTS.mdをご覧ください。

質問

すでに修正したバグをエージェントが繰り返すのを防ぐにはどうすればよいですか？ 症状、修正方法、適用対象のファイルを含む教訓として記録し、根拠となるテストを使って okl verify します。同じ語句を含むタスクには、まずその教訓を共有します。対象のコードが変更された場合は、チェックに再び合格するまでプッシュを保留します。

教訓の対象コードが変更されるとどうなりますか？ okl drift が変更を一覧表示し、pre-push フックがプッシュを保留するか、CI が失敗します。次のブリーフィングでは、その教訓に STALE のマークが付きます。okl reverify は保存済みのチェックを再実行し、合格すると認証情報を更新します。コードを元の状態に戻しても解消されます。

Cursor、Codex、Copilotでも使えますか？ ストア、コマンド、プッシュゲート、6つのMCPツールは使えます。すべてのプロンプトに対するブリーフィングとセッション終了時の質問は、Claude Codeのフックです。ほかのエージェントでは okl_check を呼び出してください（方法）。

セッションは自動で記録されますか？ いいえ。教訓は、あなた自身が、またはあなたが指示したときにエージェントが意図的に記録します。Stopフックが一度だけ尋ねます。ツール呼び出しは記録されず、この処理の中でモデルが呼び出されることもありません。

claude-mem、mem0、その他のメモリツールと併用できますか？ はい。それぞれ異なるレイヤーです。okl doctor でインストール済みのものと、既知の3つの競合が確認できます（このツールの位置づけ）。

本番環境向けに堅牢化されていますか？ いいえ。v0で、個人プロジェクトです。エンドツーエンドのテストスイートと上記の測定結果があります。対象としていない用途と制限事項は、意図的に明記しています。

Claude Codeプラグインとしてインストールする

/plugin marketplace add emeraldleaf/okl
/plugin install okl@okl

プラグインには2つのフック、MCPツール、シード用コマンドが含まれます。okl本体は含まれないため、まず MCP追加機能付きで CLIをインストールしてください。プラグインは okl mcp サーバーを登録するためです（pipx install 'observed-knowledge-ledger[mcp]'）。次に、リポジトリで okl init を実行し、ストアとドリフトゲート（pre-pushフック。GitHubワークフローでは --ci）を設定します。プラグインが有効な場合、init はフックとMCPの登録をスキップします。二重に登録すると、すべてのプロンプトに対してブリーフィングが2回行われるためです。プラグインとプロジェクトのフックが両方とも有効なリポジトリは、okl doctor で報告されます。チェックアウトから1つのセッションだけプラグインを読み込むには、claude --plugin-dir <path> を実行します。

インストール

pipx install observed-knowledge-ledger   # provides the `okl` command
pip install -e .                   # or from a clone of this repo

コア（ローカル＋クライアント＋CLI）は 標準ライブラリのみ で動作し、必須の依存関係はありません。 追加機能は必要に応じて有効にできます。

pip install "observed-knowledge-ledger[service]"    # FastAPI shared service
pip install "observed-knowledge-ledger[postgres]"   # Postgres backend (psycopg)
pip install "observed-knowledge-ledger[mcp]"        # MCP server for Claude Code / Cursor / Copilot
pip install "observed-knowledge-ledger[all]"

エージェントとの統合（MCP）

pip install "observed-knowledge-ledger[mcp]"
okl mcp     # register in your coding agent's tool config

コーディングエージェントに6つのツールを提供します。okl_check（タスクの前に教訓を確認）、okl_record（新しい教訓を記録）、okl_update（証明を保持したまま、IDで教訓を更新）、okl_retire（理由を添えて教訓を取り下げる）、okl_get（教訓全体を1件取得）、okl_search です。設定済みの共有インスタンスに接続できない場合、okl_check は障害を明確に報告します。エージェントから見ると、「見つからなかった」と「接続できなかった」は同じに見えますが、安全なのは一方だけだからです。フックとは異なり、ツールの結果でエージェントの動作を止めることはできません。警告を出すことだけができます。

構成

src/okl/
  store.py        # the database: lesson + link schema, swappable SQLite/Postgres backend
  core.py         # check / record / search / link — the logic, independent of transport
  client.py       # resolves local-file vs. shared-service; fails closed
  cli/            # the `okl` command, one module per command group (cli/__init__.py maps them)
  drift.py        # source-vs-spec drift detection
  ownership.py    # okl-fingerprint lines: which installed files are okl's, and untouched
  coexist.py      # `okl doctor`: detects other agent-memory plugins and double wiring
  bootstrap.py    # propose starter lessons from a repo's git history + docs
  service.py      # the shared web service (the [service] extra)
  mcp_server.py   # coding-agent tools (the [mcp] extra)
  seed.py         # load a JSON seed file
  scaffold_cmd.py # the `okl scaffold` starter-files stamper
seed/             # starter lesson files (examples + genuinely useful defects)
docs/decisions/   # design decision records
tests/            # end-to-end tests

テスト

pip install -e . --group dev   # from a clone of this repo (pip 25.1+; or `uv sync`)
pytest -q                 # full suite

gitを利用できない場合（または git init がブロックされている場合）、あるいは service などの任意の追加機能がインストールされていない場合、一部のテストは失敗ではなくスキップされます。

ライセンス

MIT。

コントリビューション

セットアップ、リポジトリ独自のルール（ミラーファイル、ドリフト、証拠に基づく検証）、および特に支援が役立つ箇所については、CONTRIBUTING.md を参照してください。 docs/DEVELOPING.md では、日常的な作業サイクル、CI、プルリクエスト、リリース、評価、観測できる内容など、oklの開発プロセス全体を説明しています。 セキュリティポリシーとデプロイ時の脅威モデルについては、SECURITY.md を参照してください。

Footnotes

1. PyPI が okl を oki と紛らわしいとして拒否するため、PyPI 上の名前は異なります。それ以降に入力するものはすべて okl です。 ↩