kcp-agent — KCP navigation planner

kcp-agent

🧾 実行を見る — インタラクティブな KCP プレイグラウンド · 公開記事を読む

Knowledge Context Protocol のリファレンスエージェントです。

アリーナ → — 実際のプランナーを変更せずにそのままバンドルし、 ブラウザー上でライブ実行して、よく知られた競合相手と直接対決させます。世界で最も決定論的な エージェントです。すべての判断に根拠があります。

KCP は、エージェントがナレッジ内を移動できるよう、ナレッジが自身を宣言する方法を定義します。kcp-agent はそのもう半分、KCP を最初から最後まで利用するエージェントです。タスクと knowledge.yaml を与えると、検査可能なロード計画を生成します。どのユニットをどの順序で読み込むか、どれをスキップするかとその正確な理由、フェデレーション全体でサブマニフェストをどう選択するか、そして全体にかかるコストを示し、さらに任意で、それらのユニットだけを使ってタスクに回答します。

価値ある新規性の高い中核部分は、LLM を使わず、決定論的です。計画はアクション実行前の監査のための成果物です。「マニフェストがエージェントの知識に影響を与えることはあっても、行動に影響を与えることはない」という信頼できるレンダリングの原則を、エージェントのループ全体に拡張しています。モデルを呼び出すのは最後の統合ステップだけです。

discover → verify signature → trust-gate → score units by task → federate (context + agent_identity)
        → temporal filter → budget (payment + rate_limits) → emit load plan → [follow] → [answer]

インストール

npm install
npm run build

ネイティブ実行ファイル

CI では、Linux x64/arm64、macOS x64/arm64、Windows x64 向けに、自己完結型バイナリ（対象環境で Node/Deno は不要）をクロスコンパイルします。リリース、または任意の CI 実行にある kcp-agent-natives アーティファクトから取得できます。自分でビルドするには、次のようにします。

npm ci && npm run build
deno compile --allow-read --allow-env --allow-net --node-modules-dir=auto \
  --output kcp-agent dist/cli.js

使い方

plan — 検査可能なロード計画（API キー不要）

node dist/cli.js plan "how do I deploy to production?" --manifest ./path/to/knowledge.yaml --env prod

Plan for: "how do I deploy to production?"
  companyx-knowledge-hub v1.0.0 · kcp 0.24 · env prod

Trust: · no manifest attestation requirement

Load plan (2 units):
  ● 1. front-door (score 4)  overview.md  free
  ● 2. deploy-guide (score 3) docs/deploy.md  free

Budget: tier default
Federation:
  → platform-engineering  needs github_pat before fetch  [acquire github_pat]
  · platform-engineering-dev  context ["dev","test"] excludes env 'prod'
Skipped (2):
  · auth-guide: no task-relevance match

各ステージは仕様の各レイヤーに対応しています。クエリのスコアリング（§15）、時間的な有効性（§4.22）、エージェントのアテステーション（§3.2）、フェデレーションの context + agent_identity（§3.6）、支払い／レート制限（§4.14/§4.15）です。エージェントがアテステーションできない制限付きユニットは一覧に表示されますが、読み込み対象外としてマークされます。理由を添えてフェイルクローズします。

コンテキストウィンドウの予算設定。 モデルに入力するときに実際に不足しやすいリソースはトークンです。そのため、--context-budget <n> でトークンの上限を指定します。これは金額を指定する --budget と同じように機能します。スコアの高い順に処理し、上限を超えるユニットは理由に計算内容を示してスキップします（over context budget: 1,240 tokens would exceed remaining 800 of 4,000）。一方で、スコアは低くてもサイズの小さいユニットには、引き続き読み込まれる機会があります。プランナーは取得前のメタデータを使って動作するため（アクション実行前の監査）、ユニットのサイズには、宣言された size_tokens（正確な値）か bytes/4（推定値として明示）を使用します。どちらも宣言されていないユニットは読み込み対象になりますが、未計測として数えられます（予測値は下限です）。ただし、--strict を指定するとフェイルクローズで除外されます。--context-budget は --budget と併用でき、ユニットは両方の上限を満たす必要があります。

機械可読な計画

別のエージェントやインテグレーションが計画を読み込む場合は、--json を使用します。出力では、計画のフィールドをトップレベルに保持し、さらに次の項目を追加します。

{
  "schemaVersion": 1,
  "kind": "plan"
}

kind は plan、--follow を使用した場合は tree、--trace を使用した場合は trace です。人間向けの出力は互換性の保証対象ではありません。JSON コマンドが成功すると終了コード 0 を返します。プランナーまたはマニフェストのエラーが発生した場合は、診断を stderr に出力し、0 以外の終了コードを返します。

ask — 計画を作成し、Claude を介して回答

export ANTHROPIC_API_KEY=...        # or: ant auth login
node dist/cli.js ask "how does an agent get started here?" --manifest ./knowledge.yaml

ask は同じプランナーを実行し、読み込み対象のユニットのみを読み込んで、それらを指示ではなくナレッジとして扱い、Claude に回答させます。@anthropic-ai/sdk（オプションの依存関係）と API キーが必要です。plan にはどちらも必要ありません。

ask --loop — 監査可能な批評ループ

