陈述一个意图。Kage 的编排器会从你仓库自身的记忆中为编码智能体做简报，在隔离的 git worktree 中运行它——无论是单次运行还是多轮目标——并自行重新运行检查，而不是相信智能体的报告：
┌ 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 只会在声明成立后落地代码，并确认智能体所学到的内容，因此下一次简报——无论是你的还是队友的——都会从更聪明的起点开始。
这些记忆就是代码库背后的决策、棘手部署的运行手册、顽固 bug 的根因——在智能体工作时捕获，并对照实际代码进行校验，从而确保被复用的内容始终真实可靠。它以纯 Markdown 文件的形式保存在你的仓库中，符合 Google 开放知识格式 (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 · हिन्दी
在仓库中执行一条命令，然后重启你的智能体。 仅此而已。
npx -y @kage-core/kage-graph-mcp install它会创建 .agent_memory/、构建代码图谱、写入告知智能体使用 Kage 的 AGENTS.md / CLAUDE.md 策略、自动检测并接入你的智能体，同时配置 .gitignore 和 packet 合并驱动。需要 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 shell，只加载守护进程自身的页面——npm run dmg --prefix shell 则构建 macOS .dmg（仅 arm64；Windows/Linux 打包尚未构建）。
从手机访问。 守护进程还可以绑定到机器的局域网地址，通过每次请求（包括读取）都需要的配对密钥进行保护。目前这意味着需要手动在 .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 claude一个轻量原生 shell（仅 macOS，arm64），基于 CLI 所运行的同一守护进程——支持 Dock 图标、全局快捷键、原生通知。从 GitHub releases 下载最新的 .dmg（查找 Kage-<version>.dmg 资源）。
未签名构建在首次启动时会显示 macOS 的"无法验证开发者"提示——在 Finder 中右键点击应用并选择打开一次即可。安装后，它会在启动时及每 4 小时检查一次更新，并在重启后安装；临时（未签名）构建无法自行安装，会改为通知你并链接回 releases 页面。
更喜欢命令行？一行安装命令适用于所有无需应用即可运行的场景：
npx -y @kage-core/kage-graph-mcp installKage 是构建在记忆层之上的编码智能体编排器。当你的智能体工作时，它会将学到的内容（决策、bug 修复、约定、代码如何组合在一起）捕获为 开放知识格式 (OKF) 概念文件，并提交到仓库的 .agent_memory/ 目录下。下一次会话（无论是你的还是队友的）开始时就已经知道这些内容，而无需重新阅读或重新询问。
三个特点使其有别于其他记忆工具：
协作性。 一个人（或他们的智能体）摸索出的知识会成为整个团队的财富。记忆通过 git 共享，因此队友的下一次会话会从你刚刚学到的内容开始，而不是从零开始。
标准化且原生 git。 记忆是符合规范的 OKF 包——仓库中的纯 Markdown，与代码在同一 PR 中审查，任何 OKF 工具都可读取——不会锁定在某台机器或某个供应商的云端。你的知识始终属于你。
可验证。 每条记忆都引用其对应的代码，Kage 会在写入时、召回时以及 diff 更改代码时，对照你的实际文件检查这些引用。与代码不再匹配的记忆会被扣留，因此智能体永远不会基于过时的声明采取行动。
从第一天起，Kage 就将智能体记忆以纯文件形式保存在你的仓库中——没有云、没有数据库、没有锁定，而其他人都在构建记忆云。2026 年 6 月，Google Cloud 推出了开放知识格式：知识以 Markdown 形式存在于 git 中，供应商中立、无需账户——这正是 Kage 一直以来的理念。因此 Kage 采用 OKF 作为其标准，并用 OKF 刻意留白的层次为其赋能：
验证 — OKF 存储你写下的内容；Kage 对照你的真实代码检查每个概念，并在写入时拒绝幻觉引用。
新鲜度 — OKF 没有过时的概念；Kage 在代码变更的瞬间捕获漂移，并扣留不再真实的记忆。
代码锚定 — 确定性的代码图谱将每个概念锚定到其描述的确切符号上——这是 OKF 留给工具层的部分。
信任元数据位于符合 OKF 规范的 x-kage-* 字段中，因此 Kage 包保持 100% 合规，可在任何 OKF 消费者中打开，包括 Google 自家的可视化工具。OKF 标准化了存储；Kage 则是 Google 遗漏的验证和新鲜度层。
安装后即自动运行，无需手动执行任何操作：
行动前召回。 在任务开始时（以及智能体打开文件的瞬间），Kage 会为其呈现相关的已验证记忆。过时或已删除的记忆会被排除在外。
工作中捕获。 持久的学习成果成为 packets。引用不存在文件的记忆会当场被拒绝，因此幻觉永远不会进入存储。
代码变动时保持诚实。 当 diff 更改了记忆引用的代码时，该记忆会在 commit/PR 时被标记（kage pr check），并在重新验证或替换之前从召回中扣留，因此知识不会悄悄腐坏。
在本地仪表盘（kage viewer）中实时观看：packets、记忆↔代码图谱、信任门控以及智能体工作时的实时事件流。将任何内容包裹在 <private>…</private> 中，它就不会被存储。
大多数记忆工具（claude-mem、agentmemory、mem0、Zep）将记忆存储在单台机器或你不拥有的云端，并且从不与代码进行重新校验。Kage 将其保存在你的仓库中并进行验证，因此它始终属于你的团队，并随着代码的变更保持真实。
Kage | claude-mem | mem0 / Zep | |
自动捕获 + 会话开始召回 | ✓ | ✓ | 通过 SDK |
幻觉引用在写入时被拒绝 | ✓ | — | — |
过时记忆在召回时被扣留（引用的文件被删除/更改、TTL、已报告） | ✓ | — | — |
Diff 时捕获过时，当你的更改破坏记忆时在 PR 前发出警告 | ✓ | — | — |
记忆在 git 中审查，与代码同一 PR（纯文件，无数据库） | ✓ | SQLite + 云 | 托管 API |
将记忆编码为智能体自动加载的团队 | ✓ ( | — | — |
跨机器同步 | ✓ 你自己的 git 远程仓库 | 他们的云 | 他们的云 |
需要账户 / API 密钥 | 无 | 可选云 | 是 |
真相报告。 kage scan 在约 60 秒内读取任意仓库，并呈现其风险最高的知识缺口：无文档的热门文件、未测试的热路径、复杂度热点、未解决的技术债、以及 bus-factor-1 文件，还包括重复实现、死导出和文档谎言（如存在）。每项发现都引用到 file:line。零配置，不生成任何内容，在安装任何东西之前即可运行。
节省收据。 kage gains 维护每个仓库的价值账本（agent 无需重新花费的 token + 美元），每个数字都可追溯到一条已记录事件；agent 在每次召回后转发该账本。
团队技能。 kage skills 将持久、经过验证的流程转化为 .claude/skills/<name>/SKILL.md 文件，agent 会自动加载这些文件，提交并共享，无需云端。
个人记忆与同步。 kage learn --personal 将跨机器笔记保存在 ~/.kage/memory 中，以清晰分离的低信任度区块召回，并通过你自己的 git 远程仓库同步。
自愈会话循环。 未捕获的会话会被自动提炼为待审阅的草稿；kage resume 以"此前……"摘要打开每个会话；kage repair 用一条命令修复损坏的数据包和索引。
在同等正确性下比 grep 快 18%，用于真实代码导航任务（N=3 套件，同一 agent/模型；可用 kage benchmark --project . --compare 复现）。
LongMemEval-S 检索： 98.72% R@10 / 99.79% R@20 / 0.909 MRR —— 在每个深度上都领先于纯 BM25，除了 R@5，BM25 略胜一筹（96.60% 对 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 bundle完整 CLI 和 MCP 参考：docs。 将工作委派给编码 agent（派发 → 验证声明 → 合并）：docs/DELEGATION.md。
所有内容都存放在 .agent_memory/ 中：packets/ 是持久仓库记忆（git 跟踪的 OKF Markdown）；graph/、code_graph/、structural/ 和 indexes/ 可用 kage refresh 重建；reports/ 保存价值账本和健康报告。捕获在写入前会扫描机密和 PII。
标准格式 — 开放知识格式（OKF）。 Kage 的记忆是一个 OKF 包：带 YAML frontmatter 的纯 Markdown 概念文件，任何 OKF 消费者（包括 Google 的可视化器）都可读取。运行 kage okf migrate 可将存储渲染为 .agent_memory/okf/ 下的 OKF 包。Kage 补充了 OKF 未涵盖的生命周期——接地、验证和新鲜度——通过 OKF 合法的 x-kage-* 字段承载，并且可以 import 任何第三方 OKF 包。往返是无损的。参见 OKF_STANDARD.md。
cd mcp
npm install
npm test
npm run buildKage 是开放构建的，我们非常期待你的帮助。四个运行时依赖（检索核心零依赖），无账户，无云端——这是一个容易上手的友好代码库。
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
