Kage

In June 2026 Google shipped OKF (Open Knowledge Format): a standard for keeping knowledge as plain Markdown concept files in your repo, vendor-neutral, no lock-in. It standardizes the store and stops there. Verification, freshness, and staleness are explicitly out of scope for v0.1. Kage is the framework that maintains it. It captures what your coding agents learn as a conformant OKF bundle in git, then keeps every concept honest against your real code: a memory whose cited code no longer exists is rejected at write time, and one that drifts when the code changes is flagged and withheld until it is re-verified. Deterministic, no LLM on the verdict path. No account, no database, no API key.

hljs language-bash

Copy

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

Website · Docs · Live viewer · npm

Works with Claude Code · Codex · Cursor · Windsurf · Gemini CLI · Cline · Goose · Roo Code · Kilo Code · OpenCode · Aider · Claude Desktop · Copilot · OpenClaw · Hermes · any MCP client

Install

One command, inside your repo, then restart your agent. That's the whole setup.

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

It creates .agent_memory/, builds the code graph, writes the AGENTS.md / CLAUDE.md policy that tells agents to use Kage, auto-detects and wires your agents, and configures .gitignore + the packet merge driver. Requires Node.js 18+. No account, no API key.

Ambient proxy — the zero-wiring path. Two steps: install once, then kage up once. Every Anthropic-API agent (Claude Code, Codex CLI, aider, ...) flows through Kage with no per-agent config at all.

npx -y @kage-core/kage-graph-mcp install   # once per repo
kage up                                    # audit-only config + runtime + background proxy (once)

Then, in any terminal:

kage run -- claude       # or: export ANTHROPIC_BASE_URL=http://localhost:8788
kage down                # stop the background proxy + runtime when you are done

kage up starts the proxy in the background: it keeps serving after you close the terminal, so new terminals only ever need kage run. Re-running kage up verifies the recorded proxy is really alive (pid + port, never the state file alone), reuses it, and exits 0; a stale record — say after a crash — is cleaned up and started fresh. To be honest about the one gap: a machine reboot stops the proxy (there is no system service), so run kage up once afterwards. Prefer the old behavior? kage up --foreground keeps the proxy in your terminal, where Ctrl-C stops it.

Auto-attach — so you do not have to remember kage run. kage setup claude-code --project . --write records env.ANTHROPIC_BASE_URL in that repo's .claude/settings.local.json, so an agent launched from that directory routes through Kage on its own. Your existing settings are preserved and any value you set yourself wins.

Two honest limits, both of which kage status now reports instead of leaving you to guess:

• It is per-directory. The agent reads the settings of the directory it was launched in, so wiring a git worktree while running the agent from the parent repo attaches nothing.
• Some hosts resolve their own endpoint and never read project settings — notably the Claude desktop app, which sets ANTHROPIC_BASE_URL itself. No amount of restarting attaches it. For proxy coverage there, launch the agent from a terminal (claude) or use kage run -- <agent>. Memory still reaches the desktop app through the Claude hooks; it is the proxy's byte-level measurement and injection you lose.

attach:  NOT attached in THIS session — settings are wired to http://localhost:8788, but the
         running host (claude-desktop) resolved https://api.anthropic.com itself ...

kage up defaults to audit mode: measurement only — your bytes are forwarded unchanged and nothing is injected. When you want verified memory injected into prompts, run kage up --mode assist. See what it measured with kage status --project ..

Or just ask your agent to set it up. Paste this into Claude Code, Cursor, or any coding agent:

