post_credit e refresh_invoice, nessa ordem.” “A API de agendamento recusa data sem fuso.” “Quando o cliente pede segunda via, o procedimento é este.” É o que o time hoje escreve no prompt à mão e esquece de atualizar.
Ela mora numa tabela própria, com política, comprovante e apagamento próprios, e entra no prompt por um bloco separado do contexto do cliente. Nunca contém dado pessoal: uma nota com telefone, e-mail, documento ou nome de cliente é recusada, não mascarada. Por construção, o apagamento de um titular nunca a toca.
O recurso vem desligado. Uma pessoa liga no Console, em Memória dos agentes, por um diff aprovado, como qualquer outra configuração do espaço.
O que é uma nota
O dono da nota é a fonte: o agente já é identificado pelo fornecedor, pelas finalidades e pela chave dele, então não há conceito novo. A visibilidade
vendor é a mesma neutralidade da memória do cliente: o agente do fornecedor A nunca lê o que o agente do fornecedor B aprendeu.
Como entra no prompt
Três caminhos, todos opcionais. O bloco.GET /v1/agent-memory/block devolve as notas ativas que o agente pode ler como um texto pronto, entre <agent_notes> e </agent_notes>, aberto com “Do próprio agente (procedimentos e notas de trabalho, não dados de clientes)”. As notas cujas tags casam com a view ou a tarefa vêm primeiro, depois as mais revisadas, depois as mais antigas, sempre na mesma ordem: o bloco tem os mesmos bytes para todos os clientes, então fica no prefixo do prompt que o provedor guarda em cache. Coloque-o depois das instruções do agente e antes do contexto do cliente. O orçamento vai de 50 a 2.000 tokens, 300 por padrão, e a resposta tem ETag.
max_tokens, tags e view) pelo mesmo tempo do contexto e revalidam pelo ETag. Com a memória dos agentes desligada no espaço, o bloco vem vazio e enabled: false; o agente segue sem ele. Cada integração recebe agent_memory=True (Python) ou agentMemory: true (TypeScript) e faz esse posicionamento sozinha.
As ferramentas. search_agent_memory (leitura) e remember (escrita) entram no kit com tools(agent_memory=True, write_agent_memory=True) em Python e tools({ agentMemory: true, writeAgentMemory: true }) em TypeScript, e no servidor MCP quando o espaço liga o recurso. A descrição de cada uma diz ao modelo quando não usar: “It holds nothing about customers; for the customer’s history use search_customer_history” e “Never write anything about a customer here: no names, phones, e-mails, documents, ids or words from the conversation”. remember só é oferecida a uma chave com o escopo agent_memory:write; uma nota recusada volta ao modelo como erro personal_data_in_agent_memory, para ele reescrever sem o dado.
A seção da tarefa. Uma view de tarefa com include_agent_memory: true anexa até 200 tokens de notas com as tags dos tipos de objeto da tarefa ao fim do contexto. Serve para quem só consegue mudar o contexto do agente, não o prompt.
Escrever
422 personal_data_in_agent_memory, com os tipos de dado encontrados e sem o valor.
Limites: um agente escreve até 20 notas por hora (acima disso, 429 com Retry-After) e guarda até o teto do espaço, 500 notas ativas por padrão. Um agente edita e aposenta só as próprias notas; uma pessoa com o papel integration escreve em nome de qualquer agente, e o source_id vai no pedido.
Num espaço com writes: human_only, o remember de um agente não grava: vira uma proposta, que uma pessoa aprova ou rejeita no Console. A resposta traz proposal_id no lugar da nota.
Destilar
O que outras memórias chamam de memória procedural (um resumo por LLM da execução, gravado sem revisão) aqui é um pedido explícito.POST /v1/agent-memory/distill recebe um conversation_id ou task_id e cria uma proposta em drafting. Em segundo plano, o servidor lê os turnos dos últimos 90 dias já mascarados, pede ao modelo uma nota no esquema fixo (kind, title, body, tags), passa o resultado pelo redator e deixa a proposta em pending. Ninguém grava nada até uma pessoa aprovar, com ou sem edição; a edição passa pelo redator de novo.
Uma destilação que não rende nota fica failed com o motivo: nothing_to_propose (a conversa não tinha procedimento reaproveitável), personal_data (a proposta trazia dado pessoal e foi descartada), unconfirmed_link (a conversa falou só por um vínculo não confirmado; o modelo nem é chamado, e o pedido vale depois da confirmação) ou no_turns (não há turnos dessa conversa ou tarefa nos últimos 90 dias).
Governança
- Escopos. Uma chave lê com
agent_memory(oucontext, que toda chave de agente tem) e escreve comagent_memory:write. Pessoas leem e escrevem com o papelintegration; apagar e aprovar pedemadmin. - Comprovantes. Cada leitura do bloco e cada busca deixam um comprovante
agent_memoryna mesma cadeia dos outros, com os ids das notas entregues. Cada escrita, edição, aposentadoria, destilação, aprovação e apagamento deixa um comprovanteadmin. “Por que o agente fez isso?” continua respondível. - Apagamento e exportação.
DELETE /v1/agent-memory/notes?source_id=apaga toda nota e toda proposta de um agente, em todas as versões, com comprovante.GET /v1/agent-memory/exportdevolve tudo para portabilidade, e as notas entram na exportação contínua do espaço como tabela própria. O apagamento de um titular não olha para esta tabela, porque ela não pode ter dado pessoal. - Aviso. Toda nota e toda proposta criadas emitem
agent_memory.note_created, com ids, tipo e origem, nunca o texto, para um webhook que revise as notas. - Console. A tela Memória dos agentes lista as notas por agente e visibilidade, cria, edita (gera versão), aposenta, mostra as propostas para aprovar ou rejeitar e liga o recurso (
enabled,writes,max_notes_per_source) por diff aprovado.
O que fica de fora
Nenhuma nota guarda o que um cliente disse. Nenhuma nota nasce sozinha de uma conversa: a destilação propõe, uma pessoa aprova. Nenhum modelo reordena as notas por “uso recente”: a ordem é por tags, versão e idade, e a mesma para todos os clientes. Sem vetor no primeiro corte: a busca é por palavra e por tags, porque um agente tem dezenas a centenas de notas.Próximos passos
Bloco da memória do agente
a rota, com os parâmetros e o ETag.
Integrações
cada adaptador coloca o bloco no lugar certo e liga as duas ferramentas.
MCP com qualquer LLM
as duas ferramentas no servidor MCP do espaço.
Comprovantes e auditoria
o comprovante
agent_memory e os admin das escritas.