See what your repo is hiding — 60 seconds, zero setup

npx -y @kage-core/kage-graph-mcp scan --project .

The Truth Report finds duplicate implementations, ghost exports, bus-factor-1
hot files, knowledge voids, and doc lies. On a fresh clone of Express:

Kage Truth Report — express
Scanned 142 files, 3160 symbols, 1 doc file(s)

■ KNOWLEDGE VOID — high churn, zero memory (7, showing top 4)
  • lib/response.js — knowledge void
    390 commits of accumulated decisions, 149 graph edge(s) depending on it —
    and zero memory packets or doc mentions. Agents and new hires fly blind here.
  • lib/application.js — 179 commits x 77 edges, memory packets citing it: 0
  • lib/request.js     — 175 commits x 58 edges, memory packets citing it: 0
  • lib/utils.js       — 107 commits x 35 edges, memory packets citing it: 0

Every finding cites file:line evidence from your code — nothing is generated.

The 30-second trust demo

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

1. Hallucinated citation — REJECTED on write:
   ✗ "Use the helper in src/ghost.ts"
     Citation validation failed: none of the referenced paths exist in this repo.

2. Stale memory (cited file deleted) — WITHHELD from recall:
   ⊘ Legacy retry helper is the fallback
     all cited files deleted since capture: src/legacy-retry.ts

3. Recall returns only grounded, current memory:
   ✓ Payments must be idempotent
   ✓ Auth uses jose, not jsonwebtoken

Receipts, not vibes

Kage keeps a per-repo value ledger and shows you what the memory harness
actually did. kage gains --project .:

This week Kage saved you ~564K tokens (~$8.46), blocked 0 stale memories,
caught 0 stale at change-time, answered 2 recalls.

Agents relay the same receipt after each recall, and the viewer leads with a
Gains tab fed by the same ledger — every number traceable to a logged event.

Trust mechanics

An agent acting on wrong memory is worse than one with none. Kage enforces
trust at three points:

1. Reject on write — a memory citing files that don't exist in your repo is
   refused. Hallucinated citations never enter storage.

2. Withhold on recall — every recall re-verifies cited files. If the
   evidence was deleted, the TTL lapsed, or the memory was reported stale, it is
   suppressed (and shown to you in the viewer, never silently dropped).

3. Stale-catch at change-time — kage pr check (and kage staleguard as a
   pre-commit hook) leads with what your diff just broke:

   ⚠ Your changes invalidated 15 team memories:
     • CI: Kage PR Check must block only on hard-stale memory — cites mcp/kernel.ts (file changed)
     fix: kage learn (update) | kage supersede --packet <id>
   

Prove it on your own repo: kage benchmark --trust --project . measures
hallucination rejection, stale exclusion, and live grounding — 100/100.

The numbers

• 18% faster than grep at equal correctness on real code-navigation tasks
  (N=3 task suite, same agent, same model; reproduce with
  kage benchmark --project . --compare --task "<task>").
• 524 ghost call edges → 0 on Express after import-aware call resolution:
  callees resolve through local scope → imports → package before any name-only
  match, and external-package imports produce no repo edge.
• Real AST extraction for Python, Go, Rust, Java, and Ruby via a
  tree-sitter tier (pure WASM, zero native deps) — on Click, 466 methods
  correctly classified where regex extraction found 0.
• LongMemEval-S retrieval: 96.17% R@5 / 98.72% R@10 with zero dependencies.

Methodology, commands, and caveats: docs/BENCHMARKS.md.

Quick start

Requires Node.js 18+. Two steps to live memory:

npm install -g @kage-core/kage-graph-mcp
cd your-repo
kage init --project .

Then connect your agent (one command writes the MCP + hooks config):

kage setup claude-code --project . --write     # Claude Code
kage setup codex       --project . --write     # Codex
kage setup cursor      --project . --write     # Cursor
kage setup windsurf    --project . --write     # Windsurf
# also: gemini-cli, cline, goose, roo-code, kilo-code, opencode, aider,
#       claude-desktop, generic-mcp — see: kage setup list

Claude Code / Codex users can install the plugin instead:

/plugin marketplace add kage-core/Kage      # then: /plugin install kage@kage
codex plugin marketplace add kage-core/Kage # then: codex plugin add kage@kage

Restart the agent once, then confirm the harness is live:

kage setup verify-agent --agent claude-code --project .

From there it's ambient: the agent recalls grounded memory at task start
(kage_context), captures durable learnings as it works (kage_learn), and
you review memory in the same PR as the code. kage refresh re-grounds after
merges; kage viewer shows gains, trust, and what's being withheld.

The packet lifecycle

Each learning is a packet: reviewable JSON in .agent_memory/packets/,
git-tracked and diffable.

capture → cite-check (reject paths that don't exist) → ground
(fingerprint cited files) → recall (stale memory excluded) → refresh
(re-verify grounding as code changes) → update / supersede / retire.

A packet goes stale when a cited file is missing or changed since verification,
its TTL (365 days) lapsed, or it was reported/deprecated. Soft-stale (linked
code changed) is flagged for review; hard-stale (evidence gone) is withheld
from recall. kage compact prunes dead citations and surfaces duplicates;
kage supersede records lineage when one memory replaces another.

Daily commands

kage recall "how do I run tests" --project .
kage code-graph "who calls createPacket" --project .   # definition + call sites
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

Full CLI and MCP reference: docs.

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.

Development

cd mcp
npm install
npm test
npm run build

License

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