# Búsqueda semántica (embeddings)

Synapse admite búsqueda semántica usando embeddings vectoriales. A diferencia
de FTS5 (coincidencia por palabra clave), la búsqueda semántica encuentra
memorias por **significado** — incluso si no coincide ninguna palabra clave.

## Cómo funciona

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

### ¿Qué son los embeddings?

Los embeddings son representaciones vectoriales numéricas del texto. El texto
con significado similar tiene vectores similares. Synapse genera un vector (p.
ej. 1536 dimensiones) por el contenido de cada memoria.

### Similitud coseno

Para encontrar memorias semánticamente similares, Synapse calcula la similitud
coseno entre el vector de la consulta y cada vector de memoria. Mayor similitud
= más relevante.

## Cuándo usar búsqueda semántica

### Use búsqueda semántica cuando:

- Quiere "memorias sobre X" donde X se describe de forma diferente a como está
  almacenado
- FTS5 no devuelve resultados (sin coincidencia de palabra clave)
- Quiere agrupación conceptual (p. ej. todas las memorias de "deployment",
  incluso si algunas dicen "release")
- La consulta es una pregunta: "¿cómo gestionamos la autenticación?"

### Use FTS5 cuando:

- Conoce palabras clave exactas
- Necesita lógica booleana (AND, OR, NOT)
- Necesita respuesta sub-milisegundo
- Quiere coincidencia 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"
```

Respuesta:

```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
    }
  ]
}
```

## Ejemplos

### Buscar memorias de despliegue

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

Devuelve memorias sobre "deployment", "release", "publishing", "rolling out",
etc.

### Buscar patrones de autenticación

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

Devuelve memorias sobre login, auth, JWT, gestión de sesiones, OAuth, etc.

### Buscar memorias similares

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

Usa similitud semántica (vía etiquetas compartidas Y vectores de embedding).

## Generación de embeddings

### ¿Cuándo se generan los embeddings?

- **Al almacenar memoria** — si el servicio de embeddings está configurado, el
  embedding se genera de forma síncrona
- **Generación en lote** — `POST /memory/embed-batch` genera embeddings para
  memorias que no los tienen
- **Actualizaciones asíncronas** — cuando se actualiza el contenido, el
  embedding se regenera

### Proveedores de embeddings

Synapse admite proveedores de embeddings configurables:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Modelos locales** (vía Ollama o similar)
- **Personalizado** (implementar la interfaz de embeddings)

Configúrelos mediante variables de entorno:

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

### Generación en lote

Para minds con muchas memorias sin 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
```

## Rendimiento

| Operación | Latencia |
|-----------|---------|
| Generate embedding (OpenAI) | 100-200ms |
| Semantic search (1k memories) | 50-100ms |
| Semantic search (10k memories) | 200-500ms |
| Batch generation (100 memories) | 10-20s |

> [!NOTE]
> La búsqueda semántica es más lenta que FTS5 debido al cálculo vectorial. Use
> FTS5 para palabras clave conocidas, semántica para consultas conceptuales.

## Limitaciones

### Costo de embeddings

Si usa OpenAI, generar embeddings cuesta dinero (~$0.02 por 1M tokens para
text-embedding-3-small). Para 10.000 memorias de promedio 100 tokens cada una,
son ~$0.02 — despreciable.

### Arranque en frío

Las memorias almacenadas antes de configurar los embeddings no los tendrán.
Ejecute `POST /memory/embed-batch` para rellenarlas.

### Dependencia del proveedor

Si el proveedor de embeddings está caído, la búsqueda semántica falla de forma
graciosa (devuelve resultados vacíos o un error). FTS5 sigue funcionando.

## Cuando los embeddings no están disponibles

Si el servicio de embeddings no está configurado:

- `GET /memory/semantic-search` devuelve 503 Service Unavailable
- `POST /memory` sigue funcionando (solo no se genera embedding)
- La búsqueda FTS5 sigue funcionando

## Mejores prácticas

> [!TIP]
> - **Use semántica para consultas conceptuales** — "¿cómo gestionamos X?"
> - **Use FTS5 para términos específicos** — "docker swarm"
> - **Rellene los embeddings regularmente** — `POST /memory/embed-batch`
> - **Monitoree la salud del proveedor** — la búsqueda semántica depende de él
> - **Combine con etiquetas** — semántica + filtro por etiqueta acota resultados

## Próximos pasos

- [Búsqueda FTS5](/docs/concepts/fts5-search)
- [API de Memory](/docs/api/memory)
- [Arquitectura](/docs/concepts/architecture)