Memória Engram via MCP

O que Memória Engram via MCP faz?

Verdade fundamental: @sentropic/engram 0.22.0 candidate (fb223377), provedor sentropic.engram.memory, conector engram-memory, contrato 1.0.0. Qualquer coisa marcada como não verificado não é estabelecida pelas fontes listadas no final.

0. O que o host possui (leia primeiro)

• Nunca nos argumentos: tenant, workspace, escopo, principal, agent_id, sessão, credencial, auditId, prazo, cancelamento, confirmação (elicitationRef). O host os vincula por chamada. Cada esquema de entrada é fechado (additionalProperties: false): um campo extra é INVALID_SCHEMA. Omita campos opcionais; nunca envie null.
• Isolamento de tenant e workspace: cada chamada é vinculada a um escopo exato escolhido pelo host; os argumentos não carregam seletor de escopo. As concessões são escopadas por {tenantId, workspaceId} e um escopo estrangeiro é recusado. Você nunca vê a memória de outro tenant: um destino desconhecido e um destino fora do seu escopo retornam NOT_FOUND.
• purpose_ref (search, get, capture) deve ser igual ao propósito vinculado pelo seu host; uma incompatibilidade é uma recusa de protocolo. Como o host informa o purpose_ref ao agente é não verificado: se você não o tiver, pergunte ao operador do host.
• Chamadas mutantes (capture, request_admission, withdraw, forget) passam pela proteção de mutação do host (reserva de idempotência e resumo da operação). withdraw e forget sempre exigem a proteção de confirmação do host (uma aprovação humana vinculada à capacidade, destino e resumo da operação, TTL de no máximo 300 s, execução em 30 s). Capture e request_admission exigem quando a seleção do host marca a confirmação como obrigatória. Você não pode confirmar em seu próprio nome: um confirmed: true escrito pelo modelo não tem efeito.
• Manutenção nunca é uma capacidade do agente: admin, bootstrap, rotate, revoke, backup, restore, migrate, invalidação de projeção, supersede, dispute, rewind, expire, histórico ou inspeção de candidato estão fora das seis ferramentas. A concessão de manutenção (['read','maintain']) é exclusiva do host e nunca atinge o caminho do agente.
• Cada ferramenta é descoberta e autorizada de forma independente; ativar a memória não concede todas as seis. Uma ferramenta ausente significa que você não tem essa capacidade; nenhuma ferramenta de memória significa que a memória está desabilitada para você (desabilitada por padrão; host e tenant devem optar por ativar). Não procure outra rota.
• Erros de protocolo não são respostas de memória: -32603 Contexto de invocação confiável indisponível (contexto de host ausente ou não confiável, propósito, principal, tenant ou fonte incompatíveis, referência de confirmação ausente) e -32602 Ferramenta desconhecida. Pare, relate ao operador do host, não repita com argumentos alterados.

1. Quando usar a memória, e quando não usar

Use-a para conhecimento durável e reutilizável que vale a pena encontrar novamente em uma sessão posterior ou por outro agente: decisões com raciocínio, fatos verificados sobre um sistema com uma fonte citável, convenções, armadilhas recorrentes e suas correções, fatos de hand-off.

Não use para: estado temporário ou em andamento, transcrições de chat, saída bruta de ferramentas, notas locais de tarefas, especulação ou qualquer coisa no §4. Search e get revelam apenas registros accepted_current; registros pendentes, rejeitados, retirados, disputados, históricos, expirados, inválidos por confiança e tombstoned nunca são retornados.

2. As seis ferramentas

Cada resultado é um envelope. Sucesso: {ok: true, output: {schema_version: 1, value}, auditId, redactionClass: "high"}. Falha: {ok: false, auditId, redactionClass: "high", error: {code, message, retriable}}. Ele é transportado em structuredContent com uma cópia de texto JSON idêntica; isError é igual a !ok. As mensagens são strings sanitizadas constantes: aja em code e retriable, nunca na mensagem.

Codificações comuns. Referências opacas (purpose_ref, component_id, primary_component_id, citation_id, source_ref, evidence_ref, reason_ref) são strings NFC de 1 a 512 bytes UTF-8. Copie candidate_id, record_id e page_cursor exatamente como retornados. Instantes (observed_at, expires_at) são YYYY-MM-DDTHH:mm:ss.sssZ (UTC canônico, precisão de milissegundos). O objeto de argumento serializado tem no máximo 1.048.576 bytes UTF-8.

engram_memory_search (somente leitura): encontre memórias atuais com citações e um recibo de classificação.

