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

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

Respuesta:

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

# 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

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

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

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

Generación en lote

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

Rendimiento

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

Próximos pasos

• Búsqueda FTS5
• API de Memory
• Arquitectura