rhanka/engram-memory

Memoria Engram a través de MCP

Fuente de verdad: @sentropic/engram 0.22.0 candidato (fb223377), proveedor sentropic.engram.memory, conector engram-memory, contrato 1.0.0. Todo lo marcado como no verificado no está establecido por las fuentes listadas al final.

0. Lo que posee el anfitrión (leer primero)

• Nunca en los argumentos: tenant, workspace, scope, principal, agent_id, sesión, credencial, auditId, fecha límite, cancelación, confirmación (elicitationRef). El anfitrión los vincula por llamada. Cada esquema de entrada está cerrado (additionalProperties: false): un campo extra es INVALID_SCHEMA. Omite campos opcionales; nunca envíes null.
• Aislamiento de tenant y workspace: cada llamada está vinculada a un alcance exacto elegido por el anfitrión; los argumentos no llevan selector de alcance. Los permisos están delimitados por {tenantId, workspaceId} y se rechaza un alcance ajeno. Nunca ves la memoria de otro tenant: un destino desconocido y un destino fuera de tu alcance ambos devuelven NOT_FOUND.
• purpose_ref (búsqueda, obtención, captura) debe coincidir con el propósito vinculado por tu anfitrión; una discrepancia es un rechazo de protocolo. Cómo el anfitrión le dice al agente su purpose_ref está no verificado: si no lo tienes, pregunta al operador del anfitrión.
• Llamadas mutantes (captura, solicitar admisión, retirar, olvidar) pasan la protección de mutación del anfitrión (reserva de idempotencia y resumen de operación). withdraw y forget siempre requieren la protección de confirmación del anfitrión (una aprobación humana vinculada a la capacidad, destino y resumen de operación, TTL de máximo 300 s, ejecución dentro de 30 s). Capture y request_admission lo requieren cuando la selección del anfitrión marca la confirmación como requerida. No puedes confirmar por tu cuenta: un confirmed: true escrito por el modelo no tiene efecto.
• El mantenimiento nunca es una capacidad del agente: administración, arranque, rotación, revocación, copia de seguridad, restauración, migración, invalidación de proyección, sustitución, disputa, retroceso, caducidad, historial o inspección de candidatos están fuera de las seis herramientas. El permiso de mantenimiento (['read','maintain']) es solo del anfitrión y nunca llega a la ruta del agente.
• Cada herramienta se descubre y autoriza de forma independiente; habilitar la memoria no otorga las seis. Una herramienta faltante significa que careces de esa capacidad; ninguna herramienta de memoria significa que la memoria está deshabilitada para ti (deshabilitada por defecto; el anfitrión y el tenant deben aceptarlo). No busques otra ruta.
• Los errores de protocolo no son respuestas de memoria: -32603 Trusted invocation context unavailable (contexto de anfitrión faltante o no confiable, propósito, principal, tenant o fuente no coincidente, referencia de confirmación faltante) y -32602 Unknown tool. Detente, informa al operador del anfitrión, no reintentes con argumentos alterados.

1. Cuándo usar la memoria, y cuándo no

Úsala para conocimiento duradero y reutilizable que valga la pena encontrar de nuevo en una sesión posterior o por otro agente: decisiones con fundamento, hechos verificados sobre un sistema con una fuente citable, convenciones, dificultades recurrentes y su solución, hechos de transferencia.

No la uses para: estado provisional o en curso, transcripciones de chat, salida bruta de herramientas, notas locales a la tarea, especulaciones, o cualquier cosa en §4. Search y get revelan solo registros accepted_current; los registros pendientes, rechazados, retirados, en disputa, históricos, caducados, no confiables y anulados nunca se devuelven.

2. Las seis herramientas

