Herramientas MCP

Resumen

toon-memory proporciona 35 herramientas MCP y 4 recursos MCP para gestionar la memoria persistente:

Herramientas

Herramienta	Descripción
memory_remember	Guarda una decisión, patrón, bug, conocimiento o warning (memoria negativa “NO hagas esto”, recuperada con boost) (con TTL opcional, inferencia automática de etiquetas, links, quality score automático, merge-dedup, confidence, importance opcional: critical/high/medium/low)
memory_recall	Busca en la memoria (úsalo ANTES de leer archivos, filtra entradas con TTL expirado). mode: "graph" expande un subgrafo con relaciones para mayor precisión. El ranking usa fusión RRF (BM25×3 + centralidad del grafo, k adaptativo); pasa rrf: false para el score lineal legacy. sessionBias potencia entradas de la rama git actual. pathScope limita los resultados a una ruta de archivo (con globMatch). budget: "tiny", "normal" o "deep". as_of re-incluye entradas superseded después de una fecha puntual. explain: true añade una línea de razón por entrada (por qué se recuperó). budget_tokens limita la salida por tokens estimados (0 = sin límite). mode: "index" lista una línea por entrada (key, id, categoría, fecha, % de relevancia) sin contenido; ids recupera entradas por id/key en lote, conservando el orden
memory_forget	Elimina una entrada por key o id
memory_stats	Ver el estado de la memoria (incluyendo estadísticas de TTL, distribución de calidad, memorias frías por debajo de umbrales y métricas de hit-rate/duplicadas/obsoletas: % recuperadas al menos una vez, % de contenido duplicado exacto, % de entradas obsoletas)
memory_summary	Guardar/recuperar resúmenes de archivos
memory_archive	Archiva entradas antiguas (>30 días) y entradas con TTL expirado
memory_diff	Muestra cambios desde una fecha (24h, 7d, o fecha exacta)
memory_suggest	Encuentra entradas relacionadas para un contexto dado
memory_captured	Lista actividad auto-capturada por hooks (opt-in) o limpia el log
memory_checkpoint	Punto de control: crea una instantánea del estado actual de memoria con TTL de 7d. Útil para referencia de restauración durante sesiones largas
memory_consolidate	Operaciones de limpieza, determinísticas (sin LLM): mode: "identical" (default) de-duplica contenido idéntico, "similar" fusiona casi-duplicados (Jaccard >50%), "low-quality" limpia en lote entradas de baja calidad (minQuality, dryRun), "versions" detecta entradas del mismo tema en distintas versiones de librería y retira las antiguas a favor de la más nueva
memory_encrypt	Habilita encriptación AES-256-GCM
memory_decrypt	Deshabilita la encriptación
memory_backup	Crea backup con timestamp del archivo de memoria (auto-limpia a los 10 más recientes)
memory_sessions	Muestra sesiones activas de agentes, branches, y conflictos suaves de archivos para coordinación multi-sesión
context_brief	Briefing de contexto en una llamada: memoria + sesiones + salud en markdown compacto. Reemplaza 5-6 llamadas memory_*. Cero LLM
context_generate	Briefing completo del proyecto: estructura + git + memoria + sesiones en una llamada. Reemplaza 6 llamadas manuales. Ahorra 93% tokens
context_diff	Briefing incremental: commits git + archivos modificados + memoria nueva/actualizada desde la última sesión. Ahorra 72% tokens
context_focus	Briefing dirigido: memoria relevante + archivos relacionados + callers + archivos de test para una query específica
context_health	Auditoría de salud: links huérfanos, duplicados, referencias rotas, TTL expirados, sesiones obsoletas. Puntaje 0–100
context_export	Exportar como Markdown: exporta memoria como markdown inyectable para system prompts. Ahorra 82% tokens
memory_smart_recall	Búsqueda unificada: BM25 + grafo + quality + freshness + decay + sesgo de sesión en una sola llamada. explain: true añade razones por entrada; budget_tokens limita la salida por tokens estimados
memory_pin	Fijar entrada: las entradas fijadas siempre aparecen al inicio de los resultados, incluso sin coincidencia de palabras clave. Soporta prioridad 1-5 (1=más alta), ordenadas por prioridad
memory_unpin	Desfijar entrada: elimina la marca de prioridad de una entrada
memory_search	Búsqueda unificada con filtros: igual que memory_recall más filtros de categoría, etiquetas y rango de fechas. sessionBias potencia entradas de la rama git actual
memory_tag	Operaciones por lotes: añade, elimina o establece etiquetas en una o más entradas por key o id
memory_reflect	Reflexión de memoria: clasifica de forma determinista las entradas por obsolescencia, calidad y sobre-conexión para revelar lo que necesita atención o limpieza. Cero LLM
memory_promote	Auto-promover borradores: promueve entradas de baja confianza a activas de forma determinista (umbral 0.65, dedup Jaccard > 0.5, dryRun por defecto)

