意図を述べてください。Kageのオーケストレーターは、リポジトリ自身のメモリからコーディングエージェントに指示を与え、隔離されたgit worktree内で実行します（1回の実行または複数フェーズのゴール）。そして、エージェントの報告を信頼するのではなく、チェックを自分自身で再実行します：
┌ VERIFIED 3/3 — checks run by Kage, not the agent · build-a-stale-memory-triage-surface-do-n-260818-ec2c
│ "the stale-memory triage surface is built and wired into the review flow"
│ ✓ tests ran npm test --prefix mcp → exit 0 evidence/tests.log
│ ✓ diff-size inspected at most 800 changed lines evidence/diff-size.log
│ ✓ citations inspected every formally cited path exists (directly, or as a unique suffix) in the worktree evidence/citations.log
│ · touched 4 file(s), 212 line(s)
└────────────────────────────────────────────────────────────────これはこのリポジトリ自身の実行履歴からの実際のレシートです。各行はKageが実行したコマンドまたは調査した事実であり、エージェントが自分自身について主張した内容ではありません。kage merge は、その主張が成立した場合にのみコードを取り込み、エージェントが学んだことを承認するため、次回の指示（あなたのものでもチームメイトのものでも）はより賢く始まります。
そのメモリとは、コードベースの背後にある意思決定、厄介なデプロイのためのランブック、難しいバグの根本原因などです。エージェントが作業するときに取り込まれ、実際のコードに対して検証されるため、再利用されるものは真実であり続けます。メモリはリポジトリ内のプレーンなMarkdownファイルとして保持され、Google Open Knowledge Format (OKF) に準拠しているためロックインはなく、gitを通じてチーム全体で共有されます。アカウントもデータベースもAPIキーも不要です。
npx -y @kage-core/kage-graph-mcp install対応: Claude Code · Codex · Cursor · Windsurf · Gemini CLI · Cline · Goose · Roo Code · Kilo Code · OpenCode · Aider · Claude Desktop · Copilot · OpenClaw · Hermes · あらゆるMCPクライアント
🌐 English · 简体中文 · 日本語 · 한국어 · Español · Português (Brasil) · Français · Deutsch · हिन्दी
リポジトリ内で1つのコマンドを実行し、エージェントを再起動するだけです。 セットアップはこれだけです。
npx -y @kage-core/kage-graph-mcp install.agent_memory/ を作成し、コードグラフを構築し、エージェントにKageを使うよう指示する AGENTS.md / CLAUDE.md ポリシーを書き込み、エージェントを自動検出して接続し、.gitignore とパケットマージドライバーを設定します。Node.js 18+ が必要です。アカウントもAPIキーも不要です。
または、エージェントにセットアップを依頼するだけです。 これを Claude Code、Cursor、または任意のコーディングエージェントに貼り付けてください：
このリポジトリにKage（コーディングエージェント向けの検証済みメモリ、https://github.com/kage-core/Kage）をセットアップしてください：
npx -y @kage-core/kage-graph-mcp installを実行し、その後あなたを再起動するよう私に伝えてください。
# Claude Code / Codex plugin
/plugin marketplace add kage-core/Kage # then: /plugin install kage@kage
# wire a single agent (run `kage setup list` for all supported)
kage setup claude-code --project . --write
# memory store only, no agent wiring
kage init --project .
# confirm the harness is live
kage setup verify-agent --agent claude-code --project .Related MCP server: Agent Memory Bridge
kage room --project . # talk to Kage; it briefs and hires agents for you
kage dispatch "<intent>" --agent claude # one delegated run, briefed from repo memory
kage runs --project . # what every run is doing right now
kage review --project . # read a finished run's claim and diff
kage merge <run-id> --project . # land the code and ratify what it learned各実行は専用のgit worktree内で行われます。上記のレシートの判定を決めるチェック（テスト、diffサイズ、引用）は、エージェントの自己申告ではなく、Kage自身が実行するコマンドです。
アプリ。 kage app --project <dir> はローカルデーモンを起動（または再利用）し、同じルーム、実行ボード、メモリビューをUIで開きます。チェックアウトからは、npm start --prefix shell でネイティブウィンドウとして実行されます。これは独自のHTMLを持たない薄いElectronシェルで、デーモン自身のページを読み込むだけです。また、npm run dmg --prefix shell でmacOS .dmg をビルドします（arm64のみ。Windows/Linux用のパッケージはまだビルドされていません）。
スマートフォンから。 デーモンはマシンのLANアドレスにもバインドでき、すべてのリクエスト（読み取りも含む）で必須のペアリングシークレットによって保護されています。現時点では、.agent_memory/config.json に手動で "lan": true を設定する必要があります。--lan フラグやアプリのトグルはまだありません。
ターミナルを使わずにプロジェクトを追加。 kage projects add <dir> --agent claude は、アプリの「+」ボタンと同じ方法で別のリポジトリを登録し、その後 kage app --project <dir> でそれを開きます。
kage app --project <dir>
kage projects add <dir> --agent claudeCLIが実行するのと同じデーモン上の薄いネイティブシェル（macOS、arm64のみ）— Dockへの表示、グローバルホットキー、ネイティブ通知。最新の .dmg は GitHub リリース からダウンロードしてください（Kage-<version>.dmg アセットを探してください）。
署名されていないビルドは、初回起動時にmacOSの「未確認の開発者」プロンプトを表示します。Finderでアプリを右クリックし、開く を1回選択してください。インストール後は、起動時と4時間ごとにアップデートを確認し、再起動時にインストールします。アドホック（未署名）ビルドは自己インストールできないため、代わりにリリースページへのリンク付きで通知します。
CLIがお好みですか？アプリが不要な場所ならどこでも、ワンラインインストールで対応できます：
npx -y @kage-core/kage-graph-mcp installKageは、メモリレイヤーの上に構築されたコーディングエージェント向けのオーケストレーターです。エージェントが作業する際、学んだこと（意思決定、バグ修正、規約、コードの構造）を、リポジトリ内の .agent_memory/ にコミットされた Open Knowledge Format (OKF) コンセプトファイルとして取り込みます。次のセッション（あなたのものでもチームメイトのものでも）は、再読込や再質問をする代わりに、すでにそれを知った状態で始まります。
他のメモリツールと異なる3つの点があります：
協力的です。 一人（またはそのエージェント）が解き明かした知識は、チーム全体のものになります。メモリはgitを通じて共有されるため、チームメイトの次のセッションは、白紙ではなく、あなたが学んだばかりの内容から始まります。
標準的でgitネイティブです。 メモリはOKF準拠のバンドルです。リポジトリ内のプレーンなMarkdownであり、コードと同じPRでレビューされ、あらゆるOKFツールで読めます。単一のマシンやベンダーのクラウドに閉じ込められることはありません。あなたの知識はあなたのもののままです。
検証されています。 すべてのメモリは対象のコードを引用し、Kageは書込時、呼出時、そしてdiffがコードを変更したときに、実際のファイルとそれらの引用を照合します。コードと一致しなくなったメモリは差し控えられるため、エージェントが古い主張に基づいて行動することはありません。
初日から、Kageはエージェントメモリをリポジトリ内のプレーンファイルとして保存してきました。クラウドもデータベースもロックインもなく、その間、他の皆はメモリクラウドを構築していました。2026年6月、Google Cloudは Open Knowledge Format をリリースしました。git内のMarkdownとして知識を保持し、ベンダー中立、アカウント不要という、Kageがすでに実践していたまさにその理念です。そこでKageは OKFを標準として採用し、さらにOKFが意図的に除外しているレイヤーでそれを強化 しています：
検証 — OKFは書き留めた内容を保存します。Kageはすべてのコンセプトを実際のコードと照合し、幻覚による引用を書込時に拒否します。
鮮度 — OKFには陳腐化の概念がありません。Kageはコードが変更された瞬間に乖離を検出し、もはや真実ではないメモリを差し控えます。
コードへの接地 — 決定的なコードグラフが、各コンセプトをそれが記述する正確なシンボルに結び付けます。これはOKFがツール側に委ねているレイヤーです。
信頼メタデータはOKF準拠の x-kage-* フィールドに格納されるため、Kageバンドルは100%準拠を維持し、Google自身のビジュアライザーを含むあらゆるOKFコンシューマーで開くことができます。OKFはストアを標準化し、KageはGoogleが残した検証と鮮度のレイヤーです。
インストールすると、それは環境に溶け込みます。手動で何かを実行する必要はありません：
行動する前に想起。 タスクの開始時（およびエージェントがファイルを開いた瞬間）、Kageは関連する検証済みメモリを提示します。古いメモリや削除されたメモリは除外されます。
作業中に取り込む。 持続的な学びはパケットになります。存在しないファイルを引用するメモリはその場で拒否されるため、幻覚がストレージに入ることはありません。
コードが変化しても正しくあり続ける。 diffがメモリが引用するコードを変更した場合、そのメモリはコミット/PR時（kage pr check）にフラグ付けされ、再検証または置き換えられるまで想起から除外されます。これにより知識が静かに腐敗することはありません。
その様子は ローカルダッシュボード（kage viewer）で確認できます。エージェントが作業する間、パケット、メモリ↔コードグラフ、信頼ゲート、ライブイベントがストリーミング表示されます。<private>…</private> で囲んだものは決して保存されません。
ほとんどのメモリツール（claude-mem、agentmemory、mem0、Zep）は、メモリをマシンごと、またはあなたが所有していないクラウドに保存し、コードと照合し直すことはありません。Kageはメモリをリポジトリに保持して検証するため、チームのものとして残り、コードが変更されても正しいままです。
Kage | claude-mem | mem0 / Zep | |
自動キャプチャ + セッション開始時の想起 | ✓ | ✓ | SDK経由 |
幻覚による引用を 書込時に拒否 | ✓ | — | — |
古いメモリを 想起時に差し控え（引用ファイルの削除/変更、TTL、報告） | ✓ | — | — |
diff時の陳腐化検出、変更がメモリを壊す場合PR前に警告 | ✓ | — | — |
gitでメモリをレビュー、コードと同じPR（プレーンファイル、DBなし） | ✓ | SQLite + クラウド | ホスト型API |
メモリをチームの | ✓ ( | — | — |
マシン間同期 | ✓ 自前のgitリモート | 自社クラウド | 自社クラウド |
アカウント / APIキーの必要性 | 不要 | クラウド任意 | 必要 |
真実レポート。 kage scan は任意のリポジトリを約60秒で読み取り、最もリスクの高い知識ギャップを浮き彫りにします:
ドキュメント化されていないホットファイル、テストされていないホットパス、複雑性のホットスポット、
未解決のコード負債、バス係数1のファイル、さらに重複実装、デッドエクスポート、
ドキュメントの嘘（存在する場合）。すべての指摘は file:line に紐付けられます。セットアップ不要、
生成物なし、何もインストールする前に実行できます。
コスト削減レシート。 kage gains はリポジトリごとの価値台帳（エージェントが再消費せずに済んだトークン + $）を保持し、
すべての数値は記録されたイベントに遡れます。エージェントは各リコールの後にそれを報告します。
チームスキル。 kage skills は永続的で検証済みの手順を、エージェントが自動ロードする
.claude/skills/<name>/SKILL.md ファイルに変換します。コミットして共有でき、クラウドは不要です。
個人メモリと同期。 kage learn --personal はマシン間のメモを ~/.kage/memory に保持し、
明確に分離された低信頼度セクションとして呼び出され、自分の git リモート経由で同期されます。
自己修復型セッションループ。 キャプチャされなかったセッションは自動的に蒸留され、レビュー待ちの下書きになります。
kage resume は各セッションを「前回の…」ダイジェスト付きで開きます。kage repair は壊れたパケットとインデックスを1コマンドで修復します。
同等の正確性で grep より18%高速、実際のコードナビゲーションタスクで（N=3スイート、同一エージェント/モデル。kage benchmark --project . --compare で再現できます）。
LongMemEval-S 検索: 98.72% R@10 / 99.79% R@20 / 0.909 MRR — 素の BM25 をあらゆる深さで上回りますが、 R@5 のみ BM25 が僅差で勝っています（96.60% vs 96.17%。完全な表は benchmarks/LONGMEMEVAL.md）。 検索パス自体は依存ゼロ: BM25 + スパース語彙スコアリングで、埋め込みもネットワークも不要です。
変更時のメモリ正確性: 古いまま提供されるのは 0% です（コードが削除・変更されたメモリは提供されません）。 一方、すべてをキャプチャするストアでは 100% です。
信頼性ベンチマーク: 100/100。幻覚の拒否、古い情報の除外、ライブグラウンディングをカバーします（kage benchmark --trust --project .）。
方法論、コマンド、注意点: docs/BENCHMARKS.md。
kage recall "how do I run tests" --project .
kage verify --project . # check citations against current code
kage pr check --project . # stale-catch + graph freshness gate
kage gains --project . # what Kage saved you
kage viewer --project . # local dashboard
kage okf migrate --project . # render memory as a Google OKF bundleCLI と MCP の完全リファレンス: ドキュメント。 コーディングエージェントへの作業委任（タスク発行 → 検証済み成果 → マージ）: docs/DELEGATION.md。
すべては .agent_memory/ に置かれます: packets/ は永続的なリポジトリメモリ（git追跡される OKF Markdown）です。
graph/、code_graph/、structural/、indexes/ は kage refresh で再構築できます。
reports/ は価値台帳とヘルスレポートを保持します。キャプチャは書き込み前にシークレットとPIIをスキャンします。
標準形式 — Open Knowledge Format (OKF). Kage のメモリは
OKF バンドルです:
YAML frontmatter 付きのプレーンな Markdown コンセプトファイルで、あらゆる OKF コンシューマー
（Google のビジュアライザーを含む）で読めます。kage okf migrate を実行すると、ストアを
.agent_memory/okf/ 配下の OKF バンドルとして出力できます。Kage は OKF が対象外とするライフサイクル
— グラウンディング、検証、鮮度 — を、OKF 仕様上許容される x-kage-* フィールドに載せて追加し、
サードパーティの OKF バンドルも import できます。ラウンドトリップはロスレスです。
OKF_STANDARD.md を参照。
cd mcp
npm install
npm test
npm run buildKage はオープンに開発されており、あなたの協力を歓迎します。ランタイム依存は4つ（検索コアはゼロ）、 アカウント不要、クラウド不要 — 気軽に飛び込めるフレンドリーなコードベースです。
CONTRIBUTING.md — 開発環境のセットアップ、プロジェクト構成、規約。
ROADMAP.md — Kage の今後の方向性と、貢献できるポイント。
Good first issues · Help wanted — 範囲が明確な最初の着手先。
Discussions — 質問、アイデア、成果発表。
参加することで、当プロジェクトの行動規範に同意したものとみなされます。
GPL-3.0-only。 LICENSE を参照。GPL 切り替え前のリリースは MIT でした。
Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task; it answers caller/usage questions from the code graph too, so you rarely need a separate graph tool.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max memory packets to return (default 5) | |
| query | Yes | The task or question — used for both memory recall and code graph search | |
| targets | No | Optional files the agent may edit or explain; used for risk context | |
| session_id | No | Optional active agent session id for memory reconciliation | |
| project_dir | Yes | Absolute path to the project root | |
| changed_files | No | Optional changed files for pre-edit or PR risk context |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description correctly implies non-destructive behavior. It adds context about combined functionality and code graph answers, which is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy, front-loaded with core purpose, then usage guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no output schema, many siblings), the description adequately covers purpose and usage. Lacks detail on return format but acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra semantic context for individual parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is the primary entry point that validates memory health, recalls packets, and queries code/knowledge graphs. It distinguishes itself from sibling tools by aggregating multiple functions into one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to call at the start of every task and notes it reduces the need for a separate graph tool, providing clear when-to-use and implicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize the repo's 'why' memory at a glance: the decisions, gotchas, runbooks, conventions, and code explanations Kage has captured, plus which high-traffic code paths still have no decision memory. Use it to brief yourself on a repo before changing it, or to audit where institutional knowledge is thin or going stale. Read-only: returns grouped entries with titles, types, cited file paths, and call-outs for weak, stale, or undocumented hot paths. Does not modify any memory.
| Name | Required | Description | Default |
|---|---|---|---|
| project_dir | Yes | Absolute path to the repository root to summarize. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the annotation's readOnlyHint by stating 'Read-only' and 'Does not modify any memory.' It also details the return format (grouped entries with titles, types, etc.) and mentions call-outs for weak or undocumented hot paths, providing rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, usage guidance, and behavioral notes. It could be slightly more concise but remains focused and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context: it explains what the tool returns, its use cases, and that it is read-only. This is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'project_dir' is fully described in the schema as 'Absolute path to the repository root.' The description does not add any additional semantics beyond what the schema provides, so it meets baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as summarizing the repo's 'why' memory, listing specific content types (decisions, gotchas, conventions) and distinguishing its purpose from sibling tools like kage_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'to brief yourself on a repo before changing it' and 'to audit where knowledge is thin.' It implies not to use it for modification but does not list alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find how two files are connected in Kage's source-derived code graph. Reports direct dependency direction, reverse impact direction, or undirected graph connection.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Target file path or unique suffix | |
| from | Yes | Source file path or unique suffix | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description's 'reports' is consistent. However, the description does not disclose what happens if no path exists or other edge cases, which would enhance transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-front-loaded sentence that communicates the core functionality with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main use case but lacks details on return format, error handling, or edge cases. Given no output schema, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description adds no additional parameter meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding how two files are connected in a code graph, specifying three types of directions. This is distinct from sibling tools which focus on context, decisions, docs, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for understanding file dependencies but does not explicitly state when to use this tool over others or provide exclusions. Usage is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this repo's OWN committed documentation (README, docs/**, *.md, common doc dirs — including any framework/API docs checked into the repo). BM25 over heading-anchored chunks from .agent_memory/indexes/docs-index.json. Returns ranked doc hits with doc_path, heading, line, and snippet. This indexes only files on disk in the project, never the internet.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max ranked doc hits to return (default 5). | |
| query | Yes | Search terms to match against the repo's documentation. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true. The description adds algorithmic details (BM25, heading-anchored chunks), indexing scope (only files on disk), and output format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose, and each sentence adds distinct value: what is searched, how it works, what is returned, and what is not indexed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return fields and indexing source. It covers all essential aspects: scope, algorithm, constraints, and output, making it complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds meaning by explaining query as search terms, project_dir as absolute path, limit with default, and returns doc_path, heading, line, snippet. It also describes the indexing source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches committed documentation in the repo, using BM25 over heading-anchored chunks, and returns ranked results with specific fields. It distinguishes from internet search by specifying it indexes only files on disk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing info from the project's own docs and explicitly says 'never the internet,' which helps avoid misuse. It does not explicitly mention when to use alternatives among siblings, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record how useful a recalled repo-local memory packet was, which tunes Kage's trust and future recall. 'helpful' reinforces the packet, 'wrong' flags it as disputed, and 'stale' marks it for re-verification and withholds it from recall until refreshed. Use it right after a recalled packet helped you, misled you, or no longer matched the code. Mutates the packet's quality signals on disk.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | helpful = it was accurate and useful; wrong = it was incorrect (flag as disputed); stale = it no longer matches the code (mark for re-verification). | |
| packet_id | Yes | Id of the memory packet you are rating. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool 'Mutates the packet's quality signals on disk,' which is consistent with the readOnlyHint:false annotation. It also explains the effects of each kind (helpful, wrong, stale), providing full transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, then usage guidance, and ends with behavioral disclosure. Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 simple parameters, no output schema, and clear annotations, the description covers purpose, usage, behavior, and parameter semantics completely. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of each enum value (helpful, wrong, stale) and their consequences, which is not fully captured in the schema descriptions. However, the schema already describes the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record how useful a recalled repo-local memory packet was' and identifies the resource as memory packets. It distinguishes from sibling tools like kage_learn (which adds knowledge) or kage_refresh (which updates) by focusing on feedback/rating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it right after a recalled packet helped you, misled you, or no longer matched the code,' providing clear when-to-use guidance. It does not explicitly mention when not to use or compare to alternatives, but the context and sibling tools make the distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a durable, reusable learning from the current session as a verified repo-local memory packet (committed under .agent_memory/, shared with the team via git). Use it the moment you discover something a future session should know: a decision and its rationale, a bug's root cause and fix, a convention, or a setup step. Prefer it over diff-based proposals when you already know what was learned. The write is rejected if every cited path is missing from the repo (set allow_missing_paths for a file you are about to create), and secrets/PII are scanned out before writing. Returns the new packet id plus any contradiction warnings against existing memory.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional keywords to aid future recall. | |
| type | No | Memory type: decision, bug_fix, runbook, convention, gotcha, workflow, code_explanation. Inferred if omitted. | |
| paths | No | Repo files this memory is about; used to verify the citation now and to recall the memory when those files are touched later. | |
| stack | No | Optional technologies/frameworks the learning relates to. | |
| title | No | Short headline for the packet. Derived from the learning if omitted. | |
| evidence | No | How the learning was confirmed (e.g. test output, a reproduced behavior). | |
| learning | Yes | The insight to store, in full sentences: what was learned and why it matters to a future session. | |
| graph_nodes | No | Optional code-graph symbol or file ids this memory is grounded to. | |
| project_dir | Yes | Absolute path to the repository root. | |
| verified_by | No | What verified it (e.g. a command run, a passing test, a reviewer). | |
| discovery_tokens | No | Approximate token cost of producing this knowledge (exploration + reasoning). Stored on the packet so recall receipts can report replay value; a conservative per-type default is estimated when omitted. | |
| allow_low_quality | No | Admit this capture even though its computed quality score is below the admission floor (60). The write is otherwise rejected — this is the explicit override. | |
| allow_missing_paths | No | Allow the write even if cited paths do not exist yet (e.g. a file you are about to create). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details beyond the readOnlyHint=false annotation: the write commits under .agent_memory/, rejects writes when cited paths are missing, scans for secrets/PII before writing, and returns the new packet id plus contradiction warnings. This gives an agent a clear picture of side effects, validation, and output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient: it front-loads the core action, then gives usage timing, a preference rule, behavioral caveats, and the return value. Every sentence earns its place with no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter tool with no output schema, the description provides a complete mental model: what the tool does, when to use it, its side effects, its validation rules, and what it returns. The rich schema descriptions fill in the remaining parameter-level details, so an agent has enough to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful operational meaning for paths and allow_missing_paths by explaining the rejection condition and when to set the flag. It does not add semantics for every parameter, but the schema already covers the remaining ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: capturing a durable, reusable learning as a repo-local memory packet committed under .agent_memory/. It is precise about the object and purpose, though it does not explicitly differentiate among the sibling tools like kage_supersede or kage_skills; it only contrasts with diff-based proposals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use-case guidance: use it the moment you discover something a future session should know, with concrete examples such as decisions, bug root causes, conventions, and setup steps. It also says to prefer it over diff-based proposals when you already know what was learned, but it does not describe when-not-to-use it relative to named sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. Leads with a human summary of team memories invalidated by the current change — relay it to the developer. On a repo with many stale packets, validation findings, or reconciliation items, those lists are each capped to the 10 most actionable entries by default (stale packets ranked by urgency), with true totals and truncation notes; pass limit or verbose for more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entries per capped list to return (default 10 each). | |
| verbose | No | Return every entry in every list, uncapped. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by disclosing important behaviors: results are capped to 10 actionable entries by default, stale packets are ranked by urgency, true totals and truncation notes are included, and the output leads with a human summary that should be relayed. It also explains how limit and verbose alter behavior. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized, front-loading the core purpose in the first sentence and then adding behavioral details in subsequent sentences. Every sentence contributes essential information about what the tool returns and how to control output size. Nothing feels redundant or wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does a strong job of explaining the return shape: a human summary first, then capped lists with totals and truncation notes. It does not explicitly describe the overall readiness verdict format, but the purpose statement conveys that a merge-ready assessment is returned. This is sufficient for an agent to invoke the tool and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful value by explaining the default cap of 10, the urgency ranking for stale packets, that verbose returns everything uncapped, and that limit adjusts the cap. This goes beyond the schema's simple descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: it checks whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. This distinguishes it from siblings like kage_context, kage_risk, or kage_refresh, which have different purposes. The title reinforces the same intent without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use during PR/merge preparation, as it evaluates merge readiness for the current change. It explains what happens on repos with many stale packets and how to get more results, but it does not explicitly name excluded alternatives or state when a sibling tool should be chosen instead. This is clear context with no exclusions, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh. On non-default git branches metadata-only packet rewrites are skipped (quiet refresh) to avoid merge conflicts; pass force to persist them anyway. On a repo with many stale packets or validation warnings, stale_packets and validation.warnings are capped to the 10 most actionable entries by default (ranked by urgency), with the true total and a truncation note; pass limit or verbose for more.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Persist packet metadata rewrites even on a non-default branch | |
| limit | No | Max stale_packets / validation.warnings entries to return (default 10 each). | |
| verbose | No | Return every stale packet and validation warning, uncapped. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint and readOnlyHint annotations, the description discloses substantial behavior: the quiet-refresh mechanism for non-default branches, the capping of stale_packets/validation.warnings to 10 entries with truncation notes, and the effect of limit/verbose. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: it opens with the core action, then covers usage timing, branch-specific behavior, and output truncation in a logical flow. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the main operational concerns: when to run, how branch affects behavior, output capping, and override options. It implies the return includes stale_packets and validation.warnings, which is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds nuance to force (persists rewrites on non-default branches), limit (caps entries), and verbose (uncaps), which go beyond the schema's basic field descriptions. It does not elaborate on project_dir, but that is self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb-resource combination: 'Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata.' It clearly states what the tool does and distinguishes it from siblings like kage_pr_check by positioning it as a pre-PR maintenance step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit timing rules are given: 'run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh.' It also explains when to override the quiet refresh (pass force) on non-default branches, leaving no ambiguity about invocation conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assess modification risk for files using Kage's code graph plus local git history: dependents, impact surface, churn, ownership, co-change partners, and test gaps. Use before editing hotspot or shared files.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | No | File paths to assess | |
| project_dir | Yes | Absolute path to the repository root. | |
| changed_files | No | Optional PR/branch changed files. If targets is omitted, these are assessed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, signaling a safe read operation. The description adds value by detailing the method ('Kage's code graph plus local git history') and the specific risk factors assessed, without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence front-loads the core purpose, and the second provides usage advice. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the analysis dimensions (dependents, impact surface, etc.), giving a good idea of the output content. However, without an output schema, it does not specify the exact return format (e.g., score, report), leaving a minor gap for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already clearly documented. The tool description does not add additional meaning beyond what the schema provides for each parameter, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Assess modification risk') and resource ('files'), and lists concrete analysis dimensions (dependents, impact surface, churn, etc.). It distinguishes itself from sibling tools like kage_context or kage_decisions by focusing on risk, not context or decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use before editing hotspot or shared files.' This provides clear context, but it does not mention alternatives or when not to use it, which would be expected for a top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Codify durable, verified repo memory (runbooks, workflows, actionable decisions) into git-native SKILL.md files under .claude/skills/ that every teammate's agent auto-loads. Only grounded, non-stale packets become skills. Pass dry_run to preview without writing. dir overrides the output directory.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Override the output directory (default .claude/skills/). | |
| dry_run | No | Preview which skills would be written without creating any files. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals it writes files (non-read-only) and filters packets, matching idempotentHint. But it does not describe overwrite behavior or what happens on conflict, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, front-loading the core purpose in the first sentence. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the main action and parameters, it lacks details on return value or error handling. Given no output schema and the tool's write nature, additional clarity on outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no new semantic information beyond what is in the schema, making baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: creating SKILL.md files from repo memory. It specifies the target location (.claude/skills/) and the selection criteria (only grounded, non-stale packets). This distinguishes it from siblings like kage_context or kage_decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by mentioning dry_run for previewing and dir for output override. However, it lacks explicit 'when not to use' or comparison with sibling tools, which would enhance differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace one repo-local memory packet with a newer one that corrects or obsoletes it. Marks the old packet superseded, links it to the replacement, and writes bidirectional lineage edges so the history stays traceable. Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts. Mutates both packets on disk: the superseded packet is withheld from recall but kept for lineage. Returns ids, paths, and titles for confirmation, not the full packet bodies.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional human note recorded on the lineage edge explaining why it was superseded. | |
| packet_id | Yes | Id of the existing packet to retire (the one being replaced). | |
| project_dir | Yes | Absolute path to the repository root. | |
| replacement_packet_id | Yes | Id of the newer packet that wins and stays active. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses significant side effects: it marks the old packet superseded, writes bidirectional lineage edges, keeps the old packet but withholds it from recall, and mutates both packets on disk. It also clarifies that it returns only ids, paths, and titles rather than full packet bodies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, with each sentence forwarding a distinct fact: purpose, behavior, when to use, and output expectations. No filler or redundant restating of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema, the description covers effect, lineage behavior, return value shape, and usage conditions. An agent has enough information to invoke it correctly and understand the consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with meaningful descriptions, so the description benefits from full coverage. The description reinforces the roles of old and replacement packet, but does not add substantial detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and object—'Replace one repo-local memory packet with a newer one'—and clarifies what that means by describing the suspension and lineage updates. It distinguishes itself from deletion and from other kage tools by specifying its unique job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts.' This gives concrete selection criteria and points to an alternative behavior to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct concern: context gathering, decision summaries, dependency paths, documentation search, memory feedback, learning, PR checks, index refresh, risk assessment, skills creation, and memory superseding. There is no overlap in purpose; an agent can clearly select the right tool for each task.
All tools share the 'kage_' prefix, but the second part mixes nouns (context, decisions, feedback, risk, skills) and verbs (learn, refresh, supersede) as well as compound names (dependency_path, docs_search, pr_check). This mixed convention is still readable but lacks a consistent verb_noun pattern.
With 11 tools, the set is well-scoped. Each tool earns its place by covering a distinct aspect of the domain (memory management, code graph analysis, documentation, project checks). The count is within the ideal 3-15 range and feels neither bloated nor sparse.
The tool surface covers the core lifecycle: learn (create), context/decisions/docs_search (retrieve), feedback/supersede (update), and supersede (effective delete via obsoletion). Minor gaps include the lack of an explicit tool to list all memory packets or to delete them outright, but these are workable via existing tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared memory for coding agents. Stop re-explaining your codebase every session.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
shared AI-context layer for teams — persistent memory your agents search and update over MCP
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kage-core/Kage'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