Cada resultado es un sobre. Éxito: {ok: true, output: {schema_version: 1, value}, auditId, redactionClass: "high"}. Fracaso: {ok: false, auditId, redactionClass: "high", error: {code, message, retriable}}. Se transporta en structuredContent con una copia de texto JSON idéntica; isError equivale a !ok. Los mensajes son cadenas sanitizadas constantes: actúa sobre code y retriable, nunca sobre el mensaje.

Codificaciones comunes. Las referencias opacas (purpose_ref, component_id, primary_component_id, citation_id, source_ref, evidence_ref, reason_ref) son cadenas NFC de 1 a 512 bytes UTF-8. Copia candidate_id, record_id y page_cursor exactamente como se devuelven. Los instantes (observed_at, expires_at) son YYYY-MM-DDTHH:mm:ss.sssZ (UTC canónico, precisión de milisegundos). El objeto de argumento serializado tiene como máximo 1.048.576 bytes UTF-8.

engram_memory_search (solo lectura): encuentra memorias actuales con citas y un recibo de clasificación.

• Entrada: query (1 a 8.192 bytes UTF-8), purpose_ref. Opcional: limit (1 a 50, predeterminado 10), max_packet_bytes (4.096 a 1.048.576, predeterminado 65.536), capability_policy {minimum_channels: "lexical" | "lexical_and_semantic", network: "forbid" | "allow"} (predeterminado lexical / forbid; allow no concede nada), page_cursor (el anterior next_page_cursor, misma consulta y parámetros).
• Salida: {records[], rank_receipt, next_page_cursor?, response_digest}; cada paquete de registro es {record, redacted_fields, redaction_receipt_digest, score, rank}. record está redactado; record.record_id siempre está presente.
• Errores típicos: STALE_PAGE (inicia una nueva búsqueda sin page_cursor), RANKING_UNAVAILABLE (un canal semántico requerido está caído; sin respaldo silencioso; reintenta o solicita lexical), PROJECTION_OVERSIZED / RESULT_TOO_LARGE (reduce limit o ajusta max_packet_bytes). Una lista records vacía significa que no hay coincidencia: las fallas de infraestructura nunca se devuelven como un éxito vacío.

engram_memory_get (solo lectura): lee un registro actual conocido sin clasificación.

• Entrada: record_id (patrón ^mem_[a-z2-7]+$), purpose_ref. Opcional: max_packet_bytes.
• Salida: {record, redacted_fields, redaction_receipt_digest, read_receipt, packet_digest}; read_receipt contiene record_id, record_digest, valid_as_of, system_as_of, validated_through_cursor, authorization_receipt_digest, revalidation_receipt_digest, checked_at, receipt_digest.
• Errores típicos: NOT_FOUND (desconocido, fuera de tu alcance, o no elegible actualmente; indistinguible por diseño; no sondees variantes), PROJECTION_OVERSIZED.

engram_memory_capture (anexar): envía material citado como un candidato pendiente cifrado.

• Entrada: idempotency_key, payload, evidence.
  • payload: schema_version: 2, purpose_ref, valid_time {t, t_end?} (enteros seguros, t_end >= t; usa milisegundos de época: la ruta de lectura actual enviada los compara con instantes Date.parse, por lo que otra unidad puede dejar un registro acotado nunca actual), components (1 a 64 de {component_id, kind: "context" | "decision" | "evidence", text (1 a 65.536 bytes), citation_ids (1 a 256, distintos)}), primary_component_id, primary_event {at, type_ref, citation_id} (at es un entero seguro; su unidad está no verificada), citations (1 a 256 de {citation_id, source_ref, locator {scheme, value}, content_digest, observed_at? (Instant)}). Opcional: retention {derivative_rule: "retain" | "make-ineligible", expires_at? (Instant, estrictamente después del tiempo de captura, dentro del techo del anfitrión)}, reconciliation {family_refs} (ordenados, únicos, como máximo 64).
  • Referencias cruzadas: los valores citation_id son únicos; los valores component_id son únicos; cada cita de componente se resuelve en citations; primary_component_id se resuelve en components; primary_event.citation_id está en citations y en el componente principal.
  • evidence: {evidence_ref, evidence_digest, citation_ids (1 a 256, distintos), attestation?}; citation_ids debe resolverse en payload.citations; attestation como máximo 4.096 bytes.
