The guide

Four commands from clone to measured value.

Kage is a local-first memory harness: install it in a repo, put your agents behind one proxy, and let verified memory accumulate as you work. Nothing here needs an account or an API key, and every claim on this page has a command you can run to check it.

Step 1

Install — and get your first answer immediately

kage install initializes .agent_memory/ (plain OKF markdown, reviewable in git), builds the code and recall indexes, writes the repo policy files (AGENTS.md + CLAUDE.md) so every teammate's agent uses Kage, and wires the agents it detects on your machine.

terminal
$ npm install -g @kage-core/kage-graph-mcp
$ kage install
Kage installed in ~/code/your-repo

  Memory      .agent_memory/ created — packets are plain files, reviewable in git
  First win   starter runbook captured ("How to run, build and test your-repo") — try it now:
                kage context "how do I run the tests"
  Indexes     3 built (code graph, recall, structure)
  Policy      AGENTS.md + CLAUDE.md written — commit these so every teammate's agent uses Kage
  Agents      claude-code ✓ wired

The "first win" is real, not staged: install derives one runbook from your package.json scripts — verifiable ground truth — so the very first recall answers usefully instead of returning nothing. A repo with no runnable scripts gets an honest no-op.

Step 2

One proxy, every agent

kage up starts the background proxy once. Any agent that speaks one of the three wire formats flows through it with zero per-agent plugins:

Anthropic wire

Claude Code, aider, and any /v1/messages client via ANTHROPIC_BASE_URL.

OpenAI-compatible wire

Codex CLI, Cursor, and any /v1/chat/completions client via its base-URL setting.

Gemini wire

Gemini CLI and any :generateContent client — including streamed responses.

terminal
$ kage up
# audit mode by default: measurement only, your bytes forwarded untouched
$ kage run -- claude   # or any agent, with its base URL pointed at the proxy

The default is audit: Kage measures and changes nothing. Injection (assist) and reversible compression (protect) are explicit opt-ins, and assist refuses to start if the reversible store is unhealthy. If anything inside Kage fails, the proxy forwards your original bytes — fail-open is tested, not promised.

Step 3

Work normally — the memory loop runs itself

Capture

Durable learnings — decisions with their why, gotchas, dead ends, run recipes — are captured as OKF packets. Admission filters what your code already says: a body that merely restates its cited files routes to review instead of trusted recall, because the store audit measured that class at ~0 uses. Kage keeps what code cannot say.

Verify

Every memory is checked against the real repository, deterministically — no model in the verdict path. When cited code changes, the memory is re-checked; when it can no longer be trusted, it is withheld with a stated reason instead of misleading an agent.

Inject

Recall decides from its own score distribution whether the top memory clears this store's noise band — "inject nothing" is a first-class outcome. On the acceptance bench the false-injection rate is 0, with recall held at 1.0.

Receipts

Every request gets a receipt: bytes and tokens measured or absent, never estimated into existence. Estimated figures (like rediscovery-cost heuristics) are always labelled estimates.

Step 4

Ask whether it is actually helping

kage report team is the lead-facing answer, assembled only from local ledgers. Measured counts stay separate from labelled estimates; sections with no data say unavailable instead of fabricating a zero.

kage report team measured
Recalls served139
Stale memory withheld260
Live injection gaterate + confidence, per decision
Store compositionby derivability class
Dark areassubsystems with zero memory
Counts above are from this repository's own store — run it on yours.

The same report renders in the local portal (kage open) for leads, with an IC transparency view: what attached to your session, at what confidence — including the "injected nothing" decisions.

Teams

Share memory without trusting anyone blindly

Memory travels in git — a teammate who clones the repo already has it. The optional team workspace adds review authority on top: only approved model records sync (raw prompts never leave the machine), a proposer cannot approve their own high-impact claim, replays are idempotent, and everything lands in an append-only audit log. These invariants are enforced by tests against a real PostgreSQL — cross-tenant reads, raw payloads synced, self-approvals, duplicate syncs, and invalid webhooks all assert to zero, and local memory keeps working when the workspace is down.

See every number's receipt Back to quickstart

Reference

The commands you will actually use

cheat sheet
$ kage install            # one-shot: init + index + wire detected agents
$ kage up                 # background proxy + runtime (audit by default); kage down stops it
$ kage run -- <agent>     # run any agent through the proxy
$ kage context "query"    # validate + recall + code graph in one call
$ kage check              # verify docs/memory claims against the code — counted, not estimated
$ kage report team        # the "is this helping?" report
$ kage status             # memory + runtime health, measurement coverage
$ kage open               # the local portal (review queue, receipts, team value)

Privacy: everything above is local-first. No account, no API key, no telemetry. The store is plain markdown you can read, diff, and delete; export works even if you later use the paid workspace and stop paying.

Go deeper: Using Kage — the full manual (setup, proxy, daily use, team workflow, troubleshooting) · How it works — the mechanism end to end (delivery channels, proxy modes, what is stored and what is refused, the trust model, how recall ranks). Full CLI surface: kage help --all.