Expresa una intención. El orquestador de Kage instruye a un agente de codificación a partir de la memoria de tu propio repositorio, lo ejecuta en un worktree de git aislado — una ejecución única o un objetivo de múltiples oleadas — y vuelve a ejecutar las comprobaciones él mismo en lugar de confiar en el informe del agente:
┌ 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)
└────────────────────────────────────────────────────────────────Un comprobante real del historial de ejecución de este propio repositorio. Cada fila es un comando que Kage ejecutó o un hecho que inspeccionó — nunca una afirmación que el agente hizo sobre sí mismo. kage merge solo integra el código una vez que la afirmación se cumple, y ratifica lo que el agente aprendió, para que la siguiente instrucción, la tuya o la de un compañero, comience con más conocimiento.
Esa memoria son las decisiones detrás de tu base de código, el runbook para un despliegue complicado, la causa raíz de un bug espinoso — capturada mientras tus agentes trabajan y contrastada con el código real, para que lo que se reutiliza siga siendo fiel. Se mantiene como archivos Markdown simples en tu repositorio, conforme al Google Open Knowledge Format (OKF) para que no haya dependencia de un proveedor, y se comparte con todo tu equipo a través de git. Sin cuenta, sin base de datos, sin clave de API.
npx -y @kage-core/kage-graph-mcp installFunciona con Claude Code · Codex · Cursor · Windsurf · Gemini CLI · Cline · Goose · Roo Code · Kilo Code · OpenCode · Aider · Claude Desktop · Copilot · OpenClaw · Hermes · cualquier cliente MCP
🌐 English · 简体中文 · 日本語 · 한국어 · Español · Português (Brasil) · Français · Deutsch · हिन्दी
Un solo comando, dentro de tu repositorio, y luego reinicia tu agente. Eso es toda la configuración.
npx -y @kage-core/kage-graph-mcp installCrea .agent_memory/, construye el grafo de código, escribe la política AGENTS.md / CLAUDE.md que indica a los agentes que usen Kage, detecta y conecta automáticamente a tus agentes, y configura .gitignore + el controlador de fusión de paquetes. Requiere Node.js 18+. Sin cuenta, sin clave de API.
O simplemente pídele a tu agente que lo configure. Pega esto en Claude Code, Cursor o cualquier agente de codificación:
Configura Kage (memoria verificada para agentes de codificación, https://github.com/kage-core/Kage) en este repositorio: ejecuta
npx -y @kage-core/kage-graph-mcp instally luego dime que te reinicie.
# 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 learnedCada ejecución trabaja en su propio worktree de git. Las comprobaciones que deciden el veredicto del comprobante anterior — pruebas, tamaño del diff, citas — son comandos que Kage ejecuta por sí mismo, nunca el autoinforme del agente.
La aplicación. kage app --project <dir> inicia (o reutiliza) el daemon local y abre la misma sala, el panel de ejecuciones y la vista de memoria en una interfaz. Desde un checkout, npm start --prefix shell lo ejecuta como una ventana nativa — un shell ligero de Electron sin HTML propio, solo carga la página del propio daemon — y npm run dmg --prefix shell genera un .dmg de macOS (solo arm64; el empaquetado para Windows/Linux aún no está creado).
Desde tu teléfono. El daemon también puede vincularse a la dirección LAN de tu máquina, protegido por un secreto de emparejamiento requerido en cada solicitud, incluidas las lecturas. Hoy eso significa establecer "lan": true en .agent_memory/config.json manualmente — todavía no hay una bandera --lan ni un interruptor en la aplicación.
Añade un proyecto sin terminal. kage projects add <dir> --agent claude registra otro repositorio de la misma manera que el botón "+" de la aplicación, y luego kage app --project <dir> lo abre.
kage app --project <dir>
kage projects add <dir> --agent claudeUn shell nativo ligero (macOS, solo arm64) sobre el mismo daemon que ejecuta la CLI — presencia en el dock, una tecla de acceso rápido global, notificaciones nativas. Descarga el último .dmg desde GitHub releases (busca un recurso Kage-<version>.dmg).
Las compilaciones sin firmar muestran el aviso de "desarrollador no identificado" de macOS en el primer lanzamiento — haz clic derecho en la aplicación en Finder y elige Abrir una vez. Una vez instalada, busca actualizaciones al iniciar y cada 4 horas, y las instala al reiniciar; las compilaciones ad-hoc (sin firmar) no pueden autoinstalarse y te notifican en su lugar, con un enlace de vuelta a la página de lanzamientos.
¿Prefieres la CLI? La instalación de una línea funciona en todos los sitios donde la aplicación no es necesaria:
npx -y @kage-core/kage-graph-mcp installKage es un orquestador para agentes de codificación, construido sobre una capa de memoria. Mientras tu agente trabaja, captura lo que aprende (decisiones, correcciones de errores, convenciones, cómo encaja el código) como archivos de concepto en Open Knowledge Format (OKF) confirmados en tu repositorio bajo .agent_memory/. La siguiente sesión (la tuya o la de un compañero) comienza ya sabiéndolo, en lugar de volver a leer o volver a preguntar.
Tres cosas lo hacen diferente de otras herramientas de memoria:
Es colaborativo. El conocimiento que una persona (o su agente) descubre se convierte en el de todo el equipo. La memoria se comparte a través de git, así que la siguiente sesión de un compañero comienza con lo que acabas de aprender, no con una pizarra en blanco.
Es estándar y nativo de git. La memoria es un paquete OKF conforme — Markdown simple en tu repositorio, revisado en el mismo PR que el código, legible por cualquier herramienta OKF — no encerrado en una máquina ni en la nube de un proveedor. Tu conocimiento sigue siendo tuyo.
Está verificada. Cada memoria cita el código del que trata, y Kage comprueba esas citas contra tus archivos reales en el momento de escritura, en el momento de recuperación y cuando un diff cambia el código. La memoria que ya no coincide con el código se retiene, para que el agente nunca actúe sobre una afirmación obsoleta.
Desde el primer día, Kage mantuvo la memoria de los agentes como archivos simples en tu repositorio — sin nube, sin base de datos, sin dependencia de proveedor, mientras todos los demás construían nubes de memoria. En junio de 2026, Google Cloud lanzó el Open Knowledge Format: conocimiento como Markdown en git, neutral respecto al proveedor, sin cuenta — la tesis exacta sobre la que Kage ya se basaba. Así que Kage adoptó OKF como su estándar y lo potencia con la capa que OKF deliberadamente omite:
Verificación — OKF almacena lo que escribiste; Kage comprueba cada concepto contra tu código real y rechaza las citas alucinadas en el momento de escritura.
Actualidad — OKF no tiene noción de obsolescencia; Kage detecta la desviación en el momento en que tu código cambia y retiene la memoria que ya no es cierta.
Anclaje al código — un grafo de código determinista ancla cada concepto a los símbolos exactos que describe — la capa que OKF deja a las herramientas.
Los metadatos de confianza viajan en campos x-kage-* legales para OKF, por lo que un paquete de Kage sigue siendo 100% conforme y se abre en cualquier consumidor de OKF, incluido el visualizador propio de Google. OKF estandariza el almacén; Kage es la capa de verificación y actualidad que Google dejó fuera.
Una vez instalado, es ambiental. No ejecutas nada manualmente:
Recupera antes de actuar. Al comienzo de una tarea (y en el momento en que el agente abre un archivo), Kage muestra la memoria verificada relevante para ella. La memoria obsoleta o eliminada se deja fuera.
Captura mientras trabaja. Los aprendizajes duraderos se convierten en paquetes. Una memoria que cita un archivo que no existe se rechaza en el acto, de modo que las alucinaciones nunca entran en el almacenamiento.
Mantente honesto a medida que el código cambia. Cuando un diff modifica código que una memoria cita, esa memoria se marca en el momento del commit/PR (kage pr check) y se retiene de la recuperación hasta que se vuelve a verificar o se reemplaza, para que el conocimiento no pueda pudrirse silenciosamente.
Obsérvalo en el panel local (kage viewer): los paquetes, el grafo memoria↔código, las puertas de confianza y los eventos en vivo se transmiten mientras el agente trabaja. Envuelve cualquier cosa en <private>…</private> y nunca se almacenará.
La mayoría de las herramientas de memoria (claude-mem, agentmemory, mem0, Zep) almacenan la memoria por máquina o en una nube que no es tuya, y nunca la vuelven a contrastar con el código. Kage la mantiene en tu repositorio y la verifica, de modo que sigue siendo de tu equipo y sigue siendo fiel a medida que el código cambia.
Kage | claude-mem | mem0 / Zep | |
Captura automática + recuperación al inicio de la sesión | ✓ | ✓ | vía SDK |
Citas alucinadas rechazadas en el momento de escritura | ✓ | — | — |
Memoria obsoleta retenida en la recuperación (archivos citados eliminados/cambiados, TTL, notificado) | ✓ | — | — |
Detección de obsolescencia en el diff, aviso antes del PR cuando tu cambio rompe una memoria | ✓ | — | — |
Memoria revisada en git, en el mismo PR que el código (archivos simples, sin BD) | ✓ | SQLite + nube | API alojada |
Codificar la memoria en archivos | ✓ ( | — | — |
Sincronización entre máquinas | ✓ tu propio remoto de git | su nube | su nube |
Cuenta / clave de API requerida | ninguna | nube opcional | sí |
Informe de veracidad. kage scan lee cualquier repositorio en ~60s y saca a la luz sus brechas de conocimiento de mayor riesgo: archivos calientes sin documentar, rutas calientes sin probar, puntos de complejidad, deuda de código sin resolver y archivos con bus-factor-1, además de implementaciones duplicadas, exportaciones muertas y mentiras de documentación cuando existen. Cada hallazgo citado a file:line. Cero configuración, nada generado, se ejecuta antes de que instales nada.
Recibos de ahorro. kage gains mantiene un libro de valor por repositorio (tokens + $ que el agente no tuvo que volver a gastar), cada número trazable a un evento registrado; el agente lo transmite después de cada recuperación.
Habilidades de equipo. kage skills convierte procedimientos duraderos y verificados en archivos .claude/skills/<name>/SKILL.md que los agentes cargan automáticamente, versionados y compartidos, sin nube.
Memoria personal y sincronización. kage learn --personal guarda notas entre máquinas en ~/.kage/memory, recuperadas como una sección claramente separada de menor confianza y sincronizadas a través de tu propio remoto git.
Bucle de sesión autocurable. Las sesiones no capturadas se destilan automáticamente en borradores pendientes que tú revisas; kage resume abre cada sesión con un resumen "previamente…"; kage repair arregla paquetes e índices dañados con un solo comando.
18% más rápido que grep con la misma corrección en tareas reales de navegación de código (suite N=3, mismo agente/modelo; reproduce con kage benchmark --project . --compare).
Recuperación LongMemEval-S: 98.72% R@10 / 99.79% R@20 / 0.909 MRR — por delante de BM25 puro en todas las profundidades excepto R@5, donde BM25 le gana por poco (96.60% vs 96.17%; tabla completa en benchmarks/LONGMEMEVAL.md). La ruta de recuperación en sí no tiene dependencias: BM25 + puntuación léxica dispersa, sin embeddings, sin red.
Corrección de memoria ante cambios: 0% de datos obsoletos servidos (se retiene la memoria cuyo código fue eliminado o modificado), frente al 100% en los almacenes que capturan todo.
Benchmark de confianza: 100/100, que cubre rechazo de alucinaciones, exclusión de datos obsoletos y fundamentación en vivo (kage benchmark --trust --project .).
Metodología, comandos y salvedades: 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 bundleReferencia completa de CLI y MCP: docs. Delegar trabajo a agentes de codificación (despacho → reclamación verificada → fusión): docs/DELEGATION.md.
Todo vive en .agent_memory/: packets/ es la memoria duradera del repositorio (Markdown OKF rastreado por git); graph/, code_graph/, structural/ e indexes/ se pueden reconstruir con kage refresh; reports/ contiene el libro de valor y los informes de salud. La captura analiza secretos y PII antes de escribir.
Formato estándar — Open Knowledge Format (OKF). La memoria de Kage es un paquete OKF: archivos de conceptos en Markdown plano con frontmatter YAML, legibles por cualquier consumidor de OKF (incluido el visualizador de Google). Ejecuta kage okf migrate para renderizar el almacén como un paquete OKF en .agent_memory/okf/. Kage añade el ciclo de vida que OKF omite — fundamentación, verificación y frescura — transportado en campos x-kage-* legales para OKF, y puede import cualquier paquete OKF de terceros. El viaje de ida y vuelta no tiene pérdidas. Ver OKF_STANDARD.md.
cd mcp
npm install
npm test
npm run buildKage se construye en abierto y nos encantaría tu ayuda. Cuatro dependencias de ejecución (el núcleo de recuperación no usa ninguna), sin cuenta, sin nube — es un código amigable en el que empezar.
CONTRIBUTING.md — configuración de desarrollo, estructura del proyecto, convenciones.
ROADMAP.md — hacia dónde se dirige Kage y dónde encajar.
Buenos primeros issues · Se busca ayuda — lugares acotados para empezar.
Discussions — preguntas, ideas, mostrar y contar.
Al participar aceptas nuestro Código de Conducta.
GPL-3.0-only. Ver LICENSE. Las versiones anteriores al cambio a GPL eran 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