• Entrada: query (1 a 8.192 bytes UTF-8), purpose_ref. Opcional: limit (1 a 50, padrão 10), max_packet_bytes (4.096 a 1.048.576, padrão 65.536), capability_policy {minimum_channels: "lexical" | "lexical_and_semantic", network: "forbid" | "allow"} (padrão lexical / forbid; allow não concede nada), page_cursor (o next_page_cursor anterior, mesma consulta e parâmetros).
• Saída: {records[], rank_receipt, next_page_cursor?, response_digest}; cada pacote de registro é {record, redacted_fields, redaction_receipt_digest, score, rank}. record é redigido; record.record_id está sempre presente.
• Erros típicos: STALE_PAGE (inicie uma nova pesquisa sem page_cursor), RANKING_UNAVAILABLE (um canal semântico necessário está inativo; sem fallback silencioso; repita ou solicite lexical), PROJECTION_OVERSIZED / RESULT_TOO_LARGE (reduza limit ou ajuste max_packet_bytes). Uma lista records vazia significa nenhuma correspondência: falhas de infraestrutura nunca são retornadas como sucesso vazio.

engram_memory_get (somente leitura): leia um registro atual conhecido sem classificação.

• Entrada: record_id (padrão ^mem_[a-z2-7]+$), purpose_ref. Opcional: max_packet_bytes.
• Saída: {record, redacted_fields, redaction_receipt_digest, read_receipt, packet_digest}; read_receipt contém record_id, record_digest, valid_as_of, system_as_of, validated_through_cursor, authorization_receipt_digest, revalidation_receipt_digest, checked_at, receipt_digest.
• Erros típicos: NOT_FOUND (desconhecido, fora do seu escopo ou não atualmente elegível; indistinguível por design; não investigue variantes), PROJECTION_OVERSIZED.

engram_memory_capture (anexar): envie material citado como um candidato pendente criptografado.

• Entrada: idempotency_key, payload, evidence.
  • payload: schema_version: 2, purpose_ref, valid_time {t, t_end?} (inteiros seguros, t_end >= t; use milissegundos epoch: o caminho de leitura atual enviado os compara com instantes Date.parse, então outra unidade pode deixar um registro limitado nunca atual), 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 é um inteiro seguro; sua unidade é não verificado), 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, estritamente após o momento da captura, dentro do teto do host)}, reconciliation {family_refs} (classificado, único, no máximo 64).
  • Referências cruzadas: valores citation_id são únicos; valores component_id são únicos; toda citação de componente resolve em citations; primary_component_id resolve em components; primary_event.citation_id está em citations e no componente primário.
  • evidence: {evidence_ref, evidence_digest, citation_ids (1 a 256, distintos), attestation?}; citation_ids deve resolver em payload.citations; attestation no máximo 4.096 bytes.
• Saída: {status: "committed_pending" | "duplicate_exact", candidate_id, record_digest?, cursor, transaction_receipt_digest}. duplicate_exact é a repetição da mesma identidade de idempotência com conteúdo idêntico.
• Erros típicos: INVALID_SCHEMA (incluindo um expires_at não após o momento da captura); UNAUTHORIZED (sem autoridade de captura, retain não permitido pela política do host, expires_at além do teto do host, uma família de reconciliação sem consentimento do host); DIGEST_CONFLICT; MUTATION_OUTCOME_UNKNOWN; POLICY_UNAVAILABLE.

engram_memory_request_admission (transição de estado): peça à política de admissão do host para decidir sobre um candidato pendente.

• Entrada: candidate_id, idempotency_key.
• Saída: {outcome: {status: "accepted" | "rejected" | "pending_adjudication" | "duplicate_exact", candidate_id, record_id?, cursor, decision_receipt_digest, transaction_receipt_digest}, replayed}. accepted requer record_id. O mecanismo integrado o emite na aceitação; o esquema publicado permite um record_id opcional em outros status. Interprete outcome.status e replayed, não meramente a presença do campo; a semântica de admissão duplicate_exact permanece não verificado. rejected e pending_adjudication são resultados de domínio bem-sucedidos, não erros.
• Erros típicos: NOT_FOUND, POLICY_STALE (repetível), DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_withdraw (transição de estado, protegido por confirmação): encerre um candidato pendente.