Recursos MCP

La memoria también se expone como recursos MCP para lectura directa de contexto:

Recurso	URI	Descripción
Entradas de memoria	toon://memory/entries	Volcado completo de la memoria
Estadísticas de memoria	toon://memory/stats	Conteos por categoría e info de TTL
Resúmenes de memoria	toon://memory/summaries	System primer auto-generado: mapa de conocimiento, memorias recientes, y decisiones clave

Los recursos permiten a los agentes leer la memoria como contexto sin invocar herramientas — útil para system prompts o el inicio de sesión. El system primer proporciona contexto instantáneo sobre el estado de conocimiento de tu proyecto.

Ejemplos

Recordar una decisión

memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Usar Zod para validación",
  file: "src/types.ts",
  tags: "validation;types"
})
// 🧠 Guardado: decision/use-zod (a1b2c3d4)
// 🔗 Entradas relacionadas:
//   [pattern] zod-schemas — Schemas Zod compartidos para validación de API

Recordar con TTL

memory_remember({
  category: "knowledge",
  key: "sprint-deadline",
  content: "El sprint termina el 18 de julio, el congelamiento de features es el 16 de julio",
  ttl: "7d"
})
// 🧠 Guardado: knowledge/sprint-deadline (x1y2z3w4)
// ⏰ TTL: 2026-07-19

Usa ttl para contexto temporal como fechas límite o información de sprints. Soporta relativos (7d, 30d) o fechas exactas (2026-12-31). Las entradas expiradas se filtran automáticamente de la búsqueda.

Etiquetas inferidas automáticamente

memory_remember({
  category: "bug",
  key: "redis-connection-timeout",
  content: "Timeout de conexión Redis en producción, se aumentó el pool"
  // tags vacío — se infiere automáticamente del contenido
})
// 🧠 Guardado: bug/redis-connection-timeout (a1b2c3d4)
// 🏷️ Tags inferidos: redis

Cuando tags está vacío, el sistema los infiere del contenido usando un vocabulario de 20+ categorías: redis, auth, api, db, security, test, deploy, config, performance, refactor, error, logging, types, async, state, ui, storage, email, payment, webhook.

Buscar en la memoria

memory_recall({ query: "redis" })
// [bug] redis-pool-fix (i9j0k1l2)
//   Se agregó max_connections=20
//   Archivo: redis.ts | Tags: redis;fix | Fecha: 2026-07-10

Explicar POR QUÉ se devolvió un resultado

memory_recall({ query: "redis", explain: true })
// [decision] redis-cache-config (a1b2c3d4)
//   Capa de caché Redis para almacenamiento de sesión
//   Archivo: src/cache.ts | Tags: redis;cache | Fecha: 2026-07-10
//   ↳ 92% relevancia · usado 14× · usado hoy · importancia ALTA

La línea ↳ es determinista (relevancia %, conteo de accesos, último uso, importancia) — sin LLM. Usa explain: true cuando quieras saber por qué el agente recibió esas entradas. Las entradas guardadas con un nivel de importance explícito también lo reportan (ej. · explicit critical).

Limitar la salida con budget_tokens

memory_recall({ query: "redis", budget_tokens: 300 })
// Las entradas se acumulan de forma ávida; la cola que superaría la estimación se descarta.
// budget_tokens: 0 (default) = sin límite.

Tip: Combina budget_tokens con budget: "deep" para una ventana de contexto que se mantenga dentro de un techo de tokens fijo sin importar el tamaño de la memoria.

Explorar el índice de memoria (divulgación progresiva)