Set up Kage (verified memory for coding agents, https://github.com/kage-core/Kage) in this repo: run npx -y @kage-core/kage-graph-mcp install, then tell me to restart you.

# 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 .

What is Kage

Kage is a memory layer for coding agents. As your agent works, it captures what it learns (decisions, bug fixes, conventions, how the code fits together) as Open Knowledge Format (OKF) concept files committed in your repo under .agent_memory/. The next session (yours or a teammate's) starts already knowing it, instead of re-reading or re-asking.

Three things make it different from other memory tools:

• It's collaborative. The knowledge one person (or their agent) figures out becomes the whole team's. Memory is shared through git, so a teammate's next session starts with what you just learned, not a blank slate.
• It's standard & git-native. Memory is a conformant OKF bundle — plain Markdown in your repo, reviewed in the same PR as the code, readable by any OKF tool — not locked in one machine or a vendor's cloud. Your knowledge stays yours.
• It's verified. Every memory cites the code it's about, and Kage checks those citations against your actual files at write time, at recall time, and when a diff changes the code. Memory that no longer matches the code is withheld, so the agent never acts on a stale claim.

Kage called it. Google standardized it.

From day one, Kage kept agent memory as plain files in your repo — no cloud, no database, no lock-in, while everyone else was building memory clouds. In June 2026, Google Cloud shipped the Open Knowledge Format: knowledge as Markdown in git, vendor-neutral, no account — the exact thesis Kage already ran on. So Kage adopted OKF as its standard, and supercharges it with the layer OKF deliberately leaves out:

• Verification — OKF stores what you wrote down; Kage checks every concept against your real code and refuses hallucinated citations at write time.
• Freshness — OKF has no notion of staleness; Kage catches drift the moment your code changes and withholds memory that's no longer true.
• Code-grounding — a deterministic code graph anchors each concept to the exact symbols it describes — the layer OKF leaves to tooling.

The trust metadata rides in OKF-legal x-kage-* fields, so a Kage bundle stays 100% conformant and opens in any OKF consumer, including Google's own visualizer. OKF standardizes the store; Kage is the verification and freshness layer Google left out.

How it works

Once installed, it's ambient — hooks watch the session; you don't run anything by hand. Four paths make up the loop:

flowchart LR
    A[session events<br/>prompts · edits · commands] -->|prose observations,<br/>signal-scored| B[distill on session end<br/>gate ≥0.4 · dedupe]
    B -->|drafts born pending| C{grounded + fail→pass<br/>evidence?}
    C -->|yes| D[approved packet<br/>OKF markdown in git]
    C -->|no| E[pending inbox<br/>kage review]
    D --> F[fingerprints:<br/>file hash + code-symbol anchors]
    F -->|cited code changed| G[stale: withheld<br/>until evidence reverify]
    D -->|ranked recall| H[injected context:<br/>session start · each prompt · each file open]
    D -->|git push/pull| I[teammate's next session]

Write path (capture). Hooks turn the session into observations — your prompts, each edit as prose (the edit content is where fixes and conventions live), each command with its output. Every observation is signal-scored; machine noise hard-rejects to zero. On session end, distill --auto gates (≥0.4), dedupes, and writes drafts born pending — never approved by default. One thing lifts a draft to trusted recall automatically: it cites real files, duplicates nothing, contradicts nothing, and the session contains a fail→pass command pair — mechanical evidence a real fix happened. Explicit kage_learn writes are refused if the cited files don't exist; secrets are scanned out.

Trust path (verification). Every packet fingerprints what it cites: a whole-file hash plus anchors on the code symbols the memory actually names (real identifiers only, never prose words). Cited code edited → soft-stale, withheld from recall until re-verified with evidence (kage reverify --evidence — a bare re-stamp on changed code is refused). Cited file deleted → hard-stale, withheld, garbage-collected after 30 days. "Verified" is earned by an actual check, never granted at birth.

Read path (recall). Three injection moments: session start (policy + "previously…" digest), every prompt (top verified packets + graph facts for what you asked), and every file the agent opens or edits (packets citing that file). Ranking trusts evidence — lexical match first, a damped graph prior that can't outvote a title match, recency decay so aged change-logs sink, and code-graph identifier grounding so a query for someFunction finds the packet citing the file that defines it. Stale memory never appears; every serve increments a real usage counter.

Team path (git). The store is plain OKF markdown committed in the repo — a teammate's clone is the memory transfer. A merge driver auto-resolves packet collisions (newest content wins), and kage pr check gates merges: if your diff breaks what a memory claims, you hear about it before the PR lands.

One principle threads through all four: every number Kage shows is a count of a reproducible check — never an estimate.

Watch it happen in the local dashboard (kage viewer): packets, the memory↔code graph, trust gates, and live events stream in as the agent works. Wrap anything in <private>…</private> and it's never stored.

Why Kage

Most memory tools (claude-mem, agentmemory, mem0, Zep) store memory per-machine or in a cloud you don't own, and never re-check it against the code. Kage keeps it in your repo and verifies it, so it stays your team's and stays true as the code changes.

Features

• Truth Report. kage scan reads any repo in seconds and surfaces its highest-risk knowledge gaps: undocumented hot files, untested hot paths, complexity hotspots, unresolved code debt, and bus-factor-1 files, plus duplicate implementations, dead exports, and doc lies when they exist. Every finding cited to file:line. Zero setup, nothing generated, runs before you install anything.
• Savings receipts. kage gains keeps a per-repo value ledger (tokens + $ the agent didn't have to re-spend), every number traceable to a logged event; the agent relays it after each recall.
• Team skills. kage skills turns durable, verified procedures into .claude/skills/<name>/SKILL.md files agents auto-load, committed and shared, no cloud.
• Personal memory & sync. kage learn --personal keeps cross-machine notes in ~/.kage/memory, recalled as a clearly separated lower-trust section and synced over your own git remote.
• Self-healing session loop. Uncaptured sessions are auto-distilled into pending drafts you review; kage resume opens each session with a "previously…" digest; kage repair fixes broken packets and indexes in one command.

Benchmarks

• LongMemEval-S retrieval: 96.17% R@5 / 98.72% R@10, zero dependencies.
• Memory Correctness Under Change: 0% stale-served (memory whose code was deleted or changed is withheld), vs 100% for capture-everything stores.

Methodology, commands, and caveats: docs/BENCHMARKS.md. Every number above has a reproducible harness in this repo; claims without one don't ship.

Daily commands

kage context "how do I run tests" --project .
kage verify --project .        # check citations against current code
kage pr check --project .      # stale-catch + graph freshness gate
kage report team --project .   # the lead-facing "is this helping?" report
kage viewer --project .        # local dashboard
kage okf migrate --project .   # render memory as a Google OKF bundle

📖 Using Kage — the practical manual: setup, the proxy, daily use, team workflow, troubleshooting, and a command map by intent. Kage has ~136 commands; you need about six.

⚙️ How it works — the mechanism end to end: the two delivery channels, proxy modes and cache safety, what gets stored and what gets refused, the trust model, and how recall ranks.

Full CLI reference: kage help --all. Web docs: kage-core.com/guide.html.

Storage

Everything lives in .agent_memory/: packets/ is durable repo memory (git-tracked JSON); graph/, code_graph/, structural/, and indexes/ are rebuildable with kage refresh; reports/ holds the value ledger and health reports. Capture scans for secrets and PII before writing.

Standard format — Open Knowledge Format (OKF). Kage's memory is an OKF bundle: plain Markdown concept files with YAML frontmatter, readable by any OKF consumer (including Google's visualizer). Run kage okf migrate to render the store as an OKF bundle under .agent_memory/okf/. Kage adds the lifecycle OKF leaves out — grounding, verification, and freshness — carried in OKF-legal x-kage-* fields, and can import any third-party OKF bundle. The round-trip is lossless. See OKF_STANDARD.md.

Development

cd mcp
npm install
npm test
npm run build

Contributing & community

Kage is built in the open and we'd love your help. Zero runtime dependencies, no account, no cloud — it's a friendly codebase to jump into.

• CONTRIBUTING.md — dev setup, project layout, conventions.
• ROADMAP.md — where Kage is headed, and where to plug in.
• Good first issues · Help wanted — scoped places to start.
• Discussions — questions, ideas, show-and-tell.

By participating you agree to our Code of Conduct.

License

GPL-3.0-only. See LICENSE. Releases before the GPL switch were MIT.