FlowModels

Criar, buscar e alterar memórias de um usuário final pela API

Publicado em 11. novembro 2026

Memórias são fatos curtos sobre um usuário final que o Brain leva em conta em cada requisição dessa pessoa, por exemplo “prefere respostas curtas” ou “a contato em compras é a Sra. Berger”. O Brain cria essas memórias por conta própria. Pela API, você também pode criá-las, buscá-las, alterá-las e excluí-las.

Como as memórias funcionam

Cada memória pertence a exatamente um usuário final da sua equipe. Em requisições futuras com o mesmo external_identifier, usamos as memórias relevantes como contexto. Outros usuários finais nunca as veem. Como o Brain funciona em geral está em Usar o Brain: salvar e continuar conversas por usuário final.

Todas as chamadas precisam de external_identifier, para ficar claro de qual pessoa se trata.

Criar uma memória

curl -X POST https://api.flowmodels.one/v1/memories \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "cliente-1042", "text": "Prefere resumos curtos com três tópicos.", "kind": "preference"}'
  • text é obrigatório e pode ter no máximo 10.000 caracteres.
  • kind é opcional e ajuda você a organizar as memórias.

A resposta contém o id da memória e revision: 1. Guarde a revisão, porque você vai precisar dela ao alterar.

Criar uma memória manualmente funciona mesmo quando a memória automática está desativada para esse usuário final.

Listar ou buscar memórias

GET /v1/memories responde a duas perguntas diferentes:

Listar todas as memórias, as mais recentes primeiro:

curl "https://api.flowmodels.one/v1/memories?external_identifier=cliente-1042&limit=50" \
  -H "Authorization: Bearer at_sua_chave"

Isso é gratuito. Busque as demais páginas com after e o valor de last_id, enquanto has_more estiver como true.

Buscar por significado com query:

curl "https://api.flowmodels.one/v1/memories?external_identifier=cliente-1042&query=contato" \
  -H "Authorization: Bearer at_sua_chave"

A busca também encontra entradas que não contêm o termo literalmente. Ela é paga, porque transformamos o texto da busca em um vetor. O texto da busca pode ter no máximo 1.000 caracteres. Um resultado de busca é uma classificação sem páginas adicionais: has_more fica como false e last_id como null.

Alterar uma memória

curl -X PATCH https://api.flowmodels.one/v1/memories/018f1234-5678-7abc-9def-0123456789ab \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "cliente-1042", "text": "Prefere resumos bem curtos.", "revision": 1}'

Com revision, você informa qual versão quer alterar. Se a memória tiver mudado nesse meio-tempo, por exemplo por um segundo processo da sua aplicação, a API responde com 409 memory_revision_conflict. Nesse caso, busque novamente a versão atual, compare sua alteração e envie de novo com a nova revisão. Assim você nunca sobrescreve sem querer uma versão mais recente.

Excluir uma memória

curl -X DELETE https://api.flowmodels.one/v1/memories/018f1234-5678-7abc-9def-0123456789ab \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "cliente-1042"}'

Se quiser excluir todos os dados de uma pessoa de uma vez, use a exclusão do usuário final, veja Gerenciar e excluir usuários finais pela API: metadados, exclusão e comprovante de exclusão.

Desativar as memórias automáticas

Para novos usuários finais, o Brain cria memórias automaticamente a partir das conversas. Se você não quiser isso para uma pessoa, desative:

curl -X PATCH https://api.flowmodels.one/v1/end-users/018f1234-5678-7abc-9def-0123456789ab \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"memory_extraction_enabled": false}'

Aqui você usa o id do usuário final, vindo de POST /end-users, e não o seu próprio identificador.

Quando algo não funciona

  • 404 memory_not_found: a memória não existe ou pertence a outro usuário final. Verifique o external_identifier.
  • 400 invalid_cursor: o valor em after não vem de uma página anterior. Em uma busca com query, não há páginas adicionais.
  • 409 memory_revision_conflict: veja acima, busque novamente a versão atual.

Quantas memórias um usuário final tem também aparece na interface, em Usuários finais, na coluna Memórias.

A lista de usuários finais com as colunas de arquivos e memórias

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP