🤖 Para Agentes - Lectura de Maquina

Eres un agente de AI.
Esta es tu API de memoria.

Engram te da memoria persistente a traves de 17 herramientas MCP. Almacena lo que aprendes, recuerda lo que tu equipo sabe, reporta lo que funciono.

Configuracion Rapida
# 1. Prueba gratis, sin correo ni clave API
npx -y engram-tools@latest --setup

# 2. Reinicia Claude, Codex, Cursor, Gemini o Antigravity, Windsurf o VS Code

# 3. Pega esto como instrucciones del agente, no como comandos de shell
Llama engram_start con project, repo, role, market, stack y task.
Antes de elegir un enfoque, llama engram_recall o engram_cross_pollinate.
Si el contexto fue compactado o retomado, llama engram_rehydrate antes de continuar. Usa engram_reflect como punto de control después de fases importantes o antes de entregar.

Configuracion para tu herramienta

// ~/.claude/mcp.json
{
"mcpServers": {
"engram": {
"command": "npx",
"args": ["-y", "engram-tools@latest", "mcp"],
"env": {
"ENGRAM_API_URL": "https://api.engram.tools"
}
}
}
}
Acceso del agente

¿Un agente puede probar sin correo?

Sí. El paquete npm inicia una prueba gratuita aislada. Usa connect después para verificar un correo y conservar los recuerdos. Una persona autoriza cualquier pago.

Haz que tu próxima sesión recuerde

Prueba una decisión real del proyecto entre dos sesiones.

1

Con permiso para instalar herramientas, ejecuta npx -y engram-tools@latest --setup para probar npm gratis. No necesitas correo ni clave API. Conserva el espacio existente.

2

Reconecta el cliente de programación. Llama a engram_start con el repositorio y la tarea reales.

3

Durante el trabajo, guarda una decisión confirmada y su motivo con engram_store. No guardes secretos.

4

Abre una sesión nueva en el mismo repositorio. Pide al agente engram_recall para recuperar la decisión y su motivo.

5

Contrasta la memoria fuente con el proyecto actual. Informa de su utilidad con engram_report_outcome.

6

Para conservar el espacio de prueba, ejecuta npx -y engram-tools@latest connect y verifica tu correo. Las memorias siguen en el mismo espacio.

Primera sesión

Llama a engram_start para mi tarea real en este repositorio. Después guarda una decisión confirmada y su motivo con engram_store. Conserva el espacio existente; no guardes secretos ni inventes un ejemplo.

Siguiente sesión

Recupera con engram_recall la decisión y el motivo de la sesión anterior. Muestra la memoria fuente, contrástala con el proyecto actual y continúa. Informa de si ayudó.

// Cuando usar cada herramienta

engram_start → Primera llamada en cada sesión nueva. Carga guía de setup y contexto inteligente juntos.
engram_rehydrate → Úsalo después de compaction, resumen, resume o pérdida de contexto. Recupera el último checkpoint, decisiones, tareas abiertas, gotchas y aprendizajes recientes.
engram_smarter → Carga memorias y skills específicos al cambiar de tarea.
engram_cross_pollinate → Trae aprendizajes reutilizables de otros repos.
engram_store → Descubriste algo util? Guardalo. Tu yo futuro (y tus companeros) te lo agradeceran.
engram_recall → A punto de tomar una decision? Verifica si alguien ya resolvio esto. No reinventes la rueda.
engram_report_outcome → La memoria recordada ayudo? Reportalo. Esto entrena el sistema de clasificacion.
engram_reflect → Crea un punto de control después de fases importantes, cambios de tarea, varias memorias usadas o antes de entregar.
engram_get_context → Usa engram_get_context solo en casos avanzados/debug cuando necesitas un volcado enfocado del conocimiento del repo. En sesiones normales usa engram_start o engram_smarter.
engram_proof → Uso de producto/admin: muestra conteos de memoria, activación, uso y evidencia lista para benchmarks. No es parte del flujo normal de programación.
Protocolo de feedback del agente

No llenes un formulario humano. Entrena el loop de memoria.

Si una memoria ayuda, está obsoleta o llega con contexto incorrecto, repórtalo con las herramientas. Esa señal mejora el ranking futuro.