node dist/cli.js ask "who won, and what does it mean for infrastructure?" \
  --manifest ./knowledge.yaml --loop --methods free,x402 --budget 0.50

決定論的なスコアラーは語句ベースのため、発行者の語彙とは異なる表現のタスクでは、関連するユニットを見落とすことがあります。--loop は、決定論性を損なわずにこの差を埋めます。モデルが提案し、プランが決定します。

plan → LLM gap critique (metadata only) → term gate → re-plan → … → load → answer

高速な批評モデル（デフォルトは claude-haiku-4-5。変更するには --loop-model）には、プランのメタデータダイジェスト（ID、意図、スコア、スキップ理由。ユニットの内容は含みません）が提示され、追加の小文字の検索語句が提案されます。決定論的なゲートが検索語句をサニタイズ、重複排除し、上限を設定したうえで、タスク文字列を拡張し、プランナーが最初からプランを作り直します。批評モデルが提案を出し切る、ラウンドでユニットが追加されない、または --max-rounds（デフォルトは 3）に達すると、ループは収束します。その後、最終プランで対象となるユニットを使って、合成処理が元のタスクに回答します。

批評モデルには決してできないことがあります。アクセスゲートを開くこと、信頼性・時間・対象者に関する判断を変更すること、または費用を発生させることです。検索語句が影響するのは関連性スコアだけです。ループが収束するまでは、何も読み込まれず、費用も発生しません。また、最終プランの予算計算によって、単発モードと同じように支出が制御されます。各ラウンドはすべて記録されます（提案された検索語句、採用された検索語句、却下された検索語句、追加されたユニット、再プランニング後の成果物全体）。--json を指定すると、プランの連鎖そのものが監査ログになります。

同じループはライブラリ（差し替え可能な批評モデルを使う runLoop / askLoop）としても利用できます。また、skills/kcp-navigator/SKILL.md は、この手法を、CLI を自ら操作するエージェント向けのポータブルなスキルとしてまとめています。

ask --ground — 回答を検証し、裏付けられない内容を明らかにする

node dist/cli.js ask "who won, and what does it mean?" --manifest ./knowledge.yaml --ground

プランのフェイルクローズ型ゲートは、何を読み込めるかを判断します。グラウンディングは、同じ規律を何を主張できるかにまで広げます。合成処理の後、回答内の各主張は独立した検証器によってチェックされます。これは生成モデルとは別のモデル呼び出しであり、読み込まれたユニットのいずれかに主張の根拠を帰属できなければ、何も返してはなりません。その結果、次の 2 部構成の成果物が生成されます。

Grounded (2/3 claims):
  ● The award went to the Nordic bid.
     ↳ chipfab-exclusive · sha 9f2c1a0b7e34
Unsubstantiated (1): — could not be grounded in a loaded unit
  ○ The datacenter runs on hydro power.
     no loaded unit supports this claim
⚠ partial-unsupported — 1 claim(s) could not be substantiated

主張がグラウンディングされるのは、引用されたユニットが実際に読み込まれており、その内容のハッシュが一致する場合のみです。そのため、検証器が誤って帰属させたり、プロンプトインジェクションを受けて未読み込みのユニットを引用したりしても、その主張がグラウンディングされることはありません。帰属は提案にすぎず、グラウンディングは判定されます。裏付けのない主張は黙って除外せず、明らかにします。これは「すべての判断に根拠を示せる」状態を実現するための、誠実な対応です。明らかになった各不足は、発行者へのシグナルでもあります。つまり、タスクに必要な証拠がマニフェストに用意されていなかったことを示します。侵害された生成モデルが根拠のない不足を大量に作り出すのを防ぐため、明らかにする項目数には上限が設けられています。

--ground-rounds <n> を指定すると、ループが動作します。明らかになった不足を手がかりに表現を変更する検索語句を作り、エージェントが不足している証拠を探すために再ナビゲートし、再度グラウンディングを行います。これを最大 n ラウンド実施します。次の独立した 3 つの上限のうち、いずれか 1 つに達すると停止するため、終了は保証されています。検索語句ゲートは吸収的です。一度採用された検索語句は常に記録されるため、再ナビゲーションで追加できるのは、有限な対象ユニットの集合に含まれるものだけです。次に、ラウンド上限があります。さらに、進捗ガードにより、新しいユニットが追加されなかったラウンドは停止します。読み込み済みユニットの集合は単調に増えるか、ループが停止するため、振動は起こりません。grounded ではないすべての終端状態（partial-unsupported、partial-budget、partial-rounds）でも、残りの不足は明らかにされます。検証器が侵害されても、できるのは対象ユニットの範囲内でナビゲーションを広げることまでです。ゲートを越えたり、URL を指定したり、予算を超過して支出したりすることはできません。

assess — 実行してよい内容を判定する

プランのゲートは何を読み込んでよいかを決め、グラウンディングは何を断言してよいかを決めます。
assess()は、結論を実行に移す前に、信頼度がしきい値を超えているかを判定します。
これは合成の後段で実行されます。信頼度は出力の性質であり、そのため構造上、選択前カスケードのゲート#14にはなり得ません。

import { assess } from "kcp-agent";

