# Búsqueda semántica (embeddings)
SUMMARY: Búsqueda conceptual de memoria usando embeddings vectoriales — encuentre por significado, no solo por palabras clave.

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
[CODE BLOCK]
¿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
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
Ejemplos
Buscar memorias de despliegue
[CODE BLOCK]
Devuelve memorias sobre "deployment", "release", "publishing", "rolling out",
etc.
Buscar patrones de autenticación
[CODE BLOCK]
Devuelve memorias sobre login, auth, JWT, gestión de sesiones, OAuth, etc.
Buscar memorias similares
[CODE BLOCK]
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 —  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 (, )
- Modelos locales (vía Ollama o similar)
- Personalizado (implementar la interfaz de embeddings)
Configúrelos mediante variables de entorno:
[CODE BLOCK]
Generación en lote
Para minds con muchas memorias sin embeddings:
[CODE BLOCK]
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  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:
-  devuelve 503 Service Unavailable
-  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 — 
> - 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
- API de Memory
- Arquitectura