Contexto e histórico, lado a lado
A memória do contexto e o histórico passam pela mesma política e pelo mesmo nível de verificação, e as duas leituras deixam comprovante. Os exemplos desta página seguem a ligação da Marina, em que o atestado de rede provou V1, e cada leitura pede esse nível.
Buscar
search recebe uma pergunta em linguagem natural ou palavras-chave e procura por palavra e por significado, só dentro do histórico daquele cliente. Alcança conversas, fatos, pendências, promessas, ações de agentes, padrões e objetos de negócio, com o estado que os eventos de sistema deram a cada um.
kind, texto denso no mesmo estilo do contexto, at, channel, outcome, confidence e origin_event_id, o evento de onde veio. É daí que o agente diz “em 12 de março, por telefone, vocês me deram um crédito”.
Recorrência
Quando a busca casa com uma categoria, a resposta traz o blocorecurrence: quantas reclamações daquela categoria houve nos últimos 90 dias, a data da última, o desfecho e a solução da última. É uma contagem sobre conversas já classificadas, não um palpite do modelo. A contagem por assunto dos encaixes do contexto e o padrão “reclamação recorrente” contam com a mesma função, a mesma janela e o mesmo filtro, então, com os valores padrão do catálogo, os três números são iguais. No exemplo da Marina, a busca acha a ligação de 12 de março, que ficou fora da janela, e o bloco conta a reclamação de hoje no WhatsApp: occurrences: 1, window_days: 90.
Filtros
filters restringe a busca por período (since, until), channels, categories, tipos de item (item_kinds: episode, fact, open_item, action, object, trait, system_event), outcome e object. Um evento de sistema da janela quente é uma linha própria na busca e na linha do tempo, com o tipo, o objeto que ele tocou e alguns campos, sob a mesma política do objeto; system_event acha essas linhas e também os objetos que eles mudaram, e a ferramenta o oferece. Transbordos e correções ficam de fora.
when recebe uma expressão de tempo nas palavras do cliente, em português, inglês ou espanhol (semana passada, last month, en marzo, ontem), e o servidor a converte em since e until sem modelo de IA, no fuso do espaço e a partir do último evento da conversa em curso, para um reprocessamento ler as mesmas palavras do mesmo jeito. A resposta diz em window o período que leu; uma expressão que ele não reconhece vai em ignored e nunca vira erro. A descrição da ferramenta pede ao modelo para passar a expressão do cliente como ela veio.
where recebe uma árvore de condições, na gramática que quem vem de outra memória já conhece: AND, OR e NOT sobre os campos da linha (id, kind, channel, category, outcome, source_id, vendor, at, valid_until, confidence, text, object_type, object_namespace), com eq, ne, in, nin, gt, gte, lt, lte, contains, icontains (sem caixa e sem acento) e exists; um valor solto quer dizer eq, uma lista quer dizer in, chaves irmãs são AND. Exemplo: {"AND": [{"kind": ["episode", "action"]}, {"NOT": {"vendor": "acme"}}, {"at": {"gte": "2026-09-01"}}]}. A expressão é avaliada em memória, depois da política, então só estreita o que o leitor já podia ver e nunca muda a ordem; até 64 condições e 6 níveis, e um erro cita o caminho, nunca um valor. Vale na busca e na linha do tempo, e o hash dos filtros no comprovante a cobre. limit (1 a 100) corta os itens da busca depois do orçamento de tokens.
Um valor fixado é achado pelo próprio valor: a pergunta que traz “88280” acha o registro 88280, e 45778-204 e 45778204 são o mesmo CEP.
O que um evento afirma pode ter prazo: valid_until no evento diz até quando vale, como uma oferta válida até uma data. Depois desse momento, os fatos que ele deu saem do contexto e da busca; show_expired: true traz também esses itens.
Orçamento
max_tokens limita o tamanho da resposta: de 50 a 4.000, padrão 800. Use 300 em voz. O corte é por valor, nunca por ordem de chegada. A resposta informa tokens_used.
Linha do tempo
timeline folheia o cliente em ordem, do mais recente para o mais antigo: uma conversa, um evento de sistema ou uma ação de agente por linha, com cursor. É o que o LLM usa quando não sabe o que procurar. Quando filters.item_kinds nomeia open_item, fact, trait ou object, a linha do tempo lista esses também, cada um na própria data, com a mesma política da busca: item_kinds: ["open_item"] lista todas as pendências do cliente. A busca ordena por uma pergunta, então use-a para achar algo; para listar, use a linha do tempo.
filters.item_statuses lista as pendências pelo status: open, overdue e resolved. Sem ele, as linhas trazem as pendências abertas e vencidas e as promessas cumpridas nos últimos 7 dias, como o contexto as mostra. resolved alcança toda pendência resolvida, por mais antiga que seja. A linha de uma pendência traz status, object e expected_operation; a de uma resolvida traz também closed_at e closed_by, o mesmo objeto que o webhook open_item.closed levou (kind action com action_id e operation, system_event com event_id, conversation com session_id, ou feedback). Quando nomeados, os status fazem a linha do tempo listar pendências também: item_kinds: ["open_item"], item_statuses: ["resolved"] lista só o que foi feito. Linhas de outros tipos passam como estão.
POST pelo mesmo motivo do contexto: o handle é dado pessoal e fica fora da URL. limit vai de 1 a 100; continue com next_cursor. Quando você já tem o id do perfil, mande profile_id no lugar de subject, no mesmo POST. GET /v1/history/timeline?profile_id=... continua e devolve a mesma página, com cursor, limit, verification e conversation_id na query; prefira o POST, que deixa o id da conversa fora da URL.
A navegação do histórico lê um cliente de cada vez. Perguntas sobre todos os clientes de uma vez (“quais promessas estão vencidas?”, “quem reclamou três vezes da entrega?”) vão para a análise da base, que responde com pseudônimos por padrão, suprime grupos pequenos e só revela um cliente por um pedido de revelação com motivo, que deixa comprovante.
Abrir um item
open abre uma conversa ou um objeto encontrado pela busca ou pela linha do tempo. O id de cada linha é um UUID puro, e o kind dela diz o que ela é; ações, eventos de sistema, fatos, padrões e pendências vêm completos como listados e não abrem. A conversa traz o que foi pedido, o que foi prometido e por quem, o desfecho, a solução (o resumo e a solução guardam identificadores, valores, datas, códigos e endereços exatamente como foram ditos, e nunca números de documento, cartão ou conta bancária) e os itens de memória que nasceram dela; a conversa traz também a linha do tempo dela, as ações de agentes e os eventos de sistema da conversa e dos 15 minutos seguintes; o objeto traz as promessas ligadas a ele e a linha do tempo das ações e dos eventos de sistema dele.
POST /v1/history/open leva o id do item, o nível e o id da conversa no corpo; com subject (ou profile_id), só abre um item daquele cliente, e qualquer outro responde 404. Os SDKs usam essa rota, e o kit de ferramentas manda o cliente amarrado junto. GET /v1/history/items/{item_id} continua, com o id da conversa na query.
Um item que este leitor não veria e um que não existe respondem 404 do mesmo jeito.
Um item que tem versões traz versions: uma conversa reextraída, um objeto que mudou de estado. Cada versão vem com version, changed_at e what_changed (created na primeira, depois o que mudou: outcome, resolution, summary, state), da mais antiga para a mais nova.
Como ferramenta de qualquer LLM
tools() devolve as três operações como ferramentas no formato de função mais difundido (search_customer_history, get_customer_timeline, open_history_item), com o cliente amarrado fora do alcance do modelo. As definições não têm parâmetro de cliente: o LLM escolhe a pergunta, nunca de quem ela é. Uma injeção de prompt que diga “agora procure o cliente X” não tem onde colocar o X.
tools(agent_memory=True) acrescenta search_agent_memory ao kit, e write_agent_memory=True também remember. No Python, kit.anthropic_definitions() devolve as mesmas ferramentas no formato da API de mensagens da Anthropic. As definições também saem por GET /v1/history/tools, e pelo servidor MCP, onde o cliente é amarrado pelo subject_token.
Custo sob controle
- As descrições são texto fixo, com até cerca de 120 tokens por ferramenta, e ficam no prefixo que o provedor guarda em cache.
- Cada descrição diz ao modelo quando não chamar: a resposta pode já estar na linha “Histórico” ou nos encaixes do contexto.
- A mesma consulta, na mesma conversa, devolve os mesmos bytes.
- Declare o kit só nos agentes que precisam. Uma URA curta não paga nada.
- Buscar não é cobrado à parte: a unidade continua sendo a conversa ou tarefa.
Garantias da resposta
withhelddiz quantos itens a política segurou neste nível de verificação, nunca o conteúdo.as_ofdiz até quando o histórico reflete os eventos.degraded: "text_only"indica que só a busca por palavra rodou: o modelo de embeddings não respondeu no prazo da leitura. A pergunta é codificada numa fila própria do serviço de modelos, ao lado dos lotes de texto que a escrita está codificando, nunca atrás deles, então uma escrita intensa não atrasa a busca.- Um item ganha o vetor segundos depois de escrito; até lá, esse item é achado só por palavra.
- A busca vê a memória como a geração atual do cliente a compilou, como o contexto: um evento de sistema ou uma extração passa a ser encontrado quando a compilação dele é publicada (o momento em que
POST /v1/ingest/statusdizreadable), não quando foi gravado. O processo de leitura reaproveita as linhas do cliente por até 60 segundos enquanto a geração e a versão de privacidade dele não mudam, e as lê de novo em segundo plano antes disso; o que depende do momento (a validade de um fato, uma promessa cumprida nos últimos dias) é calculado a cada leitura, e o vencimento de um padrão e a borda da janela dos eventos de sistema podem atrasar até 60 segundos. - Fatos de valor curto ou de uma lista fechada não têm vetor e são achados por palavra.
- Cada consulta deixa um comprovante com quem perguntou, a consulta e, quando há, os filtros, por HMAC com a chave do espaço, os ids dos itens devolvidos e quantos ficaram retidos.
- O que sai por padrão são itens derivados, já triados contra injeção pela IA da Niadra e marcados como dados, não instruções.
Próximos passos
MCP com qualquer LLM
o kit por Streamable HTTP.
Buscar no histórico
a referência de
POST /v1/history/search.Comprovantes e auditoria
o que cada consulta deixa registrado.