memory_recall({ mode: "index" }) // o { query, mode: "index" } para una vista filtrada
// 📇 Índice de memoria (15 entradas):
//
// [1] use-zod (a1b2c3d4) · decision · 2026-07-10 · 100%
// [2] redis-cache-config (e5f6g7h8) · decision · 2026-07-09 · 82%
// ...

mode: "index" muestra una línea por entrada — key, id, categoría, fecha, % de relevancia — sin contenido, así que una memoria grande casi no cuesta de explorar. Elige los ids que necesites y recupera las entradas completas en lote:

memory_recall({ ids: "a1b2c3d4,e5f6g7h8" })
// Fetched 2 entries:
// [decision] use-zod (a1b2c3d4)
//   Use Zod for validation
//   File: src/types.ts | Tags: validation;types | Date: 2026-07-10

ids acepta ids o keys de entrada separados por coma/espacio/; y conserva tu orden (las desconocidas se omiten). Tres capas: explora el índice → recupera por ids → busca con mode: "flat" para el ranking completo.

Decisiones descartadas

Registra las opciones que decidiste no tomar para que el agente no vuelva a proponerlas. Una convención ligera — una entrada decision con la etiqueta rejected, sin schema extra:

memory_remember({
  category: "decision",
  key: "rejected-graphql",
  content: "Rejected GraphQL: REST + generated types wins on codegen and schema drift risk.",
  tags: "rejected;api;graphql"
})

Etiqueta la entrada con rejected y usa una key rejected-<tema> para que la palabra clave sea fácil de recuperar. Enlázala a la alternativa ganadora si aporta (links: "rest-api"). El siguiente memory_recall de esa idea saca el rechazo con su razón — tu «no» pasa a formar parte de la memoria del proyecto en vez de re-debatirse en cada sesión.

Buscar con filtro de fecha

memory_recall({
  query: "redis",
  from_date: "2026-07-01",
  to_date: "2026-07-31"
})

Mostrar cambios desde la última sesión

memory_diff({ since: "24h" })
// 📋 Cambios desde 2026-07-11:
//
// ➕ Nuevas (2):
//   [decision] use-zod (a1b2c3d4)
//     Usar Zod para validación
//   [bug] redis-timeout (e5f6g7h8)
//     Arreglo de timeout de conexión Redis

Soporta since como relativo (24h, 7d) o fecha exacta. Filtra por type: all, created, o updated.

Encontrar entradas relacionadas

memory_suggest({ context: "configuración de caché redis" })
// 🔍 Sugerencias para "configuración de caché redis":
//
// [decision] redis-cache-config (a1b2c3d4)
//   Capa de caché Redis para almacenamiento de sesión
//   Archivo: src/cache.ts | Tags: redis;cache | Fecha: 2026-07-10

Archivar entradas antiguas

memory_archive()
// 📦 Archivadas 5 entradas antiguas
// 📋 Quedan 42 entradas activas

Habilitar encriptación

memory_encrypt()
// 🔐 Encriptación habilitada
// ⚠️ Guarda esta clave (no se puede recuperar):
// a1b2c3d4...

Listar sesiones activas y conflictos

memory_sessions({ conflictsOnly: false })
// 🧭 Sesiones activas (2) — ventana 10 min:
//
// • opencode @ feature/foo
//    id: sess-B
//    Archivos:
//      • src/shared.ts
// • claude @ feature/foo (tú)
//    id: sess-A
//
// 🔥 Conflictos suaves (1):
//   ⚠️ src/shared.ts  ↔  opencode@feature/foo, claude@feature/foo

Usa memory_sessions({ conflictsOnly: true }) si solo te interesan los choques. Ver Coordinación multi-sesión más abajo.

Coordinación multi-sesión

Cuando ejecutas varias sesiones de agente de IA en paralelo (ej. tres sesiones de OpenCode en el mismo repo), pueden pisarse el trabajo. memory_sessions es una herramienta de coordinación basada en archivos — sin servidor, sin red, sin llamadas a LLM — que permite a cada sesión ver qué hacen las demás.

Cómo funciona