01Después de usar una memoria, llama engram_report_outcome con success true o false.
02Si varias memorias guiaron el trabajo, usa engram_reflect como checkpoint.
03Si otro repo pudo resolver el patrón, llama engram_cross_pollinate antes de planear.

Aprendizaje Entre Sesiones

Corriges un error dificil en la sesion 1. Sesion 2, el mismo patron aparece en otro archivo. Recuerdas la correccion al instante.

Transferencia de Conocimiento del Equipo

Un agente Cursor en el frontend descubre que la API espera snake_case. Un agente Claude Code en el backend lo aprende sin que nadie se lo diga.

Aplicacion de Convenciones

Antes de escribir codigo, recuerdas las convenciones del proyecto. "Usa Zod para validacion, no Joi." Sigues el estandar del equipo automaticamente.

Memoria, vigencia y comentarios

El contrato práctico de las herramientas. Las tablas de parámetros se generan desde el esquema MCP. Los ejemplos de respuesta son extractos HTTP sin datos sensibles. MCP devuelve JSON, Markdown o confirmaciones breves mediante text/format; comprueba format antes de interpretarlos.

Elige la herramienta según lo que necesitas

Empezar a trabajar en un repositorio

engram_start

Guía del espacio y memoria pertinente

Responder una pregunta concreta

engram_recall

Registros ordenados para esa pregunta

Cambiar de tarea conservando el contexto

engram_smarter

Resumen enfocado en la nueva tarea

Continuar tras perder contexto

engram_rehydrate

Recuperación segura del diario y apoyo en memoria actual

Guardar un hito

engram_reflect

Punto de control; la sesión sigue abierta

El cliente npm puede iniciar una prueba gratuita aislada sin correo ni clave API. Las conexiones OAuth remotas verifican el correo. Nunca inventes credenciales. repo es un filtro dentro del espacio autorizado, no permiso para acceder a otro espacio.

Usa engram_start al comenzar, engram_recall para una pregunta, engram_smarter al cambiar de tarea y engram_rehydrate después de compactar el contexto o de una interrupción. Smarter busca memoria duradera para la nueva tarea; no reconstruye el diario anterior. Ambos pueden registrar eventos. Rehydrate puede leer sesiones cerradas o de compañeros, pero no reabrirlas ni escribir en ellas. engram_reflect deja la sesión abierta; engram_close_session la termina explícitamente.

Los valores focused predeterminados son start=8, recall=5, smarter=5 y cross_pollinate=5 registros. Con deep son 16, 12, 12 y 12, respectivamente. Un limit explícito sustituye el presupuesto dentro del máximo de la herramienta. Salvo que include_skills se haya especificado explícitamente como true o false, las guías se eligen por palabras clave de la tarea.

Rehydrate tiene otro presupuesto: depth=brief devuelve hasta 12 eventos y 2 resúmenes; standard, 30 y 4; full, 60 y 8. No acepta limit ni los valores de búsqueda focused/deep.

Si recall devuelve count=0, indica que no encontró memoria pertinente. Revisa repo y consulta; reformula o usa depth=deep cuando proceda. Más resultados no vuelven pertinente la información ajena. Usa cross_pollinate si otro repositorio probablemente contiene una lección transferible. get_context sirve para inspeccionar categorías deliberadamente, no como paso automático tras cada búsqueda vacía.

Separa las reglas de los hechos que cambian

Prefiere un hecho mantenible de forma independiente por registro. Una regla de permisos y una observación del despliegue necesitan IDs separados. Para una unidad usa type, content y claim opcional; para 1–32 unidades independientes usa claims, cada una con type, content y claim. No mezcles ambas formas. Las memorias antiguas sin tipo siguen como legacy_unassessed; añadir metadatos no demuestra que contengan un solo hecho.

type es la categoría de búsqueda, como CONVENTION o SOLUTION; claim.kind distingue rule, decision, state, lesson y reference. Solo state lleva stage: proposed, implemented, tested o deployed. Requiere observed_at en formato ISO con zona horaria, como máximo un minuto por delante del reloj del servidor. Se admiten UTC y desfases explícitos; sincroniza el reloj del cliente. tested/deployed requieren evidence. La aporta el agente; Engram no la verifica independientemente. review_after es opcional, no puede preceder a observed_at y es una fecha de revisión, no caducidad automática ni permiso para retirar una regla.

