Kage is a verified memory layer for coding agents that captures, stores, and recalls team knowledge grounded in your codebase — stored as plain files in your repo with zero dependencies or cloud accounts required.
Recall verified memory & query code/knowledge graphs (kage_context): The primary entry point — validates memory health, recalls relevant memory packets, and queries both the code and knowledge graphs. Call at the start of every task.
Capture verified learnings (kage_learn): Store durable, reusable insights (decisions, bug fixes, conventions, gotchas, runbooks) as verified memory packets linked to specific repo files; hallucinated or missing path citations are rejected at write time.
Assess file modification risk (kage_risk): Evaluate risk before editing files by surfacing dependents, impact surface, churn, ownership, co-change partners, and test gaps.
Trace dependency paths (kage_dependency_path): Find how two files are connected in the code graph (direct, reverse, or undirected).
Summarize decision memory (kage_decisions): Get an overview of captured decisions, gotchas, runbooks, and conventions, plus identify high-traffic code paths lacking documented knowledge.
Search committed documentation (kage_docs_search): BM25-ranked search over the repo's own committed docs (README, markdown files) using a local index.
Rebuild indexes and graphs (kage_refresh): Refresh the code graph, memory graph, indexes, metrics, and stale-memory metadata after meaningful file changes.
Check memory readiness for merge (kage_pr_check): Verify memory, code graph, and stale-memory state before a PR merge, surfacing any team memories invalidated by current changes.
Supersede outdated memory (kage_supersede): Replace an old memory packet with a corrected one, preserving bidirectional lineage while withholding the superseded packet from future recall.
Codify memory into agent skills (kage_skills): Convert durable, verified memory into SKILL.md files that every teammate's agent auto-loads from git.
Rate recalled memory (kage_feedback): Mark recalled packets as helpful, wrong, or stale to tune trust scores and improve future recall quality.
State an intent. Kage's orchestrator briefs a coding agent from your repo's own memory, runs it in an isolated git worktree — a single run or a multi-wave goal — and re-runs the checks itself rather than trusting the agent's report:
┌ 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)
└────────────────────────────────────────────────────────────────A real receipt from this repo's own run history. Every row is a command Kage ran or a fact
it inspected — never a claim the agent made about itself. kage merge only lands the code once
the claim holds, and ratifies what the agent learned, so the next brief, yours or a teammate's,
starts smarter.
That memory is the decisions behind your codebase, the runbook for a tricky deploy, the root cause of a gnarly bug — captured as your agents work and checked against the actual code, so what gets reused stays true. It's kept as plain Markdown files in your repo, conformant to the Google Open Knowledge Format (OKF) so there's no lock-in, and shared with your whole team through git. No account, no database, no API key.
npx -y @kage-core/kage-graph-mcp installWorks with Claude Code · Codex · Cursor · Windsurf · Gemini CLI · Cline · Goose · Roo Code · Kilo Code · OpenCode · Aider · Claude Desktop · Copilot · OpenClaw · Hermes · any MCP client
🌐 English · 简体中文 · 日本語 · 한국어 · Español · Português (Brasil) · Français · Deutsch · हिन्दी
One command, inside your repo, then restart your agent. That's the whole setup.
npx -y @kage-core/kage-graph-mcp installIt 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.
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 .Related MCP server: Agent Memory Bridge
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 learnedEvery run works in its own git worktree. The checks that decide the verdict on the receipt above — tests, diff size, citations — are commands Kage runs itself, never the agent's self-report.
The app. kage app --project <dir> starts (or reuses) the local daemon and opens the
same room, runs board, and memory view in a UI. From a checkout, npm start --prefix shell
runs it as a native window — a thin Electron shell with no HTML of its own, it just loads the
daemon's own page — and npm run dmg --prefix shell builds a macOS .dmg (arm64 only;
Windows/Linux packaging isn't built yet).
From your phone. The daemon can also bind to your machine's LAN address, gated by a
pairing secret required on every request, reads included. Today that means setting
"lan": true in .agent_memory/config.json by hand — there's no --lan flag or app toggle
yet.
Add a project without a terminal. kage projects add <dir> --agent claude registers
another repo the same way the app's "+" button does, then kage app --project <dir> opens it.
kage app --project <dir>
kage projects add <dir> --agent claudeA thin native shell (macOS, arm64 only) over the same daemon the CLI runs — dock presence,
a global hotkey, native notifications. Download the latest .dmg from
GitHub releases (look for a
Kage-<version>.dmg asset).
Unsigned builds show macOS's "unidentified developer" prompt on first launch — right-click the app in Finder and choose Open once. Once installed, it checks for updates on launch and every 4 hours and installs on restart; ad-hoc (unsigned) builds can't self-install and notify you instead, linking back to the releases page.
Prefer the CLI? The one-line install works everywhere the app doesn't need to:
npx -y @kage-core/kage-graph-mcp installKage is an orchestrator for coding agents, built on a memory layer. 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.
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.
Once installed, it's ambient. You don't run anything by hand:
Recall before acting. At the start of a task (and the moment the agent opens a file), Kage surfaces the relevant verified memory for it. Stale or deleted memory is left out.
Capture as it works. Durable learnings become packets. A memory that cites a file which doesn't exist is rejected on the spot, so hallucinations never enter storage.
Stay honest as the code moves. When a diff changes code that a memory cites, that
memory is flagged at commit/PR time (kage pr check) and withheld from recall until it's
re-verified or replaced, so knowledge can't quietly rot.
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.
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.
Kage | claude-mem | mem0 / Zep | |
Automatic capture + session-start recall | ✓ | ✓ | via SDK |
Hallucinated citations rejected at write time | ✓ | — | — |
Stale memory withheld at recall (cited files deleted/changed, TTL, reported) | ✓ | — | — |
Diff-time stale-catch, warned before the PR when your change breaks a memory | ✓ | — | — |
Memory reviewed in git, same PR as the code (plain files, no DB) | ✓ | SQLite + cloud | hosted API |
Codify memory into team | ✓ ( | — | — |
Cross-machine sync | ✓ your own git remote | their cloud | their cloud |
Account / API key required | none | cloud optional | yes |
Truth Report. kage scan reads any repo in ~60s 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.
18% faster than grep at equal correctness on real code-navigation tasks (N=3 suite,
same agent/model; reproduce with kage benchmark --project . --compare).
LongMemEval-S retrieval: 98.72% R@10 / 99.79% R@20 / 0.909 MRR — ahead of plain BM25 at every depth except R@5, where BM25 edges it (96.60% vs 96.17%; full table in benchmarks/LONGMEMEVAL.md). The retrieval path itself is dependency-free: BM25 + sparse lexical scoring, no embeddings, no network.
Memory Correctness Under Change: 0% stale-served (memory whose code was deleted or changed is withheld), vs 100% for capture-everything stores.
Trust benchmark: 100/100, covering hallucination rejection, stale exclusion, and live
grounding (kage benchmark --trust --project .).
Methodology, commands, and caveats: 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 bundleFull CLI and MCP reference: docs. Delegating work to coding agents (dispatch → verified claim → merge): docs/DELEGATION.md.
Everything lives in .agent_memory/: packets/ is durable repo memory (git-tracked OKF Markdown);
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.
cd mcp
npm install
npm test
npm run buildKage is built in the open and we'd love your help. Four runtime dependencies (the retrieval core uses none), 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.
GPL-3.0-only. See LICENSE. Releases before the GPL switch were MIT.
Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task; it answers caller/usage questions from the code graph too, so you rarely need a separate graph tool.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max memory packets to return (default 5) | |
| query | Yes | The task or question — used for both memory recall and code graph search | |
| targets | No | Optional files the agent may edit or explain; used for risk context | |
| session_id | No | Optional active agent session id for memory reconciliation | |
| project_dir | Yes | Absolute path to the project root | |
| changed_files | No | Optional changed files for pre-edit or PR risk context |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description correctly implies non-destructive behavior. It adds context about combined functionality and code graph answers, which is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy, front-loaded with core purpose, then usage guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no output schema, many siblings), the description adequately covers purpose and usage. Lacks detail on return format but acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra semantic context for individual parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is the primary entry point that validates memory health, recalls packets, and queries code/knowledge graphs. It distinguishes itself from sibling tools by aggregating multiple functions into one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to call at the start of every task and notes it reduces the need for a separate graph tool, providing clear when-to-use and implicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize the repo's 'why' memory at a glance: the decisions, gotchas, runbooks, conventions, and code explanations Kage has captured, plus which high-traffic code paths still have no decision memory. Use it to brief yourself on a repo before changing it, or to audit where institutional knowledge is thin or going stale. Read-only: returns grouped entries with titles, types, cited file paths, and call-outs for weak, stale, or undocumented hot paths. Does not modify any memory.
| Name | Required | Description | Default |
|---|---|---|---|
| project_dir | Yes | Absolute path to the repository root to summarize. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the annotation's readOnlyHint by stating 'Read-only' and 'Does not modify any memory.' It also details the return format (grouped entries with titles, types, etc.) and mentions call-outs for weak or undocumented hot paths, providing rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, usage guidance, and behavioral notes. It could be slightly more concise but remains focused and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context: it explains what the tool returns, its use cases, and that it is read-only. This is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'project_dir' is fully described in the schema as 'Absolute path to the repository root.' The description does not add any additional semantics beyond what the schema provides, so it meets baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as summarizing the repo's 'why' memory, listing specific content types (decisions, gotchas, conventions) and distinguishing its purpose from sibling tools like kage_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'to brief yourself on a repo before changing it' and 'to audit where knowledge is thin.' It implies not to use it for modification but does not list alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find how two files are connected in Kage's source-derived code graph. Reports direct dependency direction, reverse impact direction, or undirected graph connection.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Target file path or unique suffix | |
| from | Yes | Source file path or unique suffix | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description's 'reports' is consistent. However, the description does not disclose what happens if no path exists or other edge cases, which would enhance transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-front-loaded sentence that communicates the core functionality with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main use case but lacks details on return format, error handling, or edge cases. Given no output schema, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description adds no additional parameter meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding how two files are connected in a code graph, specifying three types of directions. This is distinct from sibling tools which focus on context, decisions, docs, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for understanding file dependencies but does not explicitly state when to use this tool over others or provide exclusions. Usage is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this repo's OWN committed documentation (README, docs/**, *.md, common doc dirs — including any framework/API docs checked into the repo). BM25 over heading-anchored chunks from .agent_memory/indexes/docs-index.json. Returns ranked doc hits with doc_path, heading, line, and snippet. This indexes only files on disk in the project, never the internet.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max ranked doc hits to return (default 5). | |
| query | Yes | Search terms to match against the repo's documentation. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true. The description adds algorithmic details (BM25, heading-anchored chunks), indexing scope (only files on disk), and output format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose, and each sentence adds distinct value: what is searched, how it works, what is returned, and what is not indexed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return fields and indexing source. It covers all essential aspects: scope, algorithm, constraints, and output, making it complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds meaning by explaining query as search terms, project_dir as absolute path, limit with default, and returns doc_path, heading, line, snippet. It also describes the indexing source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches committed documentation in the repo, using BM25 over heading-anchored chunks, and returns ranked results with specific fields. It distinguishes from internet search by specifying it indexes only files on disk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing info from the project's own docs and explicitly says 'never the internet,' which helps avoid misuse. It does not explicitly mention when to use alternatives among siblings, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record how useful a recalled repo-local memory packet was, which tunes Kage's trust and future recall. 'helpful' reinforces the packet, 'wrong' flags it as disputed, and 'stale' marks it for re-verification and withholds it from recall until refreshed. Use it right after a recalled packet helped you, misled you, or no longer matched the code. Mutates the packet's quality signals on disk.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | helpful = it was accurate and useful; wrong = it was incorrect (flag as disputed); stale = it no longer matches the code (mark for re-verification). | |
| packet_id | Yes | Id of the memory packet you are rating. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool 'Mutates the packet's quality signals on disk,' which is consistent with the readOnlyHint:false annotation. It also explains the effects of each kind (helpful, wrong, stale), providing full transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, then usage guidance, and ends with behavioral disclosure. Every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 simple parameters, no output schema, and clear annotations, the description covers purpose, usage, behavior, and parameter semantics completely. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of each enum value (helpful, wrong, stale) and their consequences, which is not fully captured in the schema descriptions. However, the schema already describes the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record how useful a recalled repo-local memory packet was' and identifies the resource as memory packets. It distinguishes from sibling tools like kage_learn (which adds knowledge) or kage_refresh (which updates) by focusing on feedback/rating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it right after a recalled packet helped you, misled you, or no longer matched the code,' providing clear when-to-use guidance. It does not explicitly mention when not to use or compare to alternatives, but the context and sibling tools make the distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a durable, reusable learning from the current session as a verified repo-local memory packet (committed under .agent_memory/, shared with the team via git). Use it the moment you discover something a future session should know: a decision and its rationale, a bug's root cause and fix, a convention, or a setup step. Prefer it over diff-based proposals when you already know what was learned. The write is rejected if every cited path is missing from the repo (set allow_missing_paths for a file you are about to create), and secrets/PII are scanned out before writing. Returns the new packet id plus any contradiction warnings against existing memory.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional keywords to aid future recall. | |
| type | No | Memory type: decision, bug_fix, runbook, convention, gotcha, workflow, code_explanation. Inferred if omitted. | |
| paths | No | Repo files this memory is about; used to verify the citation now and to recall the memory when those files are touched later. | |
| stack | No | Optional technologies/frameworks the learning relates to. | |
| title | No | Short headline for the packet. Derived from the learning if omitted. | |
| evidence | No | How the learning was confirmed (e.g. test output, a reproduced behavior). | |
| learning | Yes | The insight to store, in full sentences: what was learned and why it matters to a future session. | |
| graph_nodes | No | Optional code-graph symbol or file ids this memory is grounded to. | |
| project_dir | Yes | Absolute path to the repository root. | |
| verified_by | No | What verified it (e.g. a command run, a passing test, a reviewer). | |
| discovery_tokens | No | Approximate token cost of producing this knowledge (exploration + reasoning). Stored on the packet so recall receipts can report replay value; a conservative per-type default is estimated when omitted. | |
| allow_low_quality | No | Admit this capture even though its computed quality score is below the admission floor (60). The write is otherwise rejected — this is the explicit override. | |
| allow_missing_paths | No | Allow the write even if cited paths do not exist yet (e.g. a file you are about to create). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details beyond the readOnlyHint=false annotation: the write commits under .agent_memory/, rejects writes when cited paths are missing, scans for secrets/PII before writing, and returns the new packet id plus contradiction warnings. This gives an agent a clear picture of side effects, validation, and output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient: it front-loads the core action, then gives usage timing, a preference rule, behavioral caveats, and the return value. Every sentence earns its place with no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter tool with no output schema, the description provides a complete mental model: what the tool does, when to use it, its side effects, its validation rules, and what it returns. The rich schema descriptions fill in the remaining parameter-level details, so an agent has enough to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful operational meaning for paths and allow_missing_paths by explaining the rejection condition and when to set the flag. It does not add semantics for every parameter, but the schema already covers the remaining ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: capturing a durable, reusable learning as a repo-local memory packet committed under .agent_memory/. It is precise about the object and purpose, though it does not explicitly differentiate among the sibling tools like kage_supersede or kage_skills; it only contrasts with diff-based proposals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use-case guidance: use it the moment you discover something a future session should know, with concrete examples such as decisions, bug root causes, conventions, and setup steps. It also says to prefer it over diff-based proposals when you already know what was learned, but it does not describe when-not-to-use it relative to named sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. Leads with a human summary of team memories invalidated by the current change — relay it to the developer. On a repo with many stale packets, validation findings, or reconciliation items, those lists are each capped to the 10 most actionable entries by default (stale packets ranked by urgency), with true totals and truncation notes; pass limit or verbose for more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entries per capped list to return (default 10 each). | |
| verbose | No | Return every entry in every list, uncapped. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by disclosing important behaviors: results are capped to 10 actionable entries by default, stale packets are ranked by urgency, true totals and truncation notes are included, and the output leads with a human summary that should be relayed. It also explains how limit and verbose alter behavior. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized, front-loading the core purpose in the first sentence and then adding behavioral details in subsequent sentences. Every sentence contributes essential information about what the tool returns and how to control output size. Nothing feels redundant or wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does a strong job of explaining the return shape: a human summary first, then capped lists with totals and truncation notes. It does not explicitly describe the overall readiness verdict format, but the purpose statement conveys that a merge-ready assessment is returned. This is sufficient for an agent to invoke the tool and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful value by explaining the default cap of 10, the urgency ranking for stale packets, that verbose returns everything uncapped, and that limit adjusts the cap. This goes beyond the schema's simple descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: it checks whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. This distinguishes it from siblings like kage_context, kage_risk, or kage_refresh, which have different purposes. The title reinforces the same intent without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use during PR/merge preparation, as it evaluates merge readiness for the current change. It explains what happens on repos with many stale packets and how to get more results, but it does not explicitly name excluded alternatives or state when a sibling tool should be chosen instead. This is clear context with no exclusions, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh. On non-default git branches metadata-only packet rewrites are skipped (quiet refresh) to avoid merge conflicts; pass force to persist them anyway. On a repo with many stale packets or validation warnings, stale_packets and validation.warnings are capped to the 10 most actionable entries by default (ranked by urgency), with the true total and a truncation note; pass limit or verbose for more.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Persist packet metadata rewrites even on a non-default branch | |
| limit | No | Max stale_packets / validation.warnings entries to return (default 10 each). | |
| verbose | No | Return every stale packet and validation warning, uncapped. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint and readOnlyHint annotations, the description discloses substantial behavior: the quiet-refresh mechanism for non-default branches, the capping of stale_packets/validation.warnings to 10 entries with truncation notes, and the effect of limit/verbose. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: it opens with the core action, then covers usage timing, branch-specific behavior, and output truncation in a logical flow. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the main operational concerns: when to run, how branch affects behavior, output capping, and override options. It implies the return includes stale_packets and validation.warnings, which is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds nuance to force (persists rewrites on non-default branches), limit (caps entries), and verbose (uncaps), which go beyond the schema's basic field descriptions. It does not elaborate on project_dir, but that is self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb-resource combination: 'Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata.' It clearly states what the tool does and distinguishes it from siblings like kage_pr_check by positioning it as a pre-PR maintenance step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit timing rules are given: 'run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh.' It also explains when to override the quiet refresh (pass force) on non-default branches, leaving no ambiguity about invocation conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assess modification risk for files using Kage's code graph plus local git history: dependents, impact surface, churn, ownership, co-change partners, and test gaps. Use before editing hotspot or shared files.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | No | File paths to assess | |
| project_dir | Yes | Absolute path to the repository root. | |
| changed_files | No | Optional PR/branch changed files. If targets is omitted, these are assessed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, signaling a safe read operation. The description adds value by detailing the method ('Kage's code graph plus local git history') and the specific risk factors assessed, without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence front-loads the core purpose, and the second provides usage advice. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the analysis dimensions (dependents, impact surface, etc.), giving a good idea of the output content. However, without an output schema, it does not specify the exact return format (e.g., score, report), leaving a minor gap for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already clearly documented. The tool description does not add additional meaning beyond what the schema provides for each parameter, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Assess modification risk') and resource ('files'), and lists concrete analysis dimensions (dependents, impact surface, churn, etc.). It distinguishes itself from sibling tools like kage_context or kage_decisions by focusing on risk, not context or decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use before editing hotspot or shared files.' This provides clear context, but it does not mention alternatives or when not to use it, which would be expected for a top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Codify durable, verified repo memory (runbooks, workflows, actionable decisions) into git-native SKILL.md files under .claude/skills/ that every teammate's agent auto-loads. Only grounded, non-stale packets become skills. Pass dry_run to preview without writing. dir overrides the output directory.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Override the output directory (default .claude/skills/). | |
| dry_run | No | Preview which skills would be written without creating any files. | |
| project_dir | Yes | Absolute path to the repository root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals it writes files (non-read-only) and filters packets, matching idempotentHint. But it does not describe overwrite behavior or what happens on conflict, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, front-loading the core purpose in the first sentence. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the main action and parameters, it lacks details on return value or error handling. Given no output schema and the tool's write nature, additional clarity on outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no new semantic information beyond what is in the schema, making baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: creating SKILL.md files from repo memory. It specifies the target location (.claude/skills/) and the selection criteria (only grounded, non-stale packets). This distinguishes it from siblings like kage_context or kage_decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by mentioning dry_run for previewing and dir for output override. However, it lacks explicit 'when not to use' or comparison with sibling tools, which would enhance differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace one repo-local memory packet with a newer one that corrects or obsoletes it. Marks the old packet superseded, links it to the replacement, and writes bidirectional lineage edges so the history stays traceable. Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts. Mutates both packets on disk: the superseded packet is withheld from recall but kept for lineage. Returns ids, paths, and titles for confirmation, not the full packet bodies.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional human note recorded on the lineage edge explaining why it was superseded. | |
| packet_id | Yes | Id of the existing packet to retire (the one being replaced). | |
| project_dir | Yes | Absolute path to the repository root. | |
| replacement_packet_id | Yes | Id of the newer packet that wins and stays active. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses significant side effects: it marks the old packet superseded, writes bidirectional lineage edges, keeps the old packet but withholds it from recall, and mutates both packets on disk. It also clarifies that it returns only ids, paths, and titles rather than full packet bodies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, with each sentence forwarding a distinct fact: purpose, behavior, when to use, and output expectations. No filler or redundant restating of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema, the description covers effect, lineage behavior, return value shape, and usage conditions. An agent has enough information to invoke it correctly and understand the consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with meaningful descriptions, so the description benefits from full coverage. The description reinforces the roles of old and replacement packet, but does not add substantial detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and object—'Replace one repo-local memory packet with a newer one'—and clarifies what that means by describing the suspension and lineage updates. It distinguishes itself from deletion and from other kage tools by specifying its unique job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts.' This gives concrete selection criteria and points to an alternative behavior to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct concern: context gathering, decision summaries, dependency paths, documentation search, memory feedback, learning, PR checks, index refresh, risk assessment, skills creation, and memory superseding. There is no overlap in purpose; an agent can clearly select the right tool for each task.
All tools share the 'kage_' prefix, but the second part mixes nouns (context, decisions, feedback, risk, skills) and verbs (learn, refresh, supersede) as well as compound names (dependency_path, docs_search, pr_check). This mixed convention is still readable but lacks a consistent verb_noun pattern.
With 11 tools, the set is well-scoped. Each tool earns its place by covering a distinct aspect of the domain (memory management, code graph analysis, documentation, project checks). The count is within the ideal 3-15 range and feels neither bloated nor sparse.
The tool surface covers the core lifecycle: learn (create), context/decisions/docs_search (retrieve), feedback/supersede (update), and supersede (effective delete via obsoletion). Minor gaps include the lack of an explicit tool to list all memory packets or to delete them outright, but these are workable via existing tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared memory for coding agents. Stop re-explaining your codebase every session.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
shared AI-context layer for teams — persistent memory your agents search and update over MCP
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kage-core/Kage'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
