Kage

Kage 管理你的记忆和 Agent

说出你的意图。Kage 的编排器会根据你代码库自身的记忆为编码 Agent 撰写任务简报，在隔离的 git worktree 中运行它——无论是单次运行还是多轮目标——并且亲自重新运行检查，而不是轻信 Agent 的报告：

┌ 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 运行过的命令或检查过的事实——绝不是 Agent 对自身作出的声明。只有在声明得到验证后，kage merge 才会合入代码，并确认 Agent 学到的内容，让下一份任务简报（无论由你还是队友编写）更加完善。}

这些记忆记录了代码库背后的决策、棘手部署的操作手册、复杂错误的根本原因——它们在 Agent 工作时被捕获，并根据实际代码进行验证，因此重复使用的内容始终准确。它们以纯 Markdown 文件的形式保存在你的代码库中，符合 Google Open Knowledge Format (OKF)，因此不会造成供应商锁定，并通过 git 与整个团队共享。无需账户、无需数据库、无需 API 密钥。

npx -y @kage-core/kage-graph-mcp install

网站 · 文档 · 在线查看器 · npm · 预约演示

兼容 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 · हिन्दी

安装

在代码库中运行一条命令，然后重启 Agent。 设置就这么简单。

npx -y @kage-core/kage-graph-mcp install

该命令会创建 .agent_memory/、构建代码图谱、编写告知 Agent 使用 Kage 的 AGENTS.md / CLAUDE.md 策略文件、自动检测并接入你的 Agent，并配置 .gitignore 和数据包合并驱动。需要 Node.js 18+。无需账户、无需 API 密钥。

也可以直接让你的 Agent 帮你设置。 将以下内容粘贴到 Claude Code、Cursor 或任意编码 Agent 中：

在此代码库中设置 Kage（供编码 Agent 使用的经验证记忆，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 .

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 工作树中进行。上方回执中的判定检查——测试、差异大小、引用——均由 Kage 自行运行，而不是依赖 Agent 的自我报告。

• 应用。 kage app --project <dir> 会启动（或复用）本地守护进程，并在 UI 中打开同一个房间、运行看板和记忆视图。在检出目录中运行 npm start --prefix shell，会以原生窗口的形式运行应用——这是一个轻量的 Electron 外壳，本身不包含 HTML，只会加载守护进程自己的页面；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 claude

桌面应用

在 CLI 运行的同一个守护进程之上提供轻量的原生外壳（仅支持 macOS、arm64），支持 Dock 显示、全局快捷键和原生通知。从 GitHub releases 下载最新的 .dmg（查找 Kage-<version>.dmg 文件）。

未签名的构建版本在首次启动时会显示 macOS 的“无法验证开发者”提示——在 Finder 中右键点击应用，并选择一次 打开。安装后，应用会在启动时及每隔 4 小时检查更新，并在重启时安装更新；临时签名（未签名）的构建版本无法自行安装更新，而是会通知你并附上返回发布页面的链接。

更喜欢使用 CLI？在无需使用应用的任何平台上，都可以通过一行命令安装：

npx -y @kage-core/kage-graph-mcp install

Kage 是什么

Kage 是一个基于记忆层构建的编码 Agent 编排器。随着 Agent 工作，它会将学到的内容（决策、错误修复、约定以及代码之间的关联方式）记录为 开放知识格式（OKF） 概念文件，并提交到代码库中的 .agent_memory/ 目录。下一次会话（无论是你自己的还是队友的）就能直接利用这些知识，而不必重新阅读或再次询问。

它与其他记忆工具的区别主要体现在三方面：

• 支持协作。 一个人（或其 Agent）总结出的知识可以为整个团队所用。记忆通过 git 共享，因此队友的下一次会话就能获取你刚学到的内容，而不是从空白开始。
• 标准化且原生支持 git。 记忆是符合 OKF 规范的知识包——以纯 Markdown 的形式保存在代码库中，与代码一起在同一个 PR 中审核，并且可供任何 OKF 工具读取——不会被锁定在某台设备或某家供应商的云端。知识始终归你所有。
• 经过验证。 每条记忆都会引用其所涉及的代码；Kage 会在写入时、回忆时以及差异导致代码发生变化时，根据实际文件检查这些引用。不再与代码相符的记忆会被暂不提供，因此 Agent 不会依据过时的说法行事。