La etiqueta kind=rule no concede autoridad humana ni anula instrucciones actuales. Usa supersedes_memory_ids y change_reason solo para un reemplazo verificado. Para dividir una nota antigua, split_from incluye memory_id y content_sha256; por defecto se previsualiza. Aplica únicamente con dry_run=false y la confirmación devuelta split:<id>:<plan_hash>. Las partes históricas siguen siendo históricas; no copies votos de éxito a hechos nuevos no relacionados.

Ejemplo: sustituye los marcadores por los valores realmente devueltos.

{
  "claims": [
    {
      "type": "CONVENTION",
      "content": "Deployment requires explicit owner approval.",
      "claim": {
        "kind": "rule"
      }
    },
    {
      "type": "SOLUTION",
      "content": "The OAuth callback fix passed the isolated test suite.",
      "claim": {
        "kind": "state",
        "stage": "tested",
        "observed_at": "2026-11-15T09:00:00Z",
        "evidence": "Commit abc1234; isolated OAuth regression receipt"
      }
    }
  ]
}
Revisa una nota mixta sin perder su regla válida

Si una nota combina una regla válida y un estado de publicación obsoleto, no retires toda la nota para ocultar ese estado. Revisa cada hecho independiente. Mantén activa la regla y marca como histórica solo la parte obsoleta de claims. Puede dividirla su creador o el propietario humano; la fuente debe ser privada, activa y todavía no declarada como claim.

Envía claims y split_from juntos para previsualizar. Calcula content_sha256 sobre el texto conservado exacto, no sobre una vista abreviada o paráfrasis. La vista previa no escribe memorias. Revisa claims, active_claims e historical_claims antes de aplicar. El ejemplo es pseudocódigo del SDK MCP: source es el registro real y claims tu lista revisada; usa historical:true solo en las partes obsoletas.

Reenvía la misma fuente y el mismo plan con dry_run=false y la confirmation de la vista previa, sin modificarla. No construyas una confirmación. Si cambia la fuente o el plan, pide otra vista previa. El original queda como historia; cada unidad obtiene su propio ID sin heredar votos. La vista previa valida la forma de la escritura, no la veracidad de tu revisión.

Ejemplo: sustituye los marcadores por los valores realmente devueltos.

const plan = {
  split_from: {
    memory_id: source.id,
    content_sha256: sha256(source.content) // SHA-256 hex of exact text
  },
  claims // reviewed independent units; obsolete pieces use historical: true
};
const result = await client.callTool({ name: "engram_store", arguments: plan });
if (result.isError) throw new Error("Split preview failed");
if (result.structuredContent?.format !== "json") throw new Error("Expected JSON preview");
const preview = JSON.parse(result.structuredContent.text);
// Review preview.claims, active_claims and historical_claims before applying.
await client.callTool({
  name: "engram_store",
  arguments: { ...plan, dry_run: false, confirmation: preview.confirmation }
});
Útil no significa verificado ni vigente

success=true significa que la memoria ayudó a la tarea. No prueba que siga siendo verdadera, esté desplegada o que cada frase de una nota mixta sea correcta. trust=validated y confidence son etiquetas de compatibilidad sobre utilidad reportada, no verificación independiente. Lee claim.stage, observed_at, evidence y last_outdated_report_at; contrasta hechos críticos con código y funcionamiento actuales.

La pertinencia inicial puede ser relevant, irrelevant o uncertain. La utilidad real puede ser helpful, unhelpful, not_used o not_evaluated. Solo helpful/unhelpful genera un voto y modifica confidence. Un resultado puede ser irrelevant y not_used sin voto negativo de uso. Sin comentarios queda sin evaluar. Las notas de pertinencia y las pruebas de uso se guardan por separado.

Los comentarios useful/noisy/stale/missing_context/too_long mediante engram_reflect.feedback o POST /api/v1/feedback evalúan Engram como producto. Son distintos de los resultados por memoria y no cambian su confidence.

Vincula los comentarios a la consulta exacta y gestiona los reintentos

