# 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 `GET /memory/recall` 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 |
|-----------|-------------|
| `identity` | Nome do usuário, papel, contato, preferências sobre si mesmo |
| `preference` | Gostos, desgostos, estilo de trabalho, preferências de comunicação |
| `fact` | Fatos verificáveis (detalhes de projeto, datas, URLs) |
| `project` | Status de projeto, marcos, arquitetura |
| `skill` | Coisas em que o usuário é bom |
| `mistake` | Erros passados — evitar repetir |
| `context` | Contexto relevante para a sessão |
| `note` | Notas diversas |

## Prioridades

- `low` — bom saber
- `normal` — padrão
- `high` — importante
- `critical` — 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.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Resposta (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

Armazena uma nova memória ou atualiza uma existente (mesma categoria + key = atualização).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Resposta: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Lista memórias com filtros opcionais.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Atualiza uma memória específica por ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Exclui uma única memória.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Endpoints de busca

### GET /memory/search

Busca em texto completo usando FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

Sintaxe FTS5:

- Múltiplas palavras = AND: `docker swarm`
- Frase: `"docker swarm"`
- Prefixo: `docker*`
- Booleano: `docker OR kubernetes`
- Excluir: `docker -swarm`

### GET /memory/semantic-search

Busca conceitual usando embeddings (mais lenta que FTS5, mas entende significado).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

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.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Encontra memórias relacionadas a uma memória específica (via tags compartilhadas).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Sync & Diff

### GET /memory/diff

Sincronização incremental — retorna memórias alteradas desde um timestamp.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Resposta: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Aplica um diff de outra instância (para sync auto-hospedado).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Operações em massa

### POST /memory/bulk-delete

Exclui várias memórias por ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Gera embeddings para memórias que ainda não os têm (para busca semântica).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Verifica o progresso da geração de embeddings.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Verificação

Memórias têm um flag `verified`. Memórias armazenadas pelo agente vêm como não
verificadas por padrão (`source=agent`); memórias armazenadas por humanos são
verificadas (`source=user`).

### POST /memory/verify

Marca uma memória como verificada (requer JWT, não Mind Key).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

Marca uma memória como não verificada (requer JWT).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

Lista memórias aguardando verificação humana.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Estatísticas e auditoria

### GET /memory/stats

Estatísticas agregadas para o mind atual.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Retorna: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Log de auditoria de todas as operações que alteram estado.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Detecta potenciais contradições nas memórias armazenadas.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Lista memórias com datas de expiração se aproximando.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Health e exportação

### GET /memory/health

Health check rápido do sistema de memória.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Exportação JSON completa de todas as memórias (para backup).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Compacta memórias similares (auto-resumo).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Próximos passos

- [Quick Start para LLMs](/docs/getting-started/quick-start-llm)
- [Melhores práticas de memória](/docs/guides/memory-best-practices)
- [Busca FTS5](/docs/concepts/fts5-search)
- [Busca semântica](/docs/concepts/semantic-search)