const verdict = await assess(task, answer, loadedUnits, {
  threshold: 0.7,            // org policy — caller-supplied, never manifest data
  severity: "critical",
  evaluator,                 // optional: makeProviderEvaluator(provider) — a separate judge
});
// { gate: "confidence", passed, score, threshold, signals[], detail, asOf }

グラウンディングと同じ信頼の考え方を採用しています。信頼度は提案であり（回答自身によるextractSelfReport経由のConfidence: 0.82形式の自己申告や、注入された評価器の判断）、ゲートは決定論的に裁定します。デフォルトではminで集約し、測定できないものがあればフェイルクローズします。しきい値を実際の結果に基づいて継続的に調整できるよう、生のsignals[]はすべての判定にそのまま保持されます。判定ではゲートと同じ二値判定と理由の記述による契約を再利用しますが、後段の別個の成果物です。DecisionTraceと適合性ベクトルには変更はありません。

適用を担うのはkcp-harnessです。そのharness_assess MCP ツールはこのゲートを実行し、重要なタスクで判定に失敗した場合、判定を証拠として埋め込んだ承認チケットを通じて指名された人間にエスカレーションします。

kind: skill — 知識とは別にゲートで管理する手順

仕様§4.3a（v0.26.1）では、通常の知識に加えて、もう一つのユニット種別を追加しています。kind: skillは、エージェントが実行できるもの、つまりランブック、スクリプト、手順を示し、単に読むものとは区別します。スキルはデフォルトでフェイルクローズします。kind: skillユニットは、マニフェストに明示的なload_eligible: trueの許可がなく、アクセス可能なaction_scope（使用可能なtools、paths、capabilities）が指定されていない限り、呼び出し対象になりません。これは独自のゲートskill_eligibilityとして動作し、関連性の直後に選択前カスケードへ挿入されます。カスケードは13ではなく、14個のゲートで構成されます。

units:
  - id: restart-web-service
    kind: skill
    load_eligible: true
    action_scope:
      tools: ["shell.exec"]
      paths: ["/opt/web-service"]
      capabilities: ["service.restart"]

許可されていないスキルも引き続きプランに含まれます。エージェントは、そのスキルが存在することと、タスクに合致した理由を確認できます。これは他のすべてのゲートと同様に、実行前に監査する考え方です。スキルは単に読み込みが保留される（loadEligible: false）か、--strict指定時には完全に除外されます。この場合、汎用的なstrictカットオフではなく、skill_eligibilityに明確に帰属します。スキルをプランに含めることは常に安全ですが、呼び出すには別途、明示的な許可が必要です。以下の管理対象スキルのデモと、移植時に再現すべき正確なゲート契約を記載した適合実装ガイドを参照してください。

デモ — モックなしの20のシナリオ

node examples/demos.js            # all twenty, narrated
node examples/demos.js --list     # newsstand · transition · vault · org · audit · trace · loop · grounding · seal · incident · leash · summer · milky-way · moved-world · deja-vu · borrowed-memory · context-window · dogfood · second-opinion · governed-skill
node examples/demos.js vault      # one at a time

デモ	内容	仕様
ニューススタンド	上限は0.40 USDC。スコアで購入し、見送る場合は理由に計算式を示します	§4.14
移行	1つの質問に対して、3つの--as-of日付を指定します。重複日の判定は後継関係で行います	§4.22
金庫	支払いで認証ゲートが開くことはありません。x402を持っていても、フェイルクローズです	§4.11/§4.14
組織	フェデレーションのcontextは環境ごとにスライスされます。agent_identityはフェッチ前に認証情報を計画します	§3.6
監査	2つの--jsonプランを比較し、機能の切り替えでどのゲートが動くのか、その価格はいくらかを正確に示します	—
ループ	スクリプト化された批評者を使った監査済み批評ループです。インジェクションは拒否され、条件は再計画され、予算は維持されます	—
グラウンディング	ask --groundでは、未ロードのユニットを引用する主張はフェイルクローズします。クローズドループが再ナビゲートし、実際のバイト列に対してグラウンディングします	—
03:00のページ	4つのフェデレーション参加者にまたがるゼロデイです。アテステーション、署名済みCERT、後継関係、強制ゲートとしてのTLP:AMBER、情報予算を扱います（examples/incident/）	すべて
借りた手綱	スクリプト化された外部MCPクライアントがstdio経由でインシデントを再計画します。ゲートも台帳も同じです。その後、kcp_replayが偽造されたアーティファクトを検出します	—
封印	署名済みマニフェストを検証します。署名後にユニットを1つ追加すると、計画前にフェイルクローズします	§3.2
夏の計画	4つのフェデレーション参加者にまたがる家族旅行です。署名済みハブ、時刻表の後継関係、IDでゲートされたアクセシビリティ登録簿、x402によるツアー詳細、そしてvalidate lintで検出されるnot_forの落とし穴を扱います（examples/summer/）	§3.6/§4.11/§4.22
天の川	企業全体のドキュメント群です。8つのドメインにまたがる署名済みハブとして、環境ごとにスライスされた開発用ミラー、適用開始前の日付が設定された将来の規制、人間のみが参照できる人事ドキュメント、HSMでアテステーションされた処方、IDでゲートされたサブスクリプション料金階層を持つERPベンダー、CSRDの年次引き継ぎを扱います（examples/milky-way/）	§3.6/§4.14/§4.22
移ろう世界	エピソード記憶です。回答をバイト列なしで記録し、タスクの重なりによって呼び出してから再生します。ピンが保持されている間はグラウンディングされたままですが、ソースが移動した瞬間にドリフトします	—
デジャヴュ	メモリ検証済みの再利用です。変更されていないマニフェストに対する同一入力は、同じプランであることを証明できます。新しいオプションでは一致せず、ドリフトしたマニフェストは拒否されます	—
借りたメモリ	MCPセッションの重複排除です。呼び出し元がすでに持つバイト列はkcp_loadが渡さず（SHAで確認済みのスタブを返します）、ドリフトしたユニットは再配信します	—
コンテキストウィンドウ	--context-budgetではトークン上限を設定し、スコア順の貪欲法で選択します。上限超過のユニットは計算式とともにスキップされます。サイズは宣言されたsize_tokensまたはbytes/4から算出します	—
ドッグフーディング	エージェントが自分自身のリポジトリを検証してナビゲートします	§2
セカンドオピニオン	assess()が、確信度の低い結論が実行に移される前にゲートします	—
ガバナンスされたスキル	kind: skillの手順は、明示的なaction_scopeの許可によって呼び出し可能になるまでフェイルクローズします	§4.3a

