Cookbook MCP

A superfície MCP é como agentes devem falar com o ValorBrain. Esta página é sobre fluxos; o contrato mecânico completo das 92 ferramentas (descrição + input schema, direto dos metadados de registerTool()) vive em /mcp-schemas.md e é regenerado a cada build da documentação. Se um campo aqui não está nesse dump, não use.

Detalhes de conexão estão em Ferramentas MCP. O código abaixo mostra o nome da ferramenta e os argumentos como qualquer cliente MCP os passaria.

O loop de sessão

Um turno de agente contra o ValorBrain são quatro chamadas, não quarenta:

1. memory_prepare — monte o contexto uma vez, no início do turno.
2. trabalhe, pense, chame o que precisar (memory_retrieve só se o prepare ficou curto).
3. memory_store — escreva de volta o que é durável.
4. memory_used — declare quais memórias de fato sustentaram a resposta.

1. Preparar o contexto

{
  "tool": "memory_prepare",
  "arguments": {
    "message": "the user's message for this turn",
    "surface_id": "claude-code",
    "recall_budget": 600
  }
}

Uma chamada devolve: hits de recall + fatos do vault + foresights + o funil (episódios, lições, keyed facts, top documentos). fast_mode: true pula a recuperação de documentos do funil para hooks críticos de latência; o recall ainda cobre documentos por categoria. Recuperação com escopo: episode_id vincula a um episódio de diálogo, collection estreita o funil.

Não responda a partir das suas suposições antes desta chamada quando a pergunta é sobre este deploy — a memória é a autoridade, seus dados de treino não são.

2. Recuperar (quando o prepare não basta)

{
  "tool": "memory_retrieve",
  "arguments": {
    "query": "one clear question",
    "mode": "auto",
    "limit": 12,
    "snippet_chars": 200
  }
}

• Uma consulta bem-formulada. O servidor expande e funde; cinco recuperações quase-duplicadas custam 5× e ranqueiam pior que uma.
• mode: auto roteia (porquê → causal, última sessão → timeline, relacionado → vizinhos); keyword / semantic / causal / timeline / discovery / complex / hybrid explícitos quando você sabe melhor.
• limit (alias max_results): padrão 12; 15–20 para tópicos amplos.
• budget é um orçamento de tokens para recall ranqueado por categoria — um eixo diferente de limit.
• Snippets voltam por padrão (snippet_chars); chame get/multi_get só quando o snippet não bastar.

String exata, chave, data, identificador? Isso não é uma busca — isso é memory_grep:

{ "tool": "memory_grep", "arguments": { "pattern": "VALORBRAIN_LLM_MODEL", "max_results": 20 } }

3. Escrever de volta o que é durável

{
  "tool": "memory_store",
  "arguments": {
    "type": "decision",
    "title": "OpenAPI served live from routes[] table",
    "content": "Static YAML drifts from the real route table. Decision: /openapi.json is now generated per request from routes[] merged with the YAML contract; servers[] rewritten from VALORBRAIN_PUBLIC_URL. Rejected: keeping a generated file on disk (another drift source).",
    "tags": ["api", "openapi"],
    "confidence": 0.85,
    "visibility": "tenant"
  }
}

O tipo escolhe a semântica:

Título de 5–200 chars (é o que a busca mostra); conteúdo ≥ 20 chars — inclua contexto, raciocínio, evidência, não só a conclusão. visibility: "private" esconde a memória do resto do tenant (a posse continua sua); compartilhada no tenant é o padrão e o produto.

Não armazene: transcrições de chat (ingeridas automaticamente), conteúdo cru de arquivos, notas de rascunho — scratchpad existe para efêmeros e nunca é indexado.

4. Declarar uso

{
  "tool": "memory_used",
  "arguments": { "docids": ["#ab12cd"], "verdict": "confirmed" }
}

verdict: "confirmed" quando o usuário concordou com o que a memória disse, "corrected" quando ele rebateu. É o sinal de ranking mais forte que existe — memórias usadas sobem, ignoradas decaem. Custa uma chamada; pular isso deixa o ranking cego.

Fatos que não podem ficar desatualizados

Documentos em prosa envelhecem mal; keyed facts carregam uma data e um nível de autoridade:

{
  "tool": "upsert_keyed_fact",
  "arguments": {
    "fact_key": "embedding.production.model",
    "fact_value": "LFM2.5-Embedding-350M-finetuned-v3",
    "as_of": "2026-08-31",
    "evidence": "systemd unit MODEL_PATH, checked on host",
    "authority": "human"
  }
}