• Entrada: candidate_id, idempotency_key, reason_ref (referência opaca, 1 a 512 bytes).
• Saída: {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"}.
• Erros típicos: gate_failed (nenhuma confirmação de host válida), NOT_FOUND, DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_forget (transição de estado, protegido por confirmação): torne um registro admitido permanentemente inelegível.

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

Códigos de erro e o que fazer. Se retriable for true, recue e repita; para uma mutação, repita com a mesma idempotency_key e argumentos idênticos. Se false, não repita inalterado.

Código	Ação
INVALID_SCHEMA, INVALID_DIGEST	Corrija os argumentos de acordo com o esquema fechado (limites, NFC, referências cruzadas, formato de resumo sha256: + 64 hex minúsculo).
UNAUTHORIZED, AUTHORIZATION_EXPIRED, AUTHORIZATION_REVOKED	Pare. Você não tem a concessão. Reporte ao host; nunca repita sob outra identidade.
NOT_FOUND	Trate o destino como indisponível para você. Não investigue.
DIGEST_CONFLICT	A chave já foi usada com conteúdo ou destino diferente. Descubra por quê; use uma nova chave apenas para uma operação genuinamente nova.
ILLEGAL_TRANSITION, ALREADY_TERMINAL	O estado do ciclo de vida proíbe. Verifique novamente com search ou get; não faça loop.
MUTATION_OUTCOME_UNKNOWN	Pode ter sido confirmado. Repita com a mesma chave e argumentos até um resultado definitivo. Nunca presuma que nada aconteceu.
gate_failed	Portão de confirmação ou política não satisfeito. Pergunte ao humano através do host.
STALE_PAGE	Nova pesquisa sem page_cursor.
RESULT_TOO_LARGE, PROJECTION_OVERSIZED	Reduza limit ou ajuste max_packet_bytes dentro dos limites.
RATE_LIMITED, DEADLINE_EXCEEDED, CANCELLED, STORE_UNAVAILABLE, FENCE_LOST, CURSOR_GAP, POLICY_UNAVAILABLE, POLICY_STALE, PROJECTION_STALE, RANKING_UNAVAILABLE	Repetível: recue, repita (mesma chave para mutações). Reporte se persistente.
CAPABILITY_UNAVAILABLE, JOURNAL_CORRUPT, BLOB_MISSING, REGISTRY_VERSION_UNAVAILABLE, BACKUP_INVALID, RESTORE_REFUSED, MIGRATION_LEDGER_INVALID	Falha operacional. Pare e reporte ao operador do host.

3. Disciplina

1. Pesquise antes de capturar. O duplicate_exact da captura cobre apenas uma repetição da mesma chave com o mesmo conteúdo; não é uma verificação de duplicata semântica. Se existir um registro atual equivalente, cite seu record_id em vez de capturar novamente.
2. Capturar cria um rascunho governado. O candidato está pendente e criptografado; não é pesquisável ou legível, e um candidate_id não é um record_id.
3. A admissão é solicitada, nunca presumida. Você não pode fornecer a decisão. Reporte o resultado exato. Conteúdo esquecido: uma nova captura ainda retorna committed_pending. Em request_admission, uma decisão de outra forma aceitante é mantida como pending_adjudication se o resumo do payload efetivo corresponder a um registro tombstoned no mesmo escopo; uma rejeição de política comum ainda retorna rejected. Reutilizar a chave de captura original com o mesmo conteúdo é uma repetição de captura (duplicate_exact), não uma nova adjudicação. Reporte o resultado retornado; nunca altere ou reformule conteúdo esquecido para contornar esta proteção.
4. Proveniência. Cada componente cita pelo menos uma citação; content_digest é um resumo sha256: do conteúdo citado (canonicalização exata não verificado). Citações, evidências e razões permanecem afirmações até que o verificador do host as verifique; a classe de confiança é atribuída pelo host, nunca por você. Sua identidade de ator é o principal vinculado ao host, agent_id e sessão; um nome escrito em text não carrega autoridade.
5. Idempotência. Chamadas mutantes precisam de uma idempotency_key NFC de 16 a 256 bytes UTF-8 (use pelo menos 16 caracteres ASCII; o minLength do JSON Schema publicado é mais flexível do que a verificação em tempo de execução). Uma chave por operação lógica, escopada ao seu principal. Registre-a antes de chamar para que uma repetição a reutilize. Mesma chave e mesmo conteúdo: repetição (duplicate_exact ou replayed: true). Mesma chave e conteúdo, destino ou ferramenta diferentes: DIGEST_CONFLICT. O armazenamento vincula cada identidade de confirmação a um hash de intenção interno; você nunca o envia, e uma incompatibilidade aparece como DIGEST_CONFLICT. Repetições reutilizam a retenção resolvida na primeira captura.
6. Retenção. Omita retention a menos que instruído. A regra derivada padrão é make-ineligible; retain precisa de uma permissão explícita do host; um expires_at além do teto do host é recusado com UNAUTHORIZED. Nenhum valor de retenção aprovado pelo proprietário existe nas fontes: retenção é um ponto aberto de nível de proprietário.

4. O que nunca armazenar

• Segredos, credenciais, tokens, chaves de API ou de assinatura, senhas, strings de conexão, valores .env, cookies de sessão e as próprias crenças de ligação do host...