各デモで説明される事実はすべて、リリースされるCLIとライブラリの実際の出力を解析または計算したものです。ハードコードされた内容はありません。また、test/demos.test.tsがCIですべての20件を実行するため、説明自体が回帰テストになっています。すべてオフラインで動作し、APIキーは不要です。

このリポジトリは自分自身を説明します

このリポジトリはKCPをドッグフーディングします。ルートにあるknowledge.yamlは、README、ソースモジュール、デモマニフェスト、CIワークフローをナレッジユニットとして宣言し、KCP spec自体のマニフェストとフェデレーションしています。そのため、エージェントは自分自身のリポジトリをナビゲートできます。

node dist/cli.js plan "how does the planner score units?" --manifest .

test/manifest.test.tsは、マニフェストが正直であることを保ちます。解析可能であり、実在するファイルを指し、適切に計画できることを確認します。

オプション

フラグ	意味
--manifest <loc>	knowledge.yaml のパス、ディレクトリ、または HTTPS URL（必須）
--env <name>	フェデレーションの context 選択に使用する実行環境（dev／test／staging／prod）。フェイルクローズ：指定しない場合、context タグ付きの参照はたどりません
--as-of <date>	時間評価に使用する ISO 日付（デフォルト：今日、UTC）
--max-units <n>	選択するユニット数の上限（デフォルト：5）
--strict	フェイルクローズ：対象外のユニットを一覧表示せず、除外します
--role <role>	エージェントが提示する対象者のロール（デフォルト：agent）
--methods <list>	エージェントが決済できる支払い方法（例：free,x402）
--credentials <list>	エージェントが保有する認証情報の種類（例：api_key,oauth2）
--attest <provider>	エージェントが提示できるアテステーションプロバイダー
--budget <amount>	リクエストごとの課金ユニットに対する支出上限。スコア順に貪欲に選択し、上限を超えるユニットは計算過程とともにスキップします。上限はマニフェストごとではなく、フェデレーション全体の走査に適用されます
--currency <code>	予算の通貨（デフォルト：USDC）
--context-budget <n>	プランがモデルのコンテキストウィンドウに読み込む内容のトークン上限。スコア順に貪欲に選択し、上限を超えるユニットは計算過程とともにスキップします。--budget と併用する場合、ユニットは両方の上限内に収まる必要があります
--follow	対象となるフェデレーション参照も取得してプランを作成します（フェイルクローズ：ゲートで制限された参照や除外された参照は取得しません）
--max-depth <n>	たどるフェデレーションのホップ数（デフォルト：1。--follow を暗黙的に有効化します）
--max-nodes <n>	走査全体で取得するマニフェスト数の上限（デフォルト：64。フェイルクローズのファンアウト上限）
--allow-private-hosts	ループバック／プライベート／リンクローカルのホストおよび http:// への取得を許可します。デフォルトでは無効です（内部アドレスやメタデータアドレスへの SSRF をブロックします）
--no-verify	マニフェストの署名検証をスキップします
--require-signature	すべてのマニフェストに検証済みの署名がない場合、失敗します
--trust-key <loc>	検証に使用する固定済み ed25519 公開鍵（パス、URL、またはインライン）
--trace	(plan) 判断トレースを表示します。ユニットごとのゲートカスケードとして、各ユニットに適用されたすべてのゲートを順番に表示します
--json	プランを（ask の場合は回答も）JSON として出力します
--correlation-id <id>	呼び出し元が指定する不透明な ID を --json のエンベロープに含めます。これにより、プランの成果物を呼び出し元の判断チェーンまたは監査ログに紐付けられます
--help	使用方法とオプションのリファレンスを表示します（-h も使用可能。任意のサブコマンドの後でも機能します）
--once	(watch) 監視を続けず、検証／プラン作成を1サイクル実行して終了します
--diff	(watch) 前回のサイクルと比較して変更点を報告します
--task <task>	(watch) 各サイクルで再プランするタスク
--publisher <name>	(init) 生成するひな形マニフェストに記載する発行者名
--from-llms-txt <loc>	(init) 既存の llms.txt から knowledge.yaml のドラフトを作成します（URL またはパス）
--dry-run	(init) 生成した knowledge.yaml を書き込まずに表示します
--force	(init) 既存の knowledge.yaml を上書きします
--model <id>	(ask) モデル ID：provider/model（例：openai/gpt-4o、anthropic/claude-opus-4-8）。デフォルト：claude-opus-4-8
--base-url <url>	(ask) OpenAI 互換エンドポイントのベース URL（プロバイダーのデフォルトを上書きします）
--api-key <key>	(ask) API キー。環境変数 ANTHROPIC_API_KEY／OPENAI_API_KEY の代わりに指定できます
--loop	(ask) 監査付きの批評ループ：プラン作成 → LLM による不足点の批評 → 用語ゲート → 再プラン
--max-rounds <n>	(ask --loop) 批評ラウンドの最大数（デフォルト：3）
--loop-model <id>	(ask --loop) 批評モデル（デフォルト：claude-haiku-4-5）
--ground	(ask) 読み込んだユニットに照らして回答の各主張を検証し、裏付けのない主張を明示します
--ground-model <id>	(ask --ground) 検証モデル（デフォルト：claude-haiku-4-5）
--ground-rounds <n>	(ask) クローズドループのグラウンディング：明示された不足点について、証拠を求めて再ナビゲーションします（デフォルト：0）
--check-gaps	(replay) 今日のマニフェストを再ナビゲーションし、グラウンディング済みの回答で明示された不足点が解消されるか確認します
--memory <dir>	(remember/recall) エピソード記憶ディレクトリ。成果物ごとにハッシュでアドレス指定されたエントリを1つ保存します
--replay	(recall) 呼び出した各エピソードを今日のマニフェストに照らして再検証します（内容に変化があったものが見つかると、終了コード1で終了します）
--limit <n>	(recall) 返すエピソード数の上限
--public-url <url>	(serve) このサーバーに接続できる公開 URL。マニフェストで宣言された serving.mcp（§3.12）と自己チェックされ、不一致の場合は起動時に警告します
test/docs.test.ts はこの表を正確に保ちます。parseArgs が受け付けるすべてのフラグは、ここおよび cli.ts のヘッダーに記載されている必要があり、その逆も同様です。

