# Busca semântica (embeddings)

O Synapse suporta busca semântica usando embeddings vetoriais. Diferente do
FTS5 (correspondência de palavras-chave), a busca semântica encontra memórias
por **significado** — mesmo que nenhuma palavra-chave corresponda.

## Como funciona

```
1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned
```

### O que são embeddings?

Embeddings são representações vetoriais numéricas de texto. Textos com
significado similar têm vetores similares. O Synapse gera um vetor (ex.: 1536
dimensões) para o conteúdo de cada memória.

### Similaridade de cosseno

Para encontrar memórias semanticamente similares, o Synapse calcula a
similaridade de cosseno entre o vetor da consulta e cada vetor de memória.
Maior similaridade = mais relevante.

## Quando usar busca semântica

### Use busca semântica quando:

- Você quer "memórias sobre X" onde X é descrito de forma diferente do que foi armazenado
- FTS5 não retorna resultados (nenhuma palavra-chave corresponde)
- Você quer agrupamento conceitual (ex.: todas as memórias de "deployment", mesmo que algumas digam "release")
- A consulta é uma pergunta: "como tratamos autenticação?"

### Use FTS5 quando:

- Você conhece as palavras-chave exatas
- Você precisa de lógica booleana (AND, OR, NOT)
- Você precisa de resposta sub-milissegundo
- Você quer correspondência de frase

## Endpoint

### GET /memory/semantic-search

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

Resposta:

```json
{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}
```

## Exemplos

### Encontrar memórias de deployment

```bash
# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process
```

Retorna memórias sobre "deployment", "release", "publishing", "rolling out",
etc.

### Encontrar padrões de autenticação

```bash
curl .../memory/semantic-search?q=how+do+users+log+in
```

Retorna memórias sobre login, auth, JWT, gerenciamento de sessão, OAuth, etc.

### Encontrar memórias similares

```bash
# Find memories similar to a specific one
curl .../memory/related/mem_001
```

Usa similaridade semântica (via tags compartilhadas E vetores de embedding).

## Geração de embeddings

### Quando os embeddings são gerados?

- **No armazenamento de memória** — se o serviço de embeddings estiver configurado, o embedding é gerado sincronamente
- **Geração em lote** — `POST /memory/embed-batch` gera embeddings para memórias que não os têm
- **Atualizações assíncronas** — quando o conteúdo é atualizado, o embedding é regenerado

### Provedores de embedding

O Synapse suporta provedores de embedding configuráveis:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Modelos locais** (via Ollama ou similar)
- **Customizado** (implemente a interface de embeddings)

Configure via variáveis de ambiente:

```bash
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small
```

### Geração em lote

Para minds com muitas memórias sem embeddings:

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

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

## Desempenho

| Operação | Latência |
|----------|----------|
| Gerar embedding (OpenAI) | 100-200ms |
| Busca semântica (1k memórias) | 50-100ms |
| Busca semântica (10k memórias) | 200-500ms |
| Geração em lote (100 memórias) | 10-20s |

> [!NOTE]
> Busca semântica é mais lenta que FTS5 devido à computação vetorial. Use
> FTS5 para palavras-chave conhecidas, semântica para consultas conceituais.

## Limitações

### Custo dos embeddings

Se usar OpenAI, gerar embeddings custa dinheiro (~$0.02 por 1M tokens para
text-embedding-3-small). Para 10.000 memórias com média de 100 tokens cada,
são ~$0.02 — insignificante.

### Cold start

Memórias armazenadas antes de os embeddings serem configurados não terão
embeddings. Execute `POST /memory/embed-batch` para preencher retroativamente.

### Dependência de provedor

Se o provedor de embeddings cair, a busca semântica falha graciosamente
(retorna resultados vazios ou erro). FTS5 continua funcionando.

## Quando embeddings não estão disponíveis

Se o serviço de embeddings não estiver configurado:

- `GET /memory/semantic-search` retorna 503 Service Unavailable
- `POST /memory` ainda funciona (apenas nenhum embedding é gerado)
- Busca FTS5 ainda funciona

## Melhores práticas

> [!TIP]
> - **Use semântica para consultas conceituais** — "como tratamos X?"
> - **Use FTS5 para termos específicos** — "docker swarm"
> - **Preencha embeddings regularmente** — `POST /memory/embed-batch`
> - **Monitore a saúde do provedor** — a busca semântica depende disso
> - **Combine com tags** — semântica + filtro de tag estreita os resultados

## Próximos passos

- [Busca FTS5](/docs/concepts/fts5-search)
- [API de Memória](/docs/api/memory)
- [Arquitetura](/docs/concepts/architecture)