• Al inicio, un hook SessionStart escribe un archivo de heartbeat para la sesión en .toon-memory/memory/sessions/<id>.json. Cada proceso escribe solo su propio archivo, sin contención de locks.
• El heartbeat registra el nombre del agente, la branch de git, los archivos tocados y un last-seen timestamp.
• Leer entre esos archivos le da a cada sesión una vista compartida, eventualmente consistente, de quién está activo.
• Una sesión está “activa” mientras su heartbeat esté dentro de la ventana TTL (10 min). Sesiones muertas (PID ya no vivo y heartbeat obsoleto) se limpiar perezosamente.
• Los conflictos suaves son archivos tocados por 2+ sesiones activas — surfaca por memory_sessions para que puedas evitar pisar el trabajo de hermanos.

Hábito recomendado para sesiones paralelas

1. Al inicio de sesión, el hook SessionStart imprime otras sesiones activas, sus branches, y conflictos suaves.
2. Antes de editar archivos compartidos, ejecuta memory_sessions() para confirmar que ningún hermano los está tocando.
3. Al terminar, tu heartbeat se marca como terminado y los archivos se liberan.

Memoria como grafo (recall basado en grafo)

Para memorias grandes, una búsqueda plana por palabras clave puede devolver demasiado o perder relaciones. toon-memory puede tratar la memoria como un grafo de conocimiento ligero para que recall devuelva las entradas correctas con menos tokens. Combinado con quality scoring, las entradas más útiles aparecen primero.

Es completamente determinístico y offline — sin embeddings, sin vector DB, sin LLM, sin servidor. Los edges vienen de:

• links explícitos — keys que declaras al guardar una entrada.
• Referencias [[key]] implícitas — cualquier mención [[alguna-key]] dentro del contenido.

Recordar con links

memory_remember({
  category: "decision",
  key: "risk-engine-priority",
  content: "El motor prioriza riesgo sobre velocidad (ver [[risk-spec]]).",
  file: "spec.md:10",
  tags: "risk;spec",
  links: "engine-arch"   // edge explícito a otra entrada
})
// 🧠 Guardado: decision/risk-engine-priority (a1b2c3d4)

Recall con modo grafo

memory_recall({ mode: "graph" }) encuentra coincidencias por palabras clave (seeds) y expande el ego-subgrafo hasta hops (1 o 2). La relevancia se propaga de seeds a vecinos, así que un spec o decisión relacionada aparece aunque no tenga la palabra de búsqueda. El resultado se limita (limit, default 6) para un contexto más pequeño y preciso.

memory_recall({ query: "riesgo", mode: "graph", hops: 2 })
// [decision] risk-engine-priority (a1b2c3d4)
//   El motor prioriza riesgo sobre velocidad (ver [[risk-spec]]).
//   File: spec.md:10 | Tags: risk;spec | Date: 2026-07-01
//   links: engine-arch
//
// [knowledge] risk-spec (a2b3c4d5)
//   Especificación de riesgo para el motor.
//   links: risk-engine-priority;engine-arch
//
// [pattern] engine-arch (e6f7g8h9)
//   Arquitectura del motor.
//   links: risk-spec

Usa mode: "graph" cuando una decisión se extiende a varias entradas (arquitectura, specs, bugs relacionados). Para hechos aislados, el modo flat por defecto es suficiente. El grafo se construye al leer, así que no hay archivo de índice extra que mantener.

Recall eficiente en tokens (compact: true)

Cuando cada token cuenta, pasa compact: true para una salida más densa:

memory_recall({ query: "riesgo", mode: "graph", hops: 2, compact: true })
// [1] decision/risk-engine-priority
//   El motor prioriza riesgo sobre velocidad (ver [[risk-spec]]).
//   tags: risk;spec · edges: ->2, ->3
//
// [2] knowledge/risk-spec
//   Especificación de riesgo para el motor.
//   tags: risk · edges: ->1
//
// [3] pattern/engine-arch
//   Arquitectura del motor.
//   tags: engine · edges: ->1

Qué cambia compact:

• Cada entrada obtiene un índice numérico estable ([1], [2], …) en orden de score.
• id, date y file se eliminan — solo se conserva tags.
• En modo graph, los edges se renderizan como ->2 (numéricos, no nombres de key).
• Los vecinos alcanzados vía el grafo (no-seeds) se truncan a un snippet con elipsis, mientras que los seeds directos conservan su contenido completo.
• El archivo .toon nunca se muta — compact solo reformatea la respuesta.

Cómo ordena recall los resultados

