# Busca semântica (embeddings)
SUMMARY: Busca conceitual de memória usando embeddings vetoriais — encontre por significado, não apenas palavras-chave.

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
[CODE BLOCK]
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
[CODE BLOCK]
Resposta:
[CODE BLOCK]
Exemplos
Encontrar memórias de deployment
[CODE BLOCK]
Retorna memórias sobre "deployment", "release", "publishing", "rolling out",
etc.
Encontrar padrões de autenticação
[CODE BLOCK]
Retorna memórias sobre login, auth, JWT, gerenciamento de sessão, OAuth, etc.
Encontrar memórias similares
[CODE BLOCK]
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 —  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 (, )
- Modelos locais (via Ollama ou similar)
- Customizado (implemente a interface de embeddings)
Configure via variáveis de ambiente:
[CODE BLOCK]
Geração em lote
Para minds com muitas memórias sem embeddings:
[CODE BLOCK]
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  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:
-  retorna 503 Service Unavailable
-  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 — 
> - 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
- API de Memória
- Arquitetura