validate — knowledge.yaml を lint する

node dist/cli.js validate .            # or a path, directory, or URL

エラーは、エージェントを誤解させたり、処理を失敗させたりする構造上の問題です（ID の重複、安全でないパスや存在しないパス、参照先のない superseded_by、どのエージェントも決して満たせない証明要件など）。警告は、ナビゲーションを弱める宣言です（トリガーがない、後継がいないまま期限切れになったユニットなど）。 エラーがある場合の終了コードは 1 です。マニフェストを公開するあらゆるリポジトリの CI で実行してください。

replay — 保存済みのプランまたは根拠付き回答を再検証する

node dist/cli.js plan "task" --manifest . --json > plan.json
node dist/cli.js replay plan.json       # exit 0 identical · exit 1 drifted

plan --json の成果物には、マニフェストの sha256 と、すべてのプランナー入力が記録されています。replay は各マニフェスト（--follow ツリーのすべてのノード）を再取得してバイト列を比較し、保存された入力で純粋なプランナーを再実行して、マニフェストごとに、変更されたフィールドとともに一致または差分ありを報告します。プランは証拠であり、replay はその反対尋問です。成果物を手作業で編集した場合も差分になります。再計算したプランが成果物と一致しなくなるためです。

replay は、根拠付き回答の成果物（ask --ground --json によるもの）を自動検出し、代わりに各主張を個別に反対尋問します。根拠付きの各主張で引用されたユニットを再読込し、その sha256 を記録済みの値と再比較します。結果は、根拠あり、差分あり（バイト列が変更された）、または消失（ユニットが削除された）です。引用が1つでも成立しなくなった場合、終了コードは 1 です。古くなった回答を検証済みと誤認させてはなりません。--check-gaps を指定すると、今日のマニフェストを再ナビゲートし、以前提示されたギャップが今は解消したか（回答後にマニフェストに不足していた証拠が追加されたか）を確認します。ギャップにもライフサイクルがあり、記憶とは、変化した世界に照らして再検証できるプランです。

remember / recall — 再生可能なプランとしてのエピソード記憶

node dist/cli.js ask "who won the exclusive story" --manifest examples/fjordwire --ground --json > ans.json
node dist/cli.js remember ans.json --memory .kcp-memory        # log the episode (unit bytes stripped)
node dist/cli.js recall "the exclusive story winner" --memory .kcp-memory --replay

ここでの記憶は、要約でも埋め込みでもありません。プランまたは根拠付き回答の成果物そのものから、**保持すると危険になる唯一のもの、つまりユニットのバイト列を取り除いたものです。**制限付きコンテンツや有料コンテンツを記憶ログにキャッシュすると、後でアクセスゲートを再通過せずに recall で読めてしまいます。そのため remember が保持するのは replay に必要なものだけです。各ユニットの id、path、sha256、引用テーブルのみを残し、すべての content フィールドを削除します。エントリーは、コンテンツを取り除いた成果物をもとにハッシュアドレス化されるため、同じ回答を2回記録しても冪等です。

