Kage

Kage is an orchestrator for coding agents, built on top of a memory layer. The core goal is to stop coding agents from repeatedly re-understanding your codebase, and from acting on outdated knowledge.

Main capabilities

1. Persistence and sharing of memory: As the agent works, Kage captures what it learns (decisions, bug fixes, conventions, code structure relationships) as Open Knowledge Format (OKF) concept files, committed in the repository's .agent_memory/ directory. The next session (whether yours or a teammate's) starts already knowing this content, with no need to re-read or re-ask. Memory is shared through git and is collaborative.

2. Code verification: Every memory references its corresponding code, and Kage checks these references at write time, at recall time, and when a diff changes code. A memory that references a nonexistent file is rejected on the spot; when a diff changes code referenced by a memory, that memory is flagged at the commit/PR stage (kage pr check) and shielded from recall until it is re-verified or replaced, preventing memory from silently rotting.

3. Orchestration and delegation: Declare an intent, and Kage's orchestrator generates a brief for the coding agent from the repository's own memory, runs it in an isolated git worktree—either as a single run or as multi-wave goals—and then Kage itself re-runs the checks (tests, diff size, references) rather than trusting the agent's self-report. kage merge only merges code when the declaration holds, and confirms what the agent learned, making the next brief (yours or a teammate's) start smarter.

4. Standards and portability: Memory consists of OKF-compliant plain Markdown files with YAML frontmatter, viewable in the same PR as code review, readable by any OKF tool, and not locked into a particular machine or vendor cloud. The store can be rendered as an OKF bundle under .agent_memory/okf/ via kage okf migrate, and any third-party OKF bundle can be imported losslessly. Kage's trust metadata is kept in OKF-legal x-kage-* fields, remaining 100% compatible.

How to use

Run one command inside the repository, then restart the agent to complete the entire installation: npx -y @kage-core/kage-graph-mcp install. It creates .agent_memory/, builds the code graph, writes AGENTS.md / CLAUDE.md policies to tell agents to use Kage, automatically detects and wires up agents, and configures .gitignore and the packet merge driver. Requires Node.js 18+, no account or API key needed. You can also just have your agent complete the setup by following the prompt.

After installation, Kage runs at the environment level with no manual execution needed: at the start of a task (and when an agent opens a file) it automatically recalls relevant and verified memories, while stale or deleted memories are excluded; during work it captures durable learnings as packets; and it stays honest when code changes. You can use kage viewer to observe packets, the memory↔code graph, trust gates, and the live event stream in a local dashboard. Wrapping content in <private>...</private> means it will not be stored.

Other commands and interfaces: kage app --project <dir> starts or reuses the local daemon and opens the UI, including the same room, run board, and memory view; from a checkout you can run it in a native window with npm start --prefix shell (a thin Electron shell, with no HTML of its own). The daemon can bind to a LAN address, but every request (including reads) requires a pairing key; currently you must manually set "lan": true in .agent_memory/config.json, and there is not yet a --lan flag or app toggle. kage projects add <dir> --agent claude lets you register another repository without a terminal. macOS (arm64 only) has an unsigned .dmg native shell; on first launch it will warn about an "unidentified developer," and you need to right-click and choose Open in Finder.

Use cases and limitations

Suitable for teams using coding agents that want to share verified code knowledge within the repository, avoid repeatedly explaining the codebase, and avoid acting on stale memories. Repository contents require Node.js 18+; Windows/Linux packaging has not been built yet; LAN access requires manual configuration; no account, no database, no API key. The retrieval path itself has no dependencies (BM25 + sparse lexical scoring, no embeddings, no network). The license is GPL-3.0-only; versions before the GPL switch were MIT.

Performance and validation data (from the materials)

18% faster than grep on real code navigation tasks (with equal correctness, N=3 suites, same agent/model). LongMemEval-S retrieval: 98.72% R@10 / 99.79% R@20 / 0.909 MRR, leading BM25 at every depth except R@5 (96.17% vs BM25's 96.60%). Memory correctness under change: 0% stale serving (memories whose code has been deleted or changed are blocked), versus 100% for capture-everything stores. Trust benchmark: 100/100, covering hallucination refusal, stale exclusion, and live grounding.