Kage 早已提出，Google 将其标准化。

从第一天起，Kage 就将 Agent 记忆以纯文件的形式保存在你的代码仓库中——无需云服务、数据库，也不会被供应商锁定，而其他人都在打造记忆云。2026 年 6 月，Google Cloud 发布了 Open Knowledge Format：以 Git 中的 Markdown 形式存储知识，供应商中立，无需账户——这正是 Kage 一直践行的理念。因此，Kage 采用 OKF 作为标准，并在此基础上大幅增强，补上了 OKF 刻意未涵盖的层：

• 验证 — OKF 存储你写下的内容；Kage 会根据你的真实代码检查每个概念，并在写入时拒绝虚构的引用。
• 时效性 — OKF 不会识别内容是否过时；Kage 会在代码变更时立即发现偏差，并阻止使用不再属实的记忆。
• 代码依据 — 确定性代码图将每个概念锚定到其所描述的确切符号上——这是 OKF 留给工具处理的层。

信任元数据存储在符合 OKF 规范的 x-kage-* 字段中，因此 Kage 数据包保持 100% 符合规范，可在任何 OKF 消费端打开，包括 Google 自己的可视化工具。 OKF 将存储标准化；Kage 则补上了 Google 未涵盖的验证与时效性层。

工作原理

安装后，它会自动在后台运行。你无需手动执行任何操作：

1. 行动前先回忆。 在任务开始时（以及 Agent 打开文件的那一刻），Kage 会呈现与之相关且已验证的记忆。过时或已删除的记忆不会显示。
2. 工作时自动记录。 有持久价值的经验会成为数据包。若记忆引用了不存在的文件，会立即被拒绝，因此虚构内容绝不会进入存储。
3. 代码变更时保持准确。 当差异改动了记忆所引用的代码时，该记忆会在提交/PR 时被标记（kage pr check），并从回忆结果中屏蔽，直到重新验证或替换，从而避免知识悄然过时。

通过本地仪表板（kage viewer）查看运行过程：数据包、记忆↔代码图、信任门控和实时事件流都会随着 Agent 的工作不断呈现。将任何内容括在 <private>…</private> 中，该内容就永远不会被存储。

_{`kage viewer`：底层记忆引擎为上方的编排器提供支持——团队的决策、操作手册和错误修复（紫色）保存在代码仓库中，并链接到相关代码（蓝色）。}

为什么选择 Kage

大多数记忆工具（claude-mem、agentmemory、mem0、Zep）会将记忆存储在各台机器上，或存储在你无法掌控的云端，而且从不根据代码重新检查记忆。Kage 将记忆保存在你的代码仓库中并进行验证，因此记忆始终属于你的团队，也会随着代码变化保持准确。

功能

• 真相报告。 kage scan 可在约 60 秒内读取任意代码仓库，并指出风险最高的知识缺口：未记录的热点文件、未经测试的热点路径、复杂度热点、未解决的代码债务和关键人文件，以及重复实现、无用导出和文档错误（如存在）。每项发现都标注了 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 检索： R@10 为 98.72% / R@20 为 99.79% / MRR 为 0.909——除 R@5 外，所有深度均领先于纯 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 build

贡献与社区

Kage 以开源方式开发，我们期待你的帮助。只有四个运行时依赖（检索核心不依赖任何项），无需账户，也无需云服务——这是一个很适合上手的代码库。

• CONTRIBUTING.md — 开发环境设置、项目布局和约定。
• ROADMAP.md — Kage 的发展方向，以及你可以参与的地方。
• 适合新手的问题 · 需要帮助 — 范围明确的入门任务。
• 讨论 — 提问、分享想法和展示成果。

参与即表示你同意我们的行为准则。

许可证

GPL-3.0-only。请参阅 LICENSE。切换到 GPL 之前发布的版本采用 MIT 许可证。