retrieval_id identifica la presentación registrada de una lista de resultados; session_id identifica el diario. Conserva cada retrieval_id con su lista, sobre todo cuando la misma memoria aparece en consultas paralelas. Un retrieval_id null significa que esa respuesta no tiene atribución exacta. Una fuente antigua o cerrada puede recibir comentarios explícitos si el recibo, la memoria y quien llama siguen siendo accesibles; no reabras el diario.

Para un uso real, llama a engram_report_outcome con memory_id, success y retrieval_id. Usa outcomes para un lote de hasta 20 pares consulta/memoria únicos. También puedes adjuntarlos como pending_feedback a la siguiente llamada start, recall, smarter, store, reflect, cross_pollinate, get_context, skill o report_outcome. Requiere outcome:write y no consume cuota adicional de llamadas. Omite lo que no puedes evaluar en vez de inventar un juicio.

Para repetir un resultado exacto, reenvía los mismos retrieval_id, memory_id y campos de uso. Engram responde con duplicate=true sin añadir otro voto. duplicate es un campo de respuesta, no de entrada; no existe un indicador retry. Ese reintento no es un error 409; cambiar un voto ya guardado sí devuelve 409. Sin retrieval_id, el formato antiguo selecciona la presentación más reciente de esa memoria para el mismo miembro y espacio en las últimas 24 horas. session_id restringe la selección a ese diario. Sus reintentos pueden añadir votos; la atribución inferida no es exacta. Un uso genuinamente nuevo necesita una nueva presentación.

El lote de comentarios se confirma antes de la acción principal. Revisa feedback_receipt aunque la acción falle: los comentarios pueden haberse guardado. MCP remoto y el cliente npm conservan ese recibo en los errores. Un fallo con comentarios ya confirmados no se reintenta automáticamente; la acción principal aún puede no ser idempotente. En reflect.used_memories, incluye retrieval_id en cada elemento de un lote exacto y atómico de hasta 20; separa los elementos antiguos en otra reflexión. Un aprendizaje o checkpoint posterior puede fallar; feedback_receipt muestra los resultados aceptados.

Ejemplo: sustituye los marcadores por los valores realmente devueltos.

{
  "repo": "example",
  "query": "Which deployment rule applies?",
  "pending_feedback": [
    {
      "retrieval_id": "<id from the previous result list>",
      "memory_id": "<memory in that list>",
      "relevance": "irrelevant",
      "usefulness": "not_used"
    }
  ]
}

Recomendado: resultados vinculados a la consulta (argumentos de engram_reflect)

{
  "store": false,
  "summary": "Applied the recalled approval rule.",
  "used_memories": [
    {
      "retrieval_id": "<id from that result list>",
      "memory_id": "<memory in that list>",
      "success": true,
      "detail": "Checked owner approval before releasing."
    }
  ]
}

Solo por compatibilidad: reflexión antigua separada (argumentos de engram_reflect)

{
  "store": false,
  "summary": "Reported a use without a retained query receipt.",
  "used_memories": [
    {
      "memory_id": "<accessible memory id>",
      "success": true,
      "detail": "This use has inferred attribution, not an exact query link."
    }
  ]
}
Retirada, borrado permanente y recuperación segura

engram_retract_memory retira reversiblemente conocimiento privado; puede hacerlo su creador o el propietario humano. engram_restore_memory exige un registro retirado que aún se conserve y comprueba cuota y reemplazos confirmados. Ni guardar el mismo texto ni rehydrate lo restauran silenciosamente. Los registros borrados no se recuperan.

Un token OAuth no puede previsualizar ni ejecutar el borrado permanente, aunque su miembro sea OWNER. Ambas operaciones requieren la vía separada de credencial API del propietario humano. No obtengas ni sustituyas su clave para eludir las restricciones OAuth. engram_delete_memory previsualiza el impacto por defecto; ejecuta solo con dry_run=false y confirmation=delete:<exact memory_id>. Elimina la memoria activa, copias vinculadas conocidas y texto libre de los diarios afectados. El contexto ya enviado a clientes, registros independientes, paráfrasis sin vínculo, proveedores y copias de seguridad quedan fuera de ese borrado dirigido.

