Memória

Memória#

O agente aprende com o uso — separado do conhecimento que você semeia. Dois mecanismos trabalham juntos, e as rotas abaixo (todas sob /v1/agents/{id}, JWT/API key) operam os dois:

1. Memória de conversa (verbatim) — 100% das trocas guardadas e pesquisáveis, por agente. Com conversation_recall: true no agente, trechos de conversas anteriores do mesmo end-user voltam ao contexto do turno (escopado por end_user_external_id).
2. Memória curada (L3 → L4) — a cada turno o agente anota observações L3 (insights do dia); o ciclo dream revisa a pilha, remove duplicatas e promove o que presta a memórias L4 de longo prazo (fatos, preferências, sínteses — o perfil do end-user).

GETInsights do dia (L3)#

GET /v1/agents/{id}/daily — as anotações episódicas do agente, mais novas primeiro: { entries: [ { id, day, type, content, promoted, session_id, created_at } ], total }. promoted: true = já revisada pelo dream.

DELETELimpar insights#

DELETE /v1/agents/{id}/daily → 200 { deleted } — esvazia os insights L3 do agente (a memória L4 não é tocada). DELETE .../daily/{entryID} apaga um insight só → 200 { deleted }.

GETMemórias de longo prazo (L4)#

GET /v1/agents/{id}/memories — as memórias curadas do agente: { memories: [...], total } (vazio se a memória não estiver configurada).

DELETEEsquecer uma memória#

DELETE /v1/agents/{id}/memories/{docID} → 200 { deleted } — esquece uma memória L4 (soft-delete, escopado a conta+agente).

GETMemória de conversa (verbatim)#

GET /v1/agents/{id}/conversation-memory — todas as trocas guardadas: { exchanges: [...], total }.

POSTSonhar (dream)#

POST /v1/agents/{id}/dream — roda o ciclo completo de 3 fases: Light (dedup dos insights L3) → Deep (curadoria dos sobreviventes para L4) → REM (consolidação da coleção L4 da conta). Resposta 200 com os contadores (considered, duplicates, promoted, …). Erro: 503 MEMORY_NOT_CONFIGURED.

POST /v1/agents/{id}/memory/consolidate — limpeza one-shot: reprocessa TODA a pilha L3 (inclusive já promovida) e cura para L4. Use uma vez para migrar um agente que acumulou insights velhos/repetidos.

POSTSonhar com progresso (SSE)#

POST /v1/agents/{id}/dream/stream?mode=consolidate|cycle — a variante SSE do dream: emite um evento progress por fase (start → progress* → done/error), para uma UI acompanhar ao vivo. mode=consolidate (default) reprocessa a pilha inteira; mode=cycle processa só o L3 não promovido (a passada de rotina). Roda fora do timeout de 30s — um consolidate grande faz dezenas de chamadas de LLM e leva minutos.