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

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

Resposta:

{
  "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

# 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

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

# 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:

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:

# 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

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

Próximos passos

• Busca FTS5
• API de Memória
• Arquitetura