# API de Memória
SUMMARY: Referência completa dos 22 endpoints de memória: armazenar, recall, busca, busca semântica, sincronização, auditoria e mais.

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

API de Memória
A API de Memória é o coração do Synapse. Ela oferece 22 endpoints para
armazenar, recuperar, buscar e gerenciar memórias estruturadas. Todos os
endpoints requerem uma Mind Key para autenticação.
> [!CRITICAL]
> Sempre chame  no início de cada sessão. Esta é a
> única forma de reconstruir o contexto de sessões anteriores.
Categorias
As memórias estão organizadas em 8 categorias:
| Categoria | Caso de uso |
|-----------|-------------|
|  | Nome do usuário, papel, contato, preferências sobre si mesmo |
|  | Gostos, desgostos, estilo de trabalho, preferências de comunicação |
|  | Fatos verificáveis (detalhes de projeto, datas, URLs) |
|  | Status de projeto, marcos, arquitetura |
|  | Coisas em que o usuário é bom |
|  | Erros passados — evitar repetir |
|  | Contexto relevante para a sessão |
|  | Notas diversas |
Prioridades
-  — bom saber
-  — padrão
-  — importante
-  — nunca esquecer (identidade do usuário, info jurídica)
Endpoints principais
GET /memory/recall
Retorna TODAS as memórias como texto puro otimizado para LLMs. Chame isso no
início de cada sessão.
[CODE BLOCK]
Resposta (text/plain):
[CODE BLOCK]
POST /memory
Armazena uma nova memória ou atualiza uma existente (mesma categoria + key = atualização).
[CODE BLOCK]
Resposta: 
GET /memory
Lista memórias com filtros opcionais.
[CODE BLOCK]
PUT /memory/:id
Atualiza uma memória específica por ID.
[CODE BLOCK]
DELETE /memory/:id
Exclui uma única memória.
[CODE BLOCK]
Endpoints de busca
GET /memory/search
Busca em texto completo usando FTS5.
[CODE BLOCK]
Sintaxe FTS5:
- Múltiplas palavras = AND: 
- Frase: 
- Prefixo: 
- Booleano: 
- Excluir: 
GET /memory/semantic-search
Busca conceitual usando embeddings (mais lenta que FTS5, mas entende significado).
[CODE BLOCK]
Retorna memórias semanticamente similares à consulta, mesmo que nenhuma palavra-
-chave corresponda. Útil para "encontrar memórias sobre X" quando X é descrito
de outra forma.
GET /memory/by-tag
Lista memórias por tag.
[CODE BLOCK]
GET /memory/related/:id
Encontra memórias relacionadas a uma memória específica (via tags compartilhadas).
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Sincronização incremental — retorna memórias alteradas desde um timestamp.
[CODE BLOCK]
Resposta: 
POST /memory/sync
Aplica um diff de outra instância (para sync auto-hospedado).
[CODE BLOCK]
Operações em massa
POST /memory/bulk-delete
Exclui várias memórias por ID.
[CODE BLOCK]
POST /memory/embed-batch
Gera embeddings para memórias que ainda não os têm (para busca semântica).
[CODE BLOCK]
GET /memory/embed-batch-status
Verifica o progresso da geração de embeddings.
[CODE BLOCK]
Verificação
Memórias têm um flag . Memórias armazenadas pelo agente vêm como não
verificadas por padrão (); memórias armazenadas por humanos são
verificadas ().
POST /memory/verify
Marca uma memória como verificada (requer JWT, não Mind Key).
[CODE BLOCK]
POST /memory/unverify
Marca uma memória como não verificada (requer JWT).
[CODE BLOCK]
GET /memory/unverified
Lista memórias aguardando verificação humana.
[CODE BLOCK]
Estatísticas e auditoria
GET /memory/stats
Estatísticas agregadas para o mind atual.
[CODE BLOCK]
Retorna: 
GET /memory/audit
Log de auditoria de todas as operações que alteram estado.
[CODE BLOCK]
GET /memory/contradictions
Detecta potenciais contradições nas memórias armazenadas.
[CODE BLOCK]
GET /memory/expiring
Lista memórias com datas de expiração se aproximando.
[CODE BLOCK]
Health e exportação
GET /memory/health
Health check rápido do sistema de memória.
[CODE BLOCK]
GET /memory/mind-export
Exportação JSON completa de todas as memórias (para backup).
[CODE BLOCK]
POST /memory/compact
Compacta memórias similares (auto-resumo).
[CODE BLOCK]
Próximos passos
- Quick Start para LLMs
- Melhores práticas de memória
- Busca FTS5
- Busca semântica