recall は、語彙上のタスク用語の重複度（プランナーがスコア付けに使うものと同じトークナイザー）に基づいて過去のエピソードを照合し、重複度順に並べます。バイト列は失われているため、呼び出されたエピソード自体は鮮度を保証しません。--replay を指定すると、各候補を今日のマニフェストに照らして再検証します。結果は、有効（引用されたすべてのユニットで記録済みのバイト列が維持されている）、差分あり（引用が変更された。終了コードは 1）、または検証不能（replay を実行できなかった）です。--replay を指定しない場合、すべての候補は unverifiable と報告されます。記憶が、古くなった回答を今も正しいと誤って主張することはありません。記憶とは、変化した世界に照らして再検証できるプランです。

memory-validated reuse — 決定性を保つキャッシュ

plan または ask に --memory <dir> を渡すと、エピソードログがキャッシュになります。その正しさの根拠は、ほかのすべてと同じ性質、すなわちプランが(manifest bytes, task, options)の純粋関数であることです。ルールは recall（一致の確認）＋replay（鮮度の確認）＝再利用 であり、それに満たない場合はすべてフェイルクローズします。

node dist/cli.js plan "how do I deploy" --manifest . --memory .kcp-memory   # records + reports determinism
node dist/cli.js plan "how do I deploy" --manifest . --memory .kcp-memory   # ♻ provably identical to episode …
node dist/cli.js ask  "how do I deploy" --manifest . --ground --memory .kcp-memory   # reuses a clean grounded answer, skips the model

plan --memory は各プランを記録し、以前のエピソードが同じタスク、マニフェスト、オプションで実行されていれば、今日のマニフェストがバイト単位で同一（♻ 同一であることを検証済み）か、それ以降に変化したかを報告します。これは決定性／監査のためのシグナルであり、sha の変更をまたいだ暗黙の再利用ではありません。キャッシュキーには有効な --as-of 日付が含まれるため、日付を固定していないプランを再利用できるのは同じ日付の間だけです。異なる機能（--role、--budget、…）での実行は別のプランであり、キャッシュヒットではありません。

ask --ground --memory は、再利用の効果が発揮される場面です。モデルを呼び出す前に、同一リクエストに対するキャッシュ済みのグラウンディングされた回答を探して再生し、引用されたすべてのユニットを再読み込みして、固定された sha256 を再確認します。すべての引用が引き続き有効な場合に限り、保存された回答を返します（♻ 再利用済み、モデル呼び出しなし）。引用されたユニットに変化があったか、存在しなくなった場合、回答は再計算され、古い内容が返されることはありません。取り込み時にユニットのバイト列はすでに除去されているため、想起された回答が次のアクセスゲートをすり抜けて制限対象のコンテンツを持ち込むことはありません。再利用時はガードを通してユニットをその場で再読み込みします。メモリとは、変化した世界に照らして再検証できるプランです。

mcp — プランナーをあらゆる MCP クライアントに提供

node dist/cli.js mcp                   # stdio transport

4 つのツールを公開します。kcp_plan（確認可能なロードプラン）、kcp_load（プランおよびロード可能なユニットの内容。これにより、呼び出し元エージェント自身のモデルが合成を行い、この処理で kcp-agent が API キーを必要とすることはありません）、kcp_validate、kcp_replay（保存済みのプラン成果物を通信経由で照合する機能）です。kcp_plan／kcp_load は CLI のすべての機能（role、methods、credentials、attest、budget）を受け取るため、アテステーションと認証情報のゲートは、コマンドラインの場合とまったく同じように、あらゆる MCP クライアントに対して機能します。借用するエージェント自体が決定論的である必要はありません。決定論的な相手に尋ねればよいのです。たとえば Claude Code に登録します。

claude mcp add kcp -- node /path/to/kcp-agent/dist/cli.js mcp

セッション内の重複排除。 kcp_load は known 引数を受け取ります。これは、呼び出し元がすでに保持しているユニットを [{id, sha256}] として指定するものです。sha が引き続き一致するユニットは、内容を再送せず、unchanged スタブ（バイト列は非公開、sha は確認済み）として返されます。これにより、複数ターンのセッションで呼び出し元のコンテキストウィンドウを節約できます。レスポンスには deduped と bytesSaved が報告されます。これはエピソードメモリの呼び出し元側での実装であり、その性質を保っています。サーバーはステートレスのままです（呼び出し元のウィンドウ自体がセッションです）。スタブが返されるのは sha が完全一致する場合のみで、変化があれば常に新しいバイト列を再送します。また、kcp_load は呼び出しのたびにプランを再作成し、各呼び出しでアクセス権を再確認するため、呼び出し元がその後アクセス権を失ったユニットは単に含まれず、スタブとして持ち込まれることもありません。

knowledge.yamlはllms.txtの進化形です

llms.txtは同じ問題の簡単な半分、つまりサイトの内容をエージェントに伝えることを解決し、公開者に採用されました。フラットなリンク一覧であり、それ以上のものにはなりません。

同じサイトを、どちらの方法でも扱えます。

# Acme Docs                                    kcp_version: "0.30"
                                               project: "Acme Docs"
> Everything you need to integrate Acme.       intent: "Everything you need to integrate Acme."

