Para usuarios de Claude Code que pierden tiempo explicando de nuevo el contexto del proyecto en cada sesión.
npx rekindle initTu IA olvida todo entre sesiones. Rekindle soluciona eso.
Rekindle es un motor de continuidad MCP que resuelve la orientación de la sesión, no solo el almacenamiento. Oriéntate al inicio de la sesión, captura al final de la sesión, sobrevive a la compactación a mitad de sesión. Todo local, todo SQLite, cero claves API.
v0.3.0 — "Sobrevive al largo intermedio" — Sistema de captura PreCompact, bucles abiertos, seguimiento de revisiones. Notas de la versión
npx rekindle initEsto crea un directorio .rekindle/ en tu proyecto con una base de datos SQLite, una plantilla de identidad, un directorio de capturas y un directorio de transcripciones. Luego, añade la configuración del servidor MCP para tu cliente:
Añade a ~/.claude.json:
{
"mcpServers": {
"rekindle": {
"command": "npx",
"args": ["-y", "rekindle"]
}
}
}Habilita la protección PreCompact (captura el contexto antes de la compactación a mitad de sesión):
npx rekindle setup-hooksAñade a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"rekindle": {
"command": "npx",
"args": ["-y", "rekindle"]
}
}
}Añade a .cursor/mcp.json en la raíz de tu proyecto:
{
"mcpServers": {
"rekindle": {
"command": "npx",
"args": ["-y", "rekindle"]
}
}
}Luego completa .rekindle/identity.md y pega las instrucciones de arranque en el archivo CLAUDE.md de tu proyecto.
La sesión 1 almacena. La sesión 2 recuerda. La sesión 10 anticipa.
Related MCP server: claude-session-continuity-mcp
A lo largo de 43 sesiones, medimos lo que un asistente de IA no lograba cargar al inicio de la sesión:
Métrica | Valor |
Sesiones analizadas | 43 |
Arranques limpios (todo el contexto cargado) | 33% |
Fallos de alta señal (más de 5 brechas) | 26% |
Fallos totales de recuperación | 173 |
Las herramientas de memoria existentes (Mem0, Letta, Zep) optimizan la precisión de la recuperación: ¿puede la IA encontrar lo que almacenó? Eso es necesario pero no suficiente. Ninguna de ellas aborda si la IA cargó el contexto correcto para esta sesión, o si puede detectar lo que se perdió.
Rekindle resuelve la orientación de la sesión: cargando la identidad, el contexto reciente, el estado de la memoria y las advertencias de contexto faltante antes de que el asistente comience a trabajar.
Consulta docs/gap-analysis.md para ver el conjunto de datos de investigación completo.
boot_report ejecuta una canalización de orientación antes de que comience cualquier trabajo:
boot_report
+-- Read identity document (who am I working with?)
+-- Scan memory stats (what do I know?)
+-- Find latest checkpoint (where did we leave off?)
+-- Read last transcript (what actually happened?)
+-- Surface open loops (what needs follow-up?)
+-- Surface PreCompact captures (what survived compaction?)
+-- Detect gaps (what am I missing?)
+-- Calculate orientation score (how oriented am I?)
--> "Carrying forward: [context loaded, gaps identified, score: 80/100]"La compactación a mitad de sesión destruye las cadenas de razonamiento, los enfoques fallidos, la textura relacional y el tono. El hook PreCompact se dispara automáticamente antes de la compactación y guarda lo que de otro modo se perdería:
PreCompact hook fires
+-- Parse JSONL transcript (last N messages)
+-- Write raw Markdown capture (.rekindle/captures/)
+-- Write structured JSON snapshot (decisions, open loops, files)
+-- Update manifest for cheap listing
--> boot_report surfaces captures on next session start
--> end_session warns if captures exist but weren't reviewedTres modos de lectura controlan el coste de tokens:
summary — un párrafo, económico
structured — decisiones/bucles/advertencias, moderado
raw — extracto completo de la transcripción, costoso (solo cuando es necesario)
end_session almacena registros de continuidad estructurados, no solo un resumen:
Campo | Qué captura |
| Dónde nos quedamos (obligatorio) |
| Qué se decidió y por qué |
| Tareas o preguntas sin resolver |
| Límites que no deben violarse |
| Qué cambió en la relación de trabajo |
| Dónde retomar la próxima sesión |
| Nuevas preferencias de usuario aprendidas |
| Cosas que la próxima sesión debería vigilar |
Todos los registros se almacenan con metadatos de type, source y session_id. El siguiente boot_report carga el punto de control automáticamente.
Herramienta | Descripción |
| Almacenar con contenido, categoría, importancia (1-10) y alcance del proyecto |
| Búsqueda de texto completo con ranking BM25, potenciado por importancia |
| Explorar memorias, las más recientes primero. Filtrar por categoría o proyecto |
| Eliminar por ID |
| Actualizar contenido, categoría o importancia |
| Listar capturas PreCompact (opcionalmente filtrar por sesión) |
| Leer una captura en modo resumen, estructurado o crudo |
| Capturar manualmente el contexto de la sesión actual bajo demanda |
Categorías: preference lesson context relationship general
Un archivo estático es pasivo. Tu IA lo lee, pero no puede buscarlo, clasificarlo, rastrear lo que se ha recuperado o decirte qué falta. Rekindle añade:
Búsqueda — texto completo con ranking ponderado por importancia
Estructura — categorización y alcance de proyecto a través de memorias
Orientación — carga proactiva de contexto al arrancar, no solo recuperación bajo demanda
Detección de brechas — marca identidad faltante, categorías vacías, datos obsoletos
Puntuación — lista de verificación transparente para que sepas qué tan orientada está la IA
Captura de sesión — cierre estructurado con puntos de control, decisiones y bucles abiertos
Supervivencia a la compactación — las capturas PreCompact preservan lo que los resúmenes aplanan
10 herramientas MCP — se añadieron list_captures, read_capture, capture_now
Sistema de captura PreCompact — preservación automática del contexto antes de la compactación a mitad de sesión
Bucles abiertos en boot_report — muestra tareas sin resolver de sesiones anteriores
Seguimiento de revisiones — capturas marcadas como revisadas después de read_capture; end_session advierte si no están revisadas
Configuración de hooks — npx rekindle setup-hooks configura el hook PreCompact de Claude Code
Auto-descubrimiento — capture_now descubre la transcripción de la sesión sin rutas manuales
101 pruebas automatizadas — unidad, integración, gestor de capturas, configuración de hooks
Comando | Descripción |
| Configurar |
| Configurar en el directorio home |
| Init + configurar hook PreCompact |
| Configurar hook PreCompact (independiente) |
| Capturar contexto antes de la compactación (hook) |
| Capturar manualmente el contexto de la sesión actual |
| Iniciar servidor MCP (usado por Claude Code) |
git clone https://github.com/Skitchy/rekindle.git
cd rekindle
npm install
npm run build
node dist/init/cli.js initEl comando setup-hooks escribe esto en .claude/settings.local.json:
{
"hooks": {
"PreCompact": [
{
"matcher": "auto",
"hooks": [
{
"type": "command",
"command": "npx rekindle precompact-capture",
"timeout": 60
}
]
},
{
"matcher": "manual",
"hooks": [
{
"type": "command",
"command": "npx rekindle precompact-capture",
"timeout": 60
}
]
}
]
}
}El hook recibe el contexto de la sesión en stdin (session_id, transcript_path, cwd, hook_event_name) y escribe las capturas en .rekindle/captures/.
Variable | Predeterminado | Descripción |
|
| Máximo de mensajes a capturar |
|
| Máximo de caracteres a capturar |
| Auto-detectado | Directorio base para |
Todos los datos son locales. No se envía nada a servidores externos.
Sin llamadas de red. El servidor MCP se comunica a través de stdio. Sin HTTP, sin telemetría, sin analíticas.
Las transcripciones contienen texto de conversación. No habilites la captura de transcripciones si tus sesiones contienen secretos o credenciales.
La instalación del hook es opcional. setup-hooks debe ejecutarse explícitamente (no se instala automáticamente con init).
La base de datos SQLite es un archivo normal. No está cifrada. Usa cifrado de disco a nivel de SO si es necesario.
.rekindle/ está en gitignore. El comando init maneja esto automáticamente.
boot_report lee archivos locales. Las rutas no están aisladas (sandboxed). Úsalo solo con clientes MCP y prompts en los que confíes.
Cliente | Transporte | Estado |
Claude Code (macOS) | stdio | Probado |
Claude Code (Linux/WSL2) | stdio | Probado |
Claude Code (Windows) | stdio | Probado |
Claude Desktop | stdio | Compatible (mismo formato de configuración MCP) |
Cursor | stdio | Compatible (mismo formato de configuración MCP) |
Cualquier cliente MCP stdio | stdio | Compatible |
rekindle/
src/
index.ts MCP server entry point
server.ts Server setup, tool registration (10 tools)
storage/
sqlite.ts SQLite + FTS5, schema migration, sessions
orientation/
types.ts OrientationResult, Gap, ScoreItem
GapDetector.ts Structural gap detection (8 codes)
Scorer.ts Orientation scoring (6 criteria, 100pts)
OrientationService.ts Orchestrator
OrientationRenderer.ts Markdown + JSON output
captures/
types.ts CaptureEntry, StructuredSnapshot, HookInput
CaptureManager.ts Parse, capture, list, read, review tracking
discover-transcript.ts Auto-discover session transcripts
precompact-capture.ts CLI hook entry point
capture-now.ts Manual capture CLI
tools/
boot-report.ts Orientation + open loops + capture awareness
end-session.ts Structured session close + capture warning
list-captures.ts List PreCompact captures
read-capture.ts Read captures in 3 modes
capture-now.ts Model-triggered manual capture
store.ts search.ts list.ts delete.ts update.ts
init/
cli.ts scaffold.ts setup-hooks.ts templates/Almacenamiento: SQLite + FTS5 vía better-sqlite3. Ranking BM25 potenciado por importancia. Registros tipados con type, source, session_id.
Transporte: stdio (MCP estándar). Funciona con Claude Code de forma inmediata.
npm test101 pruebas: CRUD de almacenamiento + ranking FTS5, dominio de orientación (detección de brechas, puntuación, servicio, renderizado), gestor de capturas (análisis, límites, seguimiento de revisiones, formato), configuración de hooks (esquema, idempotencia) e integración MCP (las 10 herramientas).
v0.4: "Piensa en redes" — Activación por propagación, búsqueda semántica mediante embeddings, herramientas de análisis de brechas, arnés de evaluación.
MIT
Generate a session orientation report. Read-only — does not modify any stored data. Reads the identity document from disk, scans the memory database for statistics and the latest checkpoint, finds the most recent transcript file, detects structural gaps (missing identity, stale memories, no checkpoint, etc.), and calculates a 0-100 orientation score across 6 criteria. Also surfaces open loops from prior sessions and any PreCompact captures that preserve context from compacted sessions. Workflow: call boot_report first thing every session, before any substantive work. Orientation scores are structural checks, not guarantees that every relevant context item was loaded.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Active project name for scoped orientation. When provided, the orientation score includes a project-specific criterion and memory statistics are filtered to this project. | |
| identity_path | Yes | Absolute or relative path to the identity document (e.g., '.rekindle/identity.md'). This file describes who the user is and how to work with them. If the file does not exist, a critical gap is reported. | |
| transcript_dir | Yes | Absolute or relative path to the transcripts directory (e.g., '.rekindle/transcripts'). The most recent .md file in this directory is read and included in the report. If the directory is empty or missing, an info-level gap is reported. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly states it is read-only and does not modify stored data, and it discloses that orientation scores are structural checks, not guarantees of loaded context. This adds valuable context beyond the basic function, though it doesn't detail the output format or potential edge-case errors.
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 efficiently structured: the first sentence states the core purpose, the second sentence explains the data sources and operations, and the third provides workflow and caveats. Every sentence contributes meaningful 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's complexity (multiple inputs, calculations, and output), the description covers inputs, actions, and output semantics (orientation score, open loops, captures). No output schema exists, so the description does well to mention what the report includes. It lacks explicit return format details, but the description is strong overall.
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 all three parameters are already well-documented. The description adds no additional parameter-specific details beyond what the schema provides, but it does reiterate the purpose of identity and transcript paths. This matches the baseline for high coverage.
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 generates a session orientation report, with a specific verb (generate) and resource (session orientation report). It distinguishes itself from sibling tools by detailing its unique function of reading identity, scanning memory, and calculating an orientation score, which none of the siblings perform.
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 provides a workflow directive: 'call boot_report first thing every session, before any substantive work.' This gives clear contextual guidance on when to use it. However, it does not explicitly mention alternatives or when not to use it, but none are needed given its unique role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually capture current session context to .rekindle/captures/. Use this when you want to preserve the current conversation state — before a complex operation, when context feels at risk, or when the user requests it. Produces the same artifact as the automatic PreCompact hook but triggered on demand. session_id and transcript_path are optional — if omitted, the most recent transcript is discovered automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Why this capture is being made (stored in the structured snapshot). | |
| session_id | No | Current session ID. If omitted, discovered from the most recent transcript file. | |
| transcript_path | No | Path to the current session's JSONL transcript file. If omitted, the most recent transcript is discovered automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses file creation location, artifact equivalence with PreCompact, and optional parameters with auto-discovery. No annotations provided, so description carries full burden. Could mention idempotency or error handling but still provides solid 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?
Two sentences, no filler. First sentence clearly states action and output. Second provides usage and parameter notes. Perfectly front-loaded and efficient.
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?
Describes artifact and auto-discovery for parameters, but does not explicitly state return value or success indication. With no output schema, the description could mention what the tool returns (e.g., path to capture). Still, very informative overall.
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?
Input schema has 100% description coverage. Description adds value by noting that session_id and transcript_path can be omitted and auto-discovered, going beyond schema. Reason parameter is not elaborated in description but schema covers it. Extra context earns above baseline.
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?
Description states specific verb ('capture') and resource ('current session context') and target location ('.rekindle/captures/'). Clearly distinguishes from siblings like list_captures and read_capture, as this is the creation tool.
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 states when to use: 'before a complex operation, when context feels at risk, or when the user requests it.' Also contrasts with automatic PreCompact hook. Lacks explicit 'when not to use' but positive guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a single memory from the local SQLite database by its ID. This action is irreversible — the row and its full-text search index entry are removed immediately. Use when a memory is outdated, incorrect, or no longer relevant. Returns {success: true} if the memory was found and deleted, or {success: false, message: 'Memory not found'} if the ID does not exist. Does not affect other memories or session records.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The UUID of the memory to delete. Obtain from store_memory, search_memory, or list_memories results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral traits: it warns of irreversibility ('This action is irreversible'), explains immediate deletion of both row and full-text search index entry, and details return values for both success and failure cases ('Returns {success: true} if found... or {success: false, message: 'Memory not found'} if ID does not exist'). It also states that other memories or session records are unaffected.
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 three sentences with no unnecessary words. The first sentence immediately conveys the action and scope. Each subsequent sentence adds important detail (irreversibility, usage guidance, return values). Everything is front-loaded and earns its place.
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 only one parameter, no output schema, and no annotations, the description covers all necessary aspects: what it does, when to use it, behavioral implications (irreversibility), parameter sourcing, and return values. It is fully complete for this simple 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?
The only parameter 'id' is already described in the input schema ('The UUID of the memory to delete. Obtain from store_memory, search_memory, or list_memories results.'). The tool description reinforces this by mentioning how to obtain the ID. With 100% schema coverage, baseline is 3; the extra context in the description (e.g., 'Obtain from...') adds value, justifying a 4.
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 starts with a specific verb ('Permanently delete') and resource ('a single memory from the local SQLite database'), clearly distinguishing it from sibling tools like store_memory, update_memory, or list_memories. The action is unambiguous.
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 when a memory is outdated, incorrect, or no longer relevant.' This provides clear context. However, it does not explicitly mention when not to use it or suggest alternatives (e.g., update_memory for correction), so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a structured session handoff. Writes multiple records to the local SQLite database: one checkpoint (required), plus optional decisions, open loops, preferences, constraints, warnings, relational delta, and next session focus. Each record is stored with a typed 'type' column (not content prefixes) and linked to a session record via session_id. Also creates a session row in the sessions table with a summary, orientation score, and gap count. The checkpoint is retrievable by boot_report on the next session start. All records are searchable via search_memory and list_memories. Workflow: call end_session at the end of every substantive session so the next session can pick up the thread.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name to scope all records to. Passed through to each stored memory's project field. | |
| warnings | No | Hazards or risks the next session should be aware of. Each entry is stored as type='warning' with importance 8. | |
| decisions | No | Key decisions made this session and their rationale. Each entry is stored as a separate memory with type='decision' and importance 7. | |
| checkpoint | Yes | Where we left off — the single most important handoff artifact. Stored as type='checkpoint' with importance 8. This is what boot_report loads as the latest checkpoint on the next session start. | |
| open_loops | No | Unresolved questions, pending tasks, or threads that need follow-up. Each entry is stored as type='open_loop' with importance 7. | |
| session_id | No | Current session ID. Used to check for unreviewed PreCompact captures. If captures exist for this session that were not read via read_capture, a warning is included in the response. | |
| constraints | No | Boundaries that must not be violated — violating these causes trust damage. Each entry is stored as type='constraint' with importance 9 (highest default). | |
| preferences | No | New user preferences or working style observations learned this session. Each entry is stored as type='preference' with importance 6. | |
| transcript_path | No | File path to the session transcript, stored on the session record for reference by boot_report. | |
| relational_delta | No | What changed in the working relationship this session — trust shifts, tension, repair, tone changes. Stored as type='relational_delta' with importance 8. | |
| next_session_focus | No | Where to resume next session, which may differ from where we stopped. Stored as type='next_session_focus' with importance 7. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses multiple behavioral traits: writes to a local SQLite database, stores records with a typed 'type' column, links to session_id, creates a session row with summary/orientation/gap count, includes a warning for unreviewed PreCompact captures, and mentions searchability and boot_report retrieval. This is thorough and non-misleading.
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?
Although the description is moderately long, it is dense and well-structured. It begins with the core purpose, flows into storage details, and concludes with the workflow. Every sentence adds operational information, and there is no redundancy or filler.
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 11 parameters, no output schema, and no annotations, the description covers all critical aspects: what gets written, how records are typed and linked, how to retrieve them later, the session row side-effect, and the warning behavior. It also explains the intended workflow. This is a complete description for a complex 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%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining the overall storage model (typed column, session_id linkage), the relationship to boot_report, and the workflow. However, it does not add much per-parameter detail that isn't already in the schema, so a 4 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 starts with a specific verb and resource: 'Capture a structured session handoff.' It clearly distinguishes from siblings like list_captures or store_memory by focusing on session-end aggregation and persistence. The phrase 'Writes multiple records to the local SQLite database' further specifies scope and behavior.
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 states a clear usage trigger: 'call end_session at the end of every substantive session so the next session can pick up the thread.' It provides clear context but does not explicitly name alternative tools or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List PreCompact captures for the current or recent sessions. PreCompact captures preserve context that would otherwise be lost during mid-session compaction. Workflow: if boot_report lists PreCompact captures, call list_captures then read_capture to recover pre-compaction context before relying on the checkpoint. Before calling end_session, check for unreviewed captures.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Filter to a specific session. If omitted, returns all captures sorted by recency. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It reveals the behavioral context of PreCompact captures and the recovery workflow, but doesn't detail return format or side effects, which are minimal for a list operation. Adds value beyond a simple 'list captures'.
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?
Three sentences, each earning its place: purpose, context, and workflow. Front-loaded with the primary action, concise with no fluff.
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 simple listing tool with one optional parameter and no output schema, the description provides sufficient context for selection and invocation. It also integrates with sibling tools (boot_report, read_capture, end_session), making the workflow complete.
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 schema covers 100% of the parameters, so baseline is 3. The description does not add any extra semantic detail about session_id; it is fully explained in 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 clearly states it lists PreCompact captures, with a specific verb and resource. It distinguishes from siblings like read_capture by focusing on listing, and adds context about preserving pre-compaction 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?
Explicit workflow is given: if boot_report lists PreCompact captures, call list_captures then read_capture to recover context before relying on the checkpoint; also check for unreviewed captures before end_session. This clearly indicates when to use the tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stored memories from the local SQLite database, ordered newest first. Unlike search_memory, this does not require a query — it returns all memories matching the optional filters. Read-only; does not modify any data. Use to browse what has been stored, audit memory contents, or check memory counts per category or project. Returns an array of memories with id, content, category, importance, project, and created_at.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of memories to return. Default 50. Newest memories are returned first regardless of limit. | |
| project | No | Filter to a specific project. Omit to list memories across all projects. | |
| category | No | Filter to a single category. Omit to list memories across all categories. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses read-only nature ('Read-only; does not modify any data'), ordering (newest first), and return fields. It does not cover potential pagination beyond the limit parameter or error handling, but overall provides solid transparency.
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 main action, and each sentence adds value. No unnecessary words or repetition. Highly efficient.
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 low complexity (3 optional parameters, no output schema, no annotations), the description covers purpose, usage guidance, behavior, return format, and ordering. It is complete enough for an agent to understand how and when to use the 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%, so the description need not add much. It reinforces the ordering ('Newest memories are returned first regardless of limit') and lists return fields, which is helpful but not essential. The description does not significantly deepen understanding of the 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 verb 'list', the resource 'memories', and the key distinction from sibling 'search_memory' by noting it does not require a query. It specifies the ordering (newest first) and return fields, making the purpose unambiguous.
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: 'to browse what has been stored, audit memory contents, or check memory counts per category or project'. It also contrasts with 'search_memory' (requires a query). However, it does not explicitly state when not to use or provide alternative tools beyond the mention of search_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a PreCompact capture by ID. Use this to recover context that was lost during mid-session compaction. Three modes control token cost: 'summary' (one paragraph, cheap), 'structured' (decisions/loops/warnings, moderate), 'raw' (full transcript excerpt, expensive — only when summary or structured is insufficient). Workflow: read recovered captures before relying on the latest checkpoint; start with the lightest mode that answers your question.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Capture ID from list_captures (e.g., 'precompact-abc123-001') | |
| mode | No | Reading mode. 'summary': one-paragraph overview. 'structured': decisions, open loops, warnings, context shifts. 'raw': full transcript excerpt. | structured |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It details three modes with token cost implications ('summary' cheap, 'structured' moderate, 'raw' expensive) and advises using raw only when lighter modes are insufficient. This goes beyond a simple read, giving the agent actionable behavioral guidance without contradicting any structured metadata.
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 about five sentences and front-loaded with the core purpose, then provides mode details and a workflow. It is efficient and avoids redundancy, though it lacks bullet-point formatting that could improve scannability. 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 tool has a moderate complexity (2 params, 3 modes) and no output schema. The description gives enough context for the agent to understand what to expect from each mode and how to use the tool effectively, covering purpose, mode selection, cost, and workflow. It does not describe error cases or exact return structures, but these are not critical for basic invocation.
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 baseline is 3. The description adds meaningful extra semantics, especially for the mode parameter: it expands on the schema by explaining 'summary' as one paragraph, 'structured' as decisions/loops/warnings, and 'raw' as full transcript excerpt, plus cost guidance. This enriches the schema definitions.
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 'Read' and the resource 'PreCompact capture by ID', and specifically ties it to recovering context lost during mid-session compaction. This distinguishes it from sibling tools like list_captures or capture_now by focusing on reading a specific capture.
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 says when to use the tool ('recover context lost during mid-session compaction') and provides a workflow: 'read recovered captures before relying on the latest checkpoint; start with the lightest mode that answers your question.' This gives clear context and usage strategy, though it does not explicitly mention alternatives to other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search stored memories using SQLite full-text search (FTS5). Returns results ranked by relevance with higher-importance memories boosted. Each search increments the retrieval_count on matched memories, tracking which memories are accessed most. Use at session start to load relevant context, or mid-session to recall specific information. Returns an array of matching memories with id, content, category, importance, project, created_at, and retrieval_count. Returns an empty array if no matches are found.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return. Default 10. Results are ranked by relevance and importance before truncation. | |
| query | Yes | Full-text search query. Supports keywords, phrases, and SQLite FTS5 syntax (e.g., 'database AND migration', '"exact phrase"'). Broader queries return more results. | |
| project | No | Filter results to a specific project. Omit to search across all projects. | |
| category | No | Filter results to a single category. Omit to search across all categories. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: uses FTS5, results ranked by relevance and importance, increments retrieval_count on matched memories, returns specific fields, and returns empty array on no match. This is comprehensive given no 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?
Concise and well-structured (~90 words), each sentence serves a purpose: purpose, ranking info, side effect, usage, return structure, and empty case. 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?
Covers all essential aspects: search mechanism, ranking criteria, side effect (increment retrieval_count), return fields, and empty result handling. No output schema but description adequately describes return structure.
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 already has descriptions for all parameters (100% coverage). The description adds value by explaining query semantics ('Broader queries return more results') and limit behavior ('Results are ranked by relevance and importance before truncation').
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 performs a full-text search on stored memories using SQLite FTS5, distinguishing it from sibling tools like list_memories (which likely lists all memories) and other CRUD tools.
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?
Provides explicit usage scenarios: 'Use at session start to load relevant context, or mid-session to recall specific information.' While it does not explicitly exclude alternatives, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new memory in the local SQLite database. Creates a persistent row with an auto-generated UUID, timestamp, and the provided content. Use for preferences, lessons learned, project context, relationship notes, or general information worth remembering across sessions. Memories persist across sessions and are surfaced by boot_report, search_memory, and list_memories. Returns the generated ID on success. Does not deduplicate — calling twice with the same content creates two separate memories.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The memory content to store. Plain text, no length limit. Should be self-contained — future retrieval may return this memory without surrounding context. | |
| project | No | Project name to scope this memory to. When set, boot_report can filter orientation to this project. Omit for cross-project memories. | |
| category | No | Memory category. Determines how the memory is weighted during orientation: 'preference' and 'relationship' contribute to the orientation score. 'context' is used for checkpoints and session handoffs. 'lesson' is used for constraints and warnings. 'general' is the default catch-all. | general |
| importance | No | Importance score from 1 (low) to 10 (critical). Higher-importance memories are ranked first in search results. Constraints default to 9, checkpoints to 8, general notes to 5. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses persistence across sessions, no deduplication, return value (generated ID), and that content should be self-contained. It also notes that memories are surfaced by other tools. No destructive behavior is relevant, and the description covers the key behavioral traits.
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 a single paragraph of about 6 sentences, well-structured: action, details, usage examples, cross-references to other tools, return value, and a caveat. Every sentence earns its place 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 4 parameters with full schema descriptions, no output schema but return value explained, and no nested objects, the description is complete. It covers persistence, deduplication, and cross-tool integration, leaving no significant gaps for an AI agent to use this 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 coverage is 100%, but the description adds significant value beyond the schema descriptions. For 'content' it specifies plain text with no length limit; for 'category' it explains impact on orientation scoring; for 'importance' it clarifies ranking and defaults for specific use cases; for 'project' it explains scoping and omission. This enriches the agent's understanding.
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 'Store' and the resource 'memory', and identifies it as persistent with auto-generated UUID and timestamp. It lists specific use cases (preferences, lessons, etc.) and explicitly connects to sibling tools (boot_report, search_memory, list_memories), distinguishing this creation tool from retrieval and deletion tools.
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 enumerates appropriate use cases (preferences, lessons, project context, etc.) and warns about the lack of deduplication. While it does not explicitly state when not to use, the positive guidance is strong and the deduplication caveat helps avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing memory in the local SQLite database. Modifies only the fields you provide — omitted fields are left unchanged. The updated_at timestamp is set automatically. If content is changed, the full-text search index is rebuilt for this memory. Returns the full updated memory object on success, or {success: false, message: 'Memory not found'} if the ID does not exist. Use to correct inaccurate memories, adjust importance, or reclassify a memory's category without deleting and re-creating it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The UUID of the memory to update. Obtain from store_memory, search_memory, or list_memories results. | |
| content | No | Replacement content for the memory. Omit to keep the existing content unchanged. | |
| category | No | New category for the memory. Omit to keep the existing category unchanged. | |
| importance | No | New importance score from 1 (low) to 10 (critical). Omit to keep the existing score unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses key behaviors: partial field updates (omitted fields left unchanged), automatic updated_at timestamp, full-text search index rebuild on content change, and the exact return format for success and failure. This is comprehensive.
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 long, well-structured: first sentence states main purpose, second clarifies partial update behavior, third lists side effects, fourth gives use cases. No unnecessary 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?
Given the tool's complexity (partial updates, side effects like FTS rebuild, no output schema), the description covers all critical aspects: what fields can be updated, what happens to omitted fields, automatic timestamp, index rebuild, and the exact return format for both success and failure cases.
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 each parameter already described in the schema. The description adds minimal additional context, such as 'id' being obtainable from other tools. The partial update behavior is implied by the schema's 'Omit to keep' statements, so the description just reinforces. 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: updating an existing memory in a local SQLite database. It specifies the verb 'update' and the resource 'memory', and distinguishes from sibling tools like store_memory and delete_memory by mentioning it avoids deleting and re-creating.
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 provides use cases: 'correct inaccurate memories, adjust importance, or reclassify a memory's category'. It implies not to use for creation (use store_memory) or deletion (use delete_memory), though it doesn't explicitly list when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0boot_report3 fields changedInput schema / properties / identity_path / descriptionPrevious value: -"Path to identity.md (e.g., .rekindle/identity.md)"New value: +"Absolute or relative path to the identity document (e.g., '.rekindle/identity.md'). This file describes who the user is and how to work with them. If the file does not exist, a critical gap is reported."Input schema / properties / project / descriptionPrevious value: -"Active project name for scoped orientation"New value: +"Active project name for scoped orientation. When provided, the orientation score includes a project-specific criterion and memory statistics are filtered to this project."Input schema / properties / transcript_dir / descriptionPrevious value: -"Path to transcripts directory (e.g., .rekindle/transcripts)"New value: +"Absolute or relative path to the transcripts directory (e.g., '.rekindle/transcripts'). The most recent .md file in this directory is read and included in the report. If the directory is empty or missing, an info-level gap is reported."capture_nowdelete_memory1 field changedInput schema / properties / id / descriptionPrevious value: -"The memory ID to delete"New value: +"The UUID of the memory to delete. Obtain from store_memory, search_memory, or list_memories results."end_session11 fields changedInput schema / properties / checkpoint / descriptionPrevious value: -"Where we left off — the single most important handoff artifact"New value: +"Where we left off — the single most important handoff artifact. Stored as type='checkpoint' with importance 8. This is what boot_report loads as the latest checkpoint on the next session start."Input schema / properties / constraints / descriptionPrevious value: -"Boundaries that must not be violated — violating these causes trust damage"New value: +"Boundaries that must not be violated — violating these causes trust damage. Each entry is stored as type='constraint' with importance 9 (highest default)."Input schema / properties / decisions / descriptionPrevious value: -"What was decided and why"New value: +"Key decisions made this session and their rationale. Each entry is stored as a separate memory with type='decision' and importance 7."Input schema / properties / next_session_focus / descriptionPrevious value: -"Where to resume next session (vs where we stopped)"New value: +"Where to resume next session, which may differ from where we stopped. Stored as type='next_session_focus' with importance 7."Input schema / properties / open_loops / descriptionPrevious value: -"Unresolved questions or tasks"New value: +"Unresolved questions, pending tasks, or threads that need follow-up. Each entry is stored as type='open_loop' with importance 7."Input schema / properties / preferences / descriptionPrevious value: -"New user preferences learned this session"New value: +"New user preferences or working style observations learned this session. Each entry is stored as type='preference' with importance 6."Input schema / properties / project / descriptionPrevious value: -"Project scope"New value: +"Project name to scope all records to. Passed through to each stored memory's project field."Input schema / properties / relational_delta / descriptionPrevious value: -"What changed in the working relationship this session — trust changes, tension, repair, tone shifts"New value: +"What changed in the working relationship this session — trust shifts, tension, repair, tone changes. Stored as type='relational_delta' with importance 8."Input schema / properties / session_idAdded value: +{
+ "description": "Current session ID. Used to check for unreviewed PreCompact captures. If captures exist for this session that were not read via read_capture, a warning is included in the response.",
+ "type": "string"
+}Input schema / properties / transcript_path / descriptionPrevious value: -"Path to session transcript file"New value: +"File path to the session transcript, stored on the session record for reference by boot_report."Input schema / properties / warnings / descriptionPrevious value: -"Things the next session should be careful about"New value: +"Hazards or risks the next session should be aware of. Each entry is stored as type='warning' with importance 8."list_captureslist_memories3 fields changedInput schema / properties / category / descriptionPrevious value: -"Filter by category"New value: +"Filter to a single category. Omit to list memories across all categories."Input schema / properties / limit / descriptionPrevious value: -"Maximum results to return"New value: +"Maximum number of memories to return. Default 50. Newest memories are returned first regardless of limit."Input schema / properties / project / descriptionPrevious value: -"Filter by project"New value: +"Filter to a specific project. Omit to list memories across all projects."read_capturesearch_memory4 fields changedInput schema / properties / category / descriptionPrevious value: -"Filter by category"New value: +"Filter results to a single category. Omit to search across all categories."Input schema / properties / limit / descriptionPrevious value: -"Maximum results to return"New value: +"Maximum number of results to return. Default 10. Results are ranked by relevance and importance before truncation."Input schema / properties / project / descriptionPrevious value: -"Filter by project"New value: +"Filter results to a specific project. Omit to search across all projects."Input schema / properties / query / descriptionPrevious value: -"Search query (keywords or phrases)"New value: +"Full-text search query. Supports keywords, phrases, and SQLite FTS5 syntax (e.g., 'database AND migration', '\"exact phrase\"'). Broader queries return more results."store_memory4 fields changedInput schema / properties / category / descriptionPrevious value: -"Memory category"New value: +"Memory category. Determines how the memory is weighted during orientation: 'preference' and 'relationship' contribute to the orientation score. 'context' is used for checkpoints and session handoffs. 'lesson' is used for constraints and warnings. 'general' is the default catch-all."Input schema / properties / content / descriptionPrevious value: -"The memory content to store"New value: +"The memory content to store. Plain text, no length limit. Should be self-contained — future retrieval may return this memory without surrounding context."Input schema / properties / importance / descriptionPrevious value: -"Importance score 1-10 (higher = retrieved more often)"New value: +"Importance score from 1 (low) to 10 (critical). Higher-importance memories are ranked first in search results. Constraints default to 9, checkpoints to 8, general notes to 5."Input schema / properties / project / descriptionPrevious value: -"Project scope for this memory"New value: +"Project name to scope this memory to. When set, boot_report can filter orientation to this project. Omit for cross-project memories."update_memory4 fields changedInput schema / properties / category / descriptionPrevious value: -"New category"New value: +"New category for the memory. Omit to keep the existing category unchanged."Input schema / properties / content / descriptionPrevious value: -"New content"New value: +"Replacement content for the memory. Omit to keep the existing content unchanged."Input schema / properties / id / descriptionPrevious value: -"The memory ID to update"New value: +"The UUID of the memory to update. Obtain from store_memory, search_memory, or list_memories results."Input schema / properties / importance / descriptionPrevious value: -"New importance score"New value: +"New importance score from 1 (low) to 10 (critical). Omit to keep the existing score unchanged."v0.2.0boot_reportdelete_memoryend_sessionlist_memoriessearch_memorystore_memoryupdate_memoryScored across 10 tools
Most tools have distinct purposes: memory CRUD vs. session handoff vs. capture recovery. The only potential confusion is between capture_now and end_session, but descriptions clarify that end_session creates a structured handoff while capture_now preserves raw context for compaction recovery.
All tool names follow a consistent snake_case verb-first pattern: end_session, list_captures, read_capture, store_memory, search_memory, list_memories, delete_memory, update_memory. Even boot_report and capture_now fit the verb-first style. No mixed conventions or unpredictable naming.
Ten tools is well within the ideal 3-15 range and each tool serves a clear function in the memory/session management domain. No redundancy or bloat; the set feels appropriately scoped for the server's purpose.
Memory CRUD is covered (store, search, list, update, delete) and session handoff/orientation is addressed with end_session and boot_report. However, there's no direct 'get memory by ID' tool, which could force agents to use search or list and manually filter, a minor gap in the read path.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Shared memory for AI tools: save once, recall word for word from Claude, ChatGPT, Codex or Gemini.
Portable AI memory you own. Keep memories and notes across Claude, ChatGPT, and other AI tools.