• Salida: {status: "committed_pending" | "duplicate_exact", candidate_id, record_digest?, cursor, transaction_receipt_digest}. duplicate_exact es la repetición de la misma identidad de idempotencia con contenido idéntico.
• Errores típicos: INVALID_SCHEMA (incluyendo un expires_at no posterior al tiempo de captura); UNAUTHORIZED (sin autoridad de captura, retain no permitido por la política del anfitrión, expires_at más allá del techo del anfitrión, una familia de conciliación sin consentimiento del anfitrión); DIGEST_CONFLICT; MUTATION_OUTCOME_UNKNOWN; POLICY_UNAVAILABLE.

engram_memory_request_admission (transición de estado): pide a la política de admisión del anfitrión que decida sobre un candidato pendiente.

• Entrada: candidate_id, idempotency_key.
• Salida: {outcome: {status: "accepted" | "rejected" | "pending_adjudication" | "duplicate_exact", candidate_id, record_id?, cursor, decision_receipt_digest, transaction_receipt_digest}, replayed}. accepted requiere record_id. El motor integrado lo emite en la aceptación; el esquema publicado permite un record_id opcional en otros estados. Interpreta outcome.status y replayed, no solo la presencia de campo; la semántica de admisión duplicate_exact permanece no verificada. rejected y pending_adjudication son resultados de dominio exitosos, no errores.
• Errores típicos: NOT_FOUND, POLICY_STALE (reintentable), DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_withdraw (transición de estado, protegida por confirmación): termina un candidato pendiente.

• Entrada: candidate_id, idempotency_key, reason_ref (referencia opaca, 1 a 512 bytes).
• Salida: {receipt: {event_id, operation: "withdraw", from_state: "pending", to_state: "withdrawn", cursor, event_digest, authorization_receipt_digest, transaction_receipt_digest}, replayed, key_destruction: "pending" | "complete"}.
• Errores típicos: gate_failed (sin confirmación válida del anfitrión), NOT_FOUND, DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_forget (transición de estado, protegida por confirmación): hace que un registro admitido sea definitivamente inelegible.

• Entrada: record_id, idempotency_key, reason_ref.
• Salida: {receipt: {..., operation: "tombstone", from_state: uno de accepted_current | accepted_disputed | historical | expired | trust_invalid, to_state: "tombstoned"}, replayed, projection_invalidation: "pending" | "complete", coverage_receipt_digest?}.
• Errores típicos: como withdraw.

Códigos de error y qué hacer. Si retriable es true, retrocede y reintenta; para una mutación, reintenta con la misma idempotency_key y argumentos idénticos. Si es false, no reintentes sin cambios.