## Guides                                      units:
                                                 - id: "quickstart"
- [Quickstart](/quickstart):                       path: "quickstart"
    Get running in five minutes                    intent: "Get running in five minutes"
                                                   audience: [agent, human]
                                                   triggers: ["guides", "quickstart"]

既存のものを変換できます。決定論的で、モデル呼び出しはなく、すでにあるマニフェストを上書きすることもありません。

kcp-agent init --from-llms-txt https://acme.dev/llms.txt --dry-run

kcp-agent discover <url>は、クロールに切り替える前に/llms.txtも確認し、アップグレード方法を案内します。

アップグレードで得られるものは、llms.txtでは表現できません。

	llms.txt	knowledge.yaml
何が存在するか	✅ リンク一覧	✅ 意図とトリガーを持つユニット
誰を対象とするか	❌	audience、not_for、役割による制御
いつ有効か	❌	valid_from／valid_until、後継情報
信頼できるものか	❌	detached ed25519 signatures
費用はいくらか	❌	payment、予算、レート制限
どこを参照するか	❌	他の公開者のマニフェストへのフェデレーション
エージェントがそれを使って何を実行できるか	❌	kind: skill／playbook、action_scope、load_eligible

変換では、これらを捏造せず、すべてTODOとして記します。変換後のマニフェストが、対象者や有効期間を何の断りもなく記載していたら、あなたが述べてもいないことを主張することになります。

署名

マニフェストにはsigningブロック（スキームはed25519、鍵とデタッチ署名のURL。詳しくは仕様リポジトリ独自のマニフェストを参照）を指定できます。指定されている場合、kcp-agentは計画を立てる前に、マニフェストの正確なバイト列に対する署名を検証します。無効な署名は常にフェイルクローズとなり、検証不能な署名（鍵にアクセスできない場合）は、--require-signatureを指定していなければ警告となります。対応形式：JSON署名エンベロープ（{algorithm, public_key, signature}）、base64／hex形式の生署名、およびPEM／SPKI-DER／32バイトの生鍵。--trust-keyで公開者の鍵をピン留めすると、マニフェストが自分自身を証明できないようにできます。

ネットワーク境界

マニフェストは信頼できない入力であり、エージェントが取得するURL（フェデレーション参照、署名と鍵の場所、リモートユニットのコンテンツ）を選択します。すべてのリモート読み取りは、デフォルトでフェイルクローズとなる、保護された単一のフェッチ（src/fetch.ts）を経由します。

• SSRF／混乱した代理人 — リモートではhttps://のみ許可します。ループバック、プライベート、リンクローカル、クラウドメタデータのアドレス（例：169.254.169.254）は拒否されます。ホスト名はDNSで解決され、すべてのアドレスが検査されます。リダイレクトは手動でたどるため、公開ホストがエージェントをプライベートアドレスに誘導することはできません。--allow-private-hostsを指定すると、ローカル／内部マニフェストを許可できます。
• ファンアウト — 深さと循環はすでに制限されていましたが、--max-nodes（デフォルトは64）により、1回の--followで取得するマニフェストの合計数も制限されるようになりました。これにより、悪意のあるハブが何百万ものマニフェストにファンアウトすることを防ぎます。
• レスポンスサイズ — すべての読み取りはストリーミングで8 MiBの上限を監視し、超過すると中止されます。さらに、通信全体にタイムアウトが設定されるため、悪意のあるエンドポイントがメモリを枯渇させることはできません。

MCP経由では保護がデフォルトで有効です。外部のクライアントは、まさに信頼できない呼び出し元に該当します。

エージェントが見つけられるトリガーの記述

スコアラーは語彙ベースで決定論的です。意図、トリガー、ID／パスがタスクの用語と照合されます。モデルも埋め込みも使用しません。これがこの仕組みの特長です（再現可能、監査可能、無料）。そして、そこには率直に言って次のような結果があります。**ユニットを見つけられるかどうかは、そのマニフェストで宣言されている単語だけで決まります。**現場で実際に起きた見落としの例です。

task: "sovereign compute award and infrastructure implications"
  · datacenter-power: no task-relevance match      ← the story's best infrastructure angle

このユニットのトリガーは[datacenter, power grid, capacity, Nordics]で、意図には「infrastructure」と書かれていませんでした。語彙の重なりがなかったため、スコアは0となり、スキップされました。修正すべきなのはプランナーではなく、マニフェストです。

• コンテンツ内の名詞ではなく、エージェントが尋ねる質問に合わせてトリガーを書きます。「infrastructure」「energy costs」「where does the compute run」のような、タスクで使われる表現のほうが、記事の語彙より効果的です。
• 意図にも質問に関する用語を含めます。意図もスコアの対象です。そのため、「How the power grid limits sovereign compute infrastructure」なら見つかりますが、「Live Nordic datacenter power-grid feed」では見つかりません。
• 公開前に、自分のマニフェストに想定されるタスクを指定してkcp-agent planを実行してください。スキップ理由を見れば、実際のエージェントが何を、なぜ見落とすのかが正確にわかります。

ライブラリ

import { loadManifest, plan, synthesize } from "kcp-agent";