El recall es determinístico y offline (sin embeddings, sin LLM). Cada entrada candidata recibe un score combinado de:

• Relevancia BM25 — score probabilístico de frecuencia de término sobre id + category + key + content + file + tags.
• Centralidad del grafo — normalizado por grado (0..1); un hub conectado a muchas entradas obtiene cerca de 1, así que aparece aunque no tenga la palabra de búsqueda.
• Importancia — recencia + frecuencia de acceso.
• Boost de calidad — entradas con mayor quality score (más tags, links, detalle) obtienen un boost en ranking.
• Bonus de seed — entradas que coinciden directamente con la query obtienen un boost plano.
• Decay por salto — nodos a d hops de un seed se multiplican por 0.5^d, manteniendo el contexto lejano por debajo del cercano.
• Familia de idioma — entradas escritas en la misma escritura que la query (latín/CJK/cirílico/…) obtienen un boost +0.1 vía languageFamily().
• Coincidencia de carpeta — entradas cuyo path_scope coincide con la carpeta del archivo actual obtienen un boost +0.05.
• Importancia explícita — memory_remember({ importance }) te permite establecer critical (+0.3), high (+0.15), medium (0) o low (−0.1); las decisiones critical aparecen antes que las notas low, y el nivel se muestra en las razones de explain y en la salida de budget: "deep". Vacío = automático (recencia + frecuencia).

En modo graph, recall busca por palabras clave, expande el ego-subgrafo hasta hops, y devuelve los top limit (default 6) por score combinado. memory_smart_recall combina todas estas señales en una sola llamada.

Recuperación inteligente (memory_smart_recall)

Búsqueda unificada que combina BM25, grafo, calidad, frescura y decay en una sola llamada:

memory_smart_recall({ intent: "configuración de caché redis", hops: 2 })
// Combina relevancia BM25 + centralidad del grafo + quality score + decay de frescura
// Devuelve los top resultados ordenados por score combinado

Esta es la forma recomendada de recuperar memoria — maneja todo en una sola llamada en vez de requerir orquestación de múltiples herramientas.

Puntuación de calidad

Cada entrada recibe automáticamente una puntuación de calidad (0-1) basada en:

• Cobertura de tags (peso 0.3) — más tags = mayor score
• Riqueza de links (peso 0.2) — más links = más conectada
• Detalle del contenido (peso 0.2) — contenido más largo y detallado = mayor score
• Frescura (peso 0.15) — entradas recientes obtienen un ligero boost
• Especificidad (peso 0.15) — entradas con referencias a archivos y keys específicas obtienen mayor score

Las entradas de alta calidad aparecen primero en los resultados de recall, asegurando que el contexto más útil siempre sea prominente.

Merge-deduplicación

Cuando guardas una entrada con una key existente, el sistema fusiona atributos:

• Tags: unión de ambos conjuntos
• Links: unión de ambos conjuntos
• Calidad: máximo de ambos scores
• Confianza: máximo de ambos scores
• Contenido: se conserva tal cual (sin sobrescribir)
• Fecha: se actualiza a ahora
• Importancia: gana el nivel explícito más alto (critical > high > medium > low)

Esto significa que re-guardar una entrada la enriquece en vez de reemplazarla.

Auto-tag desde dependencias del proyecto

En toon-memory init, el CLI escanea tus manifiestos de dependencias y escribe una tabla vocab en .toon-memory/memory/config.json:

{
  "vocab": {
    "react": ["react"],
    "zod": ["zod"],
    "redis": ["redis"]
  }
}

memory_remember compara nuevas entradas contra este vocabulario además del integrado. Re-ejecuta toon-memory init después de agregar dependencias mayores para actualizarlo. La clave vocab se fusiona (sin sobrescribir) con las flags encrypted/capture en config.json. Más tags = mayor quality score.

Categorías

Las entradas se organizan por categoría:

Categoría	Caso de uso
decision	Decisiones de diseño (“¿Por qué X sobre Y?”)
pattern	Patrones del proyecto (“Usa Zod para validación”)
bug	Arreglos de bugs (“Agotamiento de pool Redis”)
knowledge	Conocimiento general (“El broker usa RESP”)
warning	“NO hagas esto” — antipatrones, trampas, errores a evitar (recuperado con boost +0.2)