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 oexternal_identifier.400 invalid_cursor: o valor emafternão vem de uma página anterior. Em uma busca comquery, 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.