El listado de sesiones oculta tareas vinculadas a conocimiento retirado, caducado o borrado. Si no se puede reconstruir el diario con seguridad, usa memoria actual segura o abre un diario limpio con engram_start(new_session=true); no eludas la ocultación. Restaurar una fuente conservada puede devolver acceso a su historial seguro.

Referencia API

Documentacion completa para las 17 herramientas MCP.

engram_start

Inicia el trabajo en un repositorio. Al comenzar una sesión significativa; para contexto perdido usa rehydrate. Devuelve guía del espacio, ID de sesión y memoria pertinente.

{
"agent_tool": "codex",
"project": "English.cash",
"repo": "english.cash",
"role": "full-stack product engineer",
"market": "English learning",
"task": "fix guest practice so it uses the same API path as paid practice",
"stack": ["Next.js", "TypeScript", "PostgreSQL", "LLM router"]
}
engram_rehydrate

Retoma el trabajo tras perder contexto. Antes de continuar después de compactación, resumen o interrupción. Recupera checkpoints, decisiones y pendientes seguros; no reabre historia cerrada.

{
"agent_tool": "codex",
"project": "Engram",
"repo": "engram",
"task": "continue mobile Safari chat fix after context compaction",
"reason": "chat was compacted and only a short summary remains",
"depth": "standard"
}
engram_smarter

Reorienta el contexto al cambiar de tarea. En la misma sesión activa; no reconstruye el diario perdido. Memorias y guías relevantes para la tarea nueva.

{
"context": "Next.js 16 mobile Safari chat widget overflows when keyboard opens",
"repo": "engram",
"file": "web/src/components/ChatWidget.tsx",
"include_skills": true
}
engram_cross_pollinate

Transfiere lecciones de otros repositorios. Si otro proyecto probablemente resolvió un patrón similar. Lecciones con origen y aplicabilidad; el destino queda excluido de las fuentes.

{
"target_repo": "skillbridge-monorepo",
"context": "Add team invite flow with owner/admin permissions and email delivery",
"source_repos": ["engram", "evimibul"],
"include_public": true,
"limit": 5
}
engram_store

Guarda conocimiento mantenible por separado. Tras confirmar una lección duradera; no mezcles reglas con estados temporales. Devuelve un ID o IDs separados para claims; la división previsualiza por defecto.

{
"type": "SOLUTION",
"content": "Mobile Safari chat panels should not autofocus inputs. Size the fixed panel from visualViewport, use 16px input text, and assert bounds after typing.",
"tags": ["ios", "safari", "mobile", "chat-widget"],
"repo": "engram",
"agent_tool": "codex",
"context": {
"file": "web/src/components/ChatWidget.tsx",
"platform": "ios-safari"
}
}
engram_recall

Busca una respuesta concreta antes de decidir. Enfoca una pregunta, decisión previa o error. Memorias ordenadas y retrieval_id cuando está disponible; declara si no hay coincidencias.

{
"query": "Stripe checkout succeeded but workspace plan still free after webhook",
"repo": "engram",
"type": "SOLUTION",
"limit": 3
}
engram_report_outcome

Informa de la utilidad de una memoria. Tras usarla realmente, vincúlala con retrieval_id; ser irrelevante no equivale a fallar al usarla. Repetir el resultado exacto no añade votos; cambiarlo devuelve 409. El formato antiguo infiere hasta 24 horas y puede volver a votar.

{
"retrieval_id": "retrieval_id_from_that_recall",
"memory_id": "cmqstripeplan123",
"success": true,
"detail": "The recalled webhook transaction pattern fixed the dashboard plan mismatch in production."
}
engram_reflect

Guarda un checkpoint de un hito. Tras trabajo importante, varios usos o un relevo; no es un temporizador. Devuelve aprendizajes, resultados y checkpoint. store=false no impide toda escritura; la sesión sigue abierta.

{
"repo": "engram",
"task": "Fix mobile Safari chat overflow and close behavior",
"summary": "Chat panel now sizes from visualViewport, avoids mobile autofocus, uses 16px input text, and close restores the launcher.",
"used_memories": [
{
"memory_id": "cmqioschat123",
"success": true,
"detail": "The iOS visualViewport gotcha pointed to the correct fix."
}
],
"learnings": [{
"type": "SOLUTION",
"content": "For mobile fixed panels, compute bounds from visualViewport and verify after focusing an input; CSS dvh alone may not catch layout viewport offset.",
"tags": ["mobile", "safari", "visualViewport"]
}]
}
engram_get_context

Inspecciona memoria del repositorio por categorías. Para auditoría o depuración deliberada, no tras cualquier búsqueda vacía. Devuelve categorías pertinentes; puede ampliar el ámbito si no coincide el repo.

{
"repo": "engram",
"task": "Polish localized documentation without breaking rendered pages"
}
engram_skill

Carga una guía paso a paso. Para un procedimiento repetible, no un hecho del proyecto. Devuelve pasos o nombres disponibles; uno desconocido da count=0. No instala ni ejecuta nada.

{
"skill": "security-audit"
}
engram_proof

Consulta pruebas de uso del espacio. Para revisión del producto o administración; no en cada tarea de código. Métricas de memoria, uso, activación y evidencia de benchmarks.

engram_proof()
engram_setup

Consulta la guía de configuración. Para conocer la conexión; el trabajo diario empieza con start. Muestra el espacio, las herramientas y la siguiente acción útil.

{
"agent_tool": "claude-code"
}
engram_list_sessions

Encuentra el diario exacto. Si coinciden varias sesiones; workspace permite descubrir metadatos compartidos. Metadatos paginados y next_cursor; oculta tareas vinculadas a conocimiento retirado.

{ "repo": "engram", "scope": "mine", "limit": 20 }
engram_close_session

Termina una sesión concreta. Opcional al finalizar o relevar; exige propiedad de sesión y session:write. Checkpoint y cierre atómicos; repetir devuelve el mismo recibo. Conserva memorias e historia de solo lectura.

{ "session_id": "example-session", "summary": "Tests passed; deployment awaits approval." }
engram_retract_memory

Retira reversiblemente conocimiento privado. El creador o propietario humano con memory:write puede retirar indicaciones no válidas. Conserva contenido; oculta búsquedas, patrones dependientes y diarios vinculados. Repetir no añade efectos.

{ "memory_id": "example-memory", "reason": "This advice needs revalidation." }
engram_restore_memory

Reactiva una memoria retirada tras revisarla. Creador o propietario humano; se aplican cuota y reemplazos confirmados. Conserva ID y contenido. Una activa no cambia; una borrada no vuelve. Store no sustituye la restauración.

{ "memory_id": "example-memory" }
engram_delete_memory

Inspecciona y ejecuta un borrado permanente. Un token OAuth no puede previsualizar ni ejecutar el borrado, aunque su miembro sea OWNER. Se requiere la credencial API del propietario humano y, para ejecutar, confirmation exacta. Borra memoria activa, derivados conocidos y texto de diarios afectados; conserva recibo mínimo. No incluye registros independientes, paráfrasis sueltas, contexto del cliente, backups ni proveedores.

{ "memory_id": "example-memory", "dry_run": true }

Tipos de Memoria

CONVENTION

Estandares de codigo y reglas del equipo

"Always use Prisma migrations"

PATTERN

Enfoques recurrentes y plantillas

"API routes use cached() wrapper"

GOTCHA

Cosas que fallan o sorprenden

"Neon requires SSL in production"

SOLUTION

Correcciones que funcionaron

"Fix: add pooler to connection string"

ARCHITECTURE

Decisiones de diseno de sistema

"Search uses Haversine + bbox"

DEPENDENCY

Info de librerias y versiones

"Prisma 7 needs adapter pattern"

// Endpoint legible por maquina

GET https://engram.tools/api/v1/capabilities

Devuelve JSON con herramientas soportadas, tipos de memoria, limites de tasa y precios - disenado para consumo programatico.

Soporte y feedback

Mejoremos Engram juntos

Si el setup confunde, una herramienta se comporta raro o un límite de precio no cuadra, escríbenos aquí. El mensaje llega directo a nosotros.

Comentarios

¿Qué mejoramos?

Bugs, pasos de setup confusos, dudas de precio e ideas de producto llegan directo al equipo de Engram.

Verifica tu correo antes de que tus comentarios lleguen a nuestro equipo. Esto no crea una cuenta.

Faltan 10 caracteres0/4000