authority: human > designated > import > agent. Quando um documento contradiz um keyed fact, o fato vence. Leia com keyed_facts_as_of (viagem no tempo: último valor por chave com as_of <= date). Quando achar um documento agora errado, não apenas lembre do novo valor — assert_authority_correction persiste o fato corrigido e marca os valores anteriores como superseded.

Maquinaria de confiança

Decisões com trilha

{
  "tool": "decisions",
  "arguments": {
    "action": "record",
    "category": "architecture",
    "scenario": "serving OpenAPI",
    "reasoning": "routes[] is the truth; YAML is the contract",
    "outcome": "live merge, mtime-cached YAML",
    "confidence": 0.85
  }
}

Depois ligue a causalidade: action: "relate" com caused / influenced / precedent_for. Mais tarde: find_causal_links ("o que levou a X"), decisions action: "trace" (cadeia completa), action: "similar" (busca semântica de precedentes). Registros são hash-chained — a trilha é à prova de adulteração por construção.

Conflitos

conflicts action: "detect" escaneia contradições de valor / temporais / de relacionamento; action: "list" as enfileira por severidade; action: "resolve" escolhe uma estratégia (most_recent, credibility_weighted, …). A detecção também roda no tick de consolidação, então uma lista limpa não significa sem conflitos — significa nenhum detectado ainda.

Grafo de conhecimento

kg_query para os relacionamentos de uma entidade (multihop com o engine híbrido ligado), kg_explain para o porquê de um fato valer (árvores de prova de derivação quando registradas), append_entity_card para entradas IDENTITY/ATTRIBUTE/RELATIONSHIP/INSTRUCTION num card estável. Triplas que falham no pre-check SHACL caem em kg_quarantine — aprove ou rejeite deliberadamente, elas nunca entram no grafo silenciosamente.

Cure antes de se afogar

{
  "tool": "memory_curate",
  "arguments": { "action": "pin", "query": "priority order latency onboarding correctability" }
}

• pin — boost de +0.3, permanente. Use quando o usuário declara uma restrição persistente ou corrige uma interpretação errada pela última vez.
• snooze — oculta por N dias (until como data ISO, padrão 30). Use quando o contexto do vault insiste em trazer à tona algo irrelevante agora.

Ambos resolvem memórias por consulta de busca — sem docids. memory_pin / memory_snooze são os verbos mais antigos; memory_curate é o que você deve usar.

Estado de trabalho entre sessões

• task_state action: "goal" — o que pronto significa; entregue em todo bloco __goals__. action: "progress" — marcos (janela de 48h). action: "read" — inspecionar.
• episodes — resumos de diálogo delimitados para recuperação episódica; memory_arcs — fios narrativos ligando episódios a um objetivo.
• record_lesson / list_lessons — lições procedurais por surface, com scores de follow-through; verify=true quando a lição se provou de novo.
• diary — diário observacional para eventos que valem revisão depois, em ambientes sem suporte a hook.

Coordenação de time

• team_briefing no início da sessão: inbox não lido, handoffs pendentes, missão compartilhada, atividade recente.
• team_handoff action: "create" entrega trabalho assíncrono durável a um colega (to, summary, open_questions, files_changed, priority). status: "blocked_on_human" estaciona esperando um humano — o verbo anti-loop. action: "consume" fecha quando terminado.
• team_message — fire-and-forget; team_notify_human — puxa um humano agora pelo canal dele.
• notifications — seu inbox; marque como lido depois de tratar.

Operações (jobs longos, com segurança)

Reindex, builds de grafo e syncs de vault são operações longas com handles: reindex / build_graphs / vault_sync aceitam run_async: true e devolvem um id; operation_status (com long-poll via wait_ms), operation_list, operation_cancel os gerenciam. Um reindex escrito pela metade é pior que nenhum — prefira o cancel cooperativo a matar o processo.

Superfícies de saúde: index_stats (distribuição de conteúdo, staleness), memory_health, usage_report, harness_coverage (quem usa MCP mas nunca entrega sessões) (ops por canal/ferramenta/latência — o mesmo ledger que o REST /reports/usage lê), list_vaults.

Quando algo está quebrado no próprio produto

feedback action: "submit" — resultados vazios onde deveria existir conhecimento, ranking errado, ferramenta dando erro. Um contorno silencioso deixa o defeito no lugar para todos os outros agentes; o relato do defeito é a chamada que sustenta o sistema.