Código	Acción
INVALID_SCHEMA, INVALID_DIGEST	Corrige los argumentos contra el esquema cerrado (límites, NFC, referencias cruzadas, formato de resumen sha256: + 64 hexadecimales en minúscula).
UNAUTHORIZED, AUTHORIZATION_EXPIRED, AUTHORIZATION_REVOKED	Detente. Careces del permiso. Reporta al anfitrión; nunca reintentes bajo otra identidad.
NOT_FOUND	Trata el destino como no disponible para ti. No sondees.
DIGEST_CONFLICT	La clave ya se usó con contenido o destino diferente. Averigua por qué; usa una clave nueva solo para una operación genuinamente nueva.
ILLEGAL_TRANSITION, ALREADY_TERMINAL	El estado del ciclo de vida lo prohíbe. Vuelve a verificar con search o get; no bucles.
MUTATION_OUTCOME_UNKNOWN	Puede haberse confirmado. Reintenta con la misma clave y argumentos hasta obtener un resultado definitivo. Nunca asumas que no pasó nada.
gate_failed	La puerta de confirmación o política no está satisfecha. Pregunta al humano a través del anfitrión.
STALE_PAGE	Nueva búsqueda sin page_cursor.
RESULT_TOO_LARGE, PROJECTION_OVERSIZED	Reduce limit o ajusta max_packet_bytes dentro de los límites.
RATE_LIMITED, DEADLINE_EXCEEDED, CANCELLED, STORE_UNAVAILABLE, FENCE_LOST, CURSOR_GAP, POLICY_UNAVAILABLE, POLICY_STALE, PROJECTION_STALE, RANKING_UNAVAILABLE	Reintentable: retrocede, reintenta (misma clave para mutaciones). Reporta si es persistente.
CAPABILITY_UNAVAILABLE, JOURNAL_CORRUPT, BLOB_MISSING, REGISTRY_VERSION_UNAVAILABLE, BACKUP_INVALID, RESTORE_REFUSED, MIGRATION_LEDGER_INVALID	Falla operativa. Detente y reporta al operador del anfitrión.

3. Disciplina

1. Busca antes de capturar. El duplicate_exact de capture solo cubre un reintento de la misma clave con el mismo contenido; no es una verificación de duplicado semántico. Si existe un registro actual equivalente, cita su record_id en lugar de capturar de nuevo.
2. Capture crea un borrador gobernado. El candidato está pendiente y cifrado; no se puede buscar ni leer, y un candidate_id no es un record_id.
3. La admisión se solicita, nunca se asume. No puedes proporcionar la decisión. Reporta el resultado exacto. Contenido olvidado: una nueva captura aún devuelve committed_pending. En request_admission, una decisión que de otro modo sería aceptante se mantiene como pending_adjudication si el resumen de carga útil efectivo coincide con un registro anulado en el mismo alcance; un rechazo de política ordinario aún devuelve rejected. Reutilizar la clave de captura original con el mismo contenido es una repetición de captura (duplicate_exact), no una nueva adjudicación. Reporta el resultado devuelto; nunca alteres ni reformules el contenido olvidado para eludir esta protección.
4. Procedencia. Cada componente cita al menos una cita; content_digest es un resumen sha256: del contenido citado (canonicalización exacta no verificada). Las citas, evidencia y razones siguen siendo afirmaciones hasta que el verificador del anfitrión las compruebe; la clase de confianza la asigna el anfitrión, nunca por ti. Tu identidad de actor es el principal vinculado al anfitrión, agent_id y sesión; un nombre escrito en text no tiene autoridad.
5. Idempotencia. Las llamadas mutantes necesitan una idempotency_key NFC de 16 a 256 bytes UTF-8 (usa al menos 16 caracteres ASCII; el minLength del JSON Schema publicado es más flexible que la verificación en tiempo de ejecución). Una clave por operación lógica, delimitada a tu principal. Regístrala antes de llamar para que un reintento la reutilice. Misma clave y mismo contenido: repetición (duplicate_exact o replayed: true). Misma clave y contenido, destino o herramienta diferente: DIGEST_CONFLICT. El almacén vincula cada identidad de confirmación a un hash de intención interno; nunca lo envías, y una discrepancia se manifiesta como DIGEST_CONFLICT. Los reintentos reutilizan la retención resuelta en la primera captura.
6. Retención. Omite retention a menos que se indique. La regla derivada predeterminada es make-ineligible; retain necesita un permiso explícito del anfitrión; un expires_at más allá del techo del anfitrión se rechaza con UNAUTHORIZED. No existe un valor de retención aprobado por el propietario en las fuentes: la retención es un punto abierto a nivel de propietario.

4. Lo que nunca se debe almacenar

• Secretos, credenciales, tokens, claves de API o de firma, contraseñas, cadenas de conexión, valores de .env, cookies de sesión, y las credenciales de enlace del propio anfitrión ...