const manifest = await loadManifest("./knowledge.yaml");
const p = plan(manifest, "how do I deploy?", { env: "prod", capabilities: { paymentMethods: ["free", "x402"] } });
// p.selected / p.skipped / p.federation / p.budget / p.trust — a pure, inspectable artifact
const { answer } = await synthesize(p);   // optional LLM step

import { assess } from "kcp-agent";       // post-synthesis confidence gate
const verdict = await assess("how do I deploy?", answer, [], { threshold: 0.7 });

設計

• 決定論的なプランナー（src/planner.ts） — 純粋関数を使用し、ユニットテストで完全にテスト済み（npm test）です。I/Oもモデルも使用しません。プランは再現可能で監査可能です。
• 自己完結型のKCPクライアント（src/client.ts） — パス、ディレクトリ、HTTPS URLからknowledge.yamlを解析します。仕様リポジトリの内部実装には依存しません。
• フェデレーションフォロワー（src/follow.ts） — 純粋なプランナーを囲む非同期シェルです。対象となる参照を再帰的に取得し、失敗時は閉じた状態で処理し、循環検出とホップごとの署名検証を行います。
• 署名検証（src/verify.ts） — WebCryptoを使用し、正確なマニフェストバイト列に対してed25519を検証します。
• 合成レイヤー（src/synthesize.ts） — モデルを呼び出す唯一の部分です。プランに含まれるユニットだけを読み込み、タスクに回答します。
• 信頼度ゲート（src/assess.ts） — 合成後に、呼び出し元が指定したしきい値に照らして、自己申告および／または評価者による信頼度を判定します。決定論的に処理し、失敗時は閉じた状態になります。
• MCP サーバー（src/mcp.ts） — 依存関係のない、stdio上のJSON-RPCです。

仕様への準拠

このエージェントはKCP 0.25を対象とし、以下のサブセットをエンドツーエンドで使用します。（仕様リポジトリのマニフェストでは現在kcp_version: 0.21が宣言されていますが、これらのレイヤーではマニフェストに互換性があります。）

仕様レイヤー	セクション	対応箇所
クエリのスコアリング（意図／トリガー／ID＋パス）	§15	planner.ts scoreUnit
対象ユーザーとnot_for／not_for_strictによるターゲティング	§4.20	planner.tsの関連性／ネガティブルーティングのゲート
アクセスが認証の軸 — 支払いで代替することはできません	§4.11	planner.tsのアクセスゲート
時間的な有効性と置き換え	§4.22	planner.ts temporalStatus
エージェントのアテステーション要件	§3.2	planner.tsの信頼ゲート
フェデレーションのcontext＋agent_identity	§3.6	planner.ts＋follow.ts
支払い方法とティア	§4.14	planner.ts planPayment
レート制限のティア	§4.15	planner.ts planBudget
マニフェストの署名（ed25519）	署名ブロック	verify.ts
検出（knowledge.yaml、.well-known/）	§2	client.ts

各行は、docs/conformance.jsonに記載された、準拠を担保するCIテストに対応しています。サイトではReceiptsとして表示されます。また、参照されているテストが削除または改名されると、test/docs.test.tsがビルドを失敗させます。

適合性ベクトル

vectors/ には、プランナーの判断をポータブルな (manifest, task, options) → expected outcome のフィクスチャとして固定しています。これは決定論的なコアの動作をコードではなく、データとして表したものです。test/vectors.test.ts は、参照プランナーがすべてのケースを再現することを検証します。Go/Rust への移植（2～5 MB の静的バイナリ向け）でも、サードパーティーによる実装でも、同じ結果を出せば適合しています。同じベクトルに合格した独立した実装が2つあれば、コードだけでなく 仕様 の妥当性を検証できます。これは、プロトコルに曖昧さがないことを示す最も強力な証明です。コーパスは参照プランナーから生成されるため（npm run gen:vectors）、期待される結果が手書きされることはありません。また、KCP の規範的な適合性テストスイートとして上流への提案が行われています。

まだ対応していない項目：ユニット間の依存関係チェーン、hints.load_strategy、コンプライアンス／監査ブロック。

ガイド

• クイックスタート — 最初の10分間 — インストール → 計画 → 質問 → 検証 → 提供 → 再生までを一通り行います。
• 10分でリポジトリをナビゲート可能にする — 何もない状態から、実際のプランの対象となり、CI で整合性が保たれるマニフェストを作成します。
• マニフェストに署名する — 正確なバイト列に対する ed25519、エンベロープ、鍵のピン留め、フェイルクローズのライフサイクルを扱います。
• プランナーを Claude Code に接続する — MCP 経由で kcp_plan / kcp_load / kcp_validate を利用します。API キーは不要です。
• エージェントにメモリを与える — 回答をバイト列を含まない再生可能なエピソードとして記録し、タスクに基づいて想起し、再生で検証し、有効な間だけ再利用します。
• セッションの重複排除でコンテキストコストを削減する — MCP 呼び出し元が known ユニットを kcp_load に渡し、コンテキストウィンドウの消費を抑える方法を説明します。
• 適合実装を構築する — プランナーパイプラインを仕様として示し、ベクトルを使って2つ目の実装（例：Go）を検証する方法を説明します。

ライセンス

Apache-2.0 · eXOReaction AS による提案で、Cantara のもとでホストされています。