# Búsqueda de texto completo FTS5

Synapse usa FTS5 (Full-Text Search 5) para búsqueda de memoria rápida y
flexible. Esta página explica cómo funciona y cómo usarlo eficazmente.

## ¿Qué es FTS5?

FTS5 es una extensión de SQLite (también disponible en PostgreSQL vía
extensiones) que proporciona capacidades de búsqueda de texto completo. Esta
persona:

- Indexa contenido de texto para búsqueda rápida por palabra clave
- Admite operadores booleanos (AND, OR, NOT)
- Admite coincidencia de frases con comillas
- Admite coincidencia por prefijo con `*`
- Ordena resultados por relevancia

Synapse usa FTS5 para indexar todo el contenido de memoria, lo que habilita
búsqueda sub-milisegundo entre miles de memorias.

## Cómo Synapse usa FTS5

Cuando hace `POST /memory`:

1. El contenido de la memoria se almacena en la tabla `memories`
2. El contenido también se inserta en la tabla virtual FTS5
3. FTS5 tokeniza e indexa el contenido automáticamente

Cuando hace `GET /memory/search?q=...`:

1. Synapse parsea la consulta usando la sintaxis FTS5
2. Ejecuta un `MATCH` contra el índice FTS5
3. Filtra por `mind_id` (aislamiento de tenant)
4. Devuelve resultados ordenados por relevancia

## Sintaxis de consulta

### Búsqueda simple por palabra clave

```
?q=docker
```

Devuelve memorias que contienen "docker".

### Múltiples palabras clave (AND implícito)

```
?q=docker+swarm
?q=docker%20swarm
```

Devuelve memorias que contienen BOTH "docker" AND "swarm".

### Coincidencia de frase

```
?q="docker+swarm"
?q=%22docker%20swarm%22
```

Devuelve memorias que contienen la frase exacta "docker swarm".

### Coincidencia por prefijo

```
?q=docker*
```

Devuelve memorias que contienen palabras que comienzan por "docker" (p. ej.
"dockers", "dockerfile", "dockerize").

### OR booleano

```
?q=docker+OR+kubernetes
```

Devuelve memorias que contienen "docker" OR "kubernetes".

### NOT booleano

```
?q=docker+-swarm
?q=docker+NOT+swarm
```

Devuelve memorias que contienen "docker" pero NOT "swarm".

### Agrupamiento

```
?q=(docker+OR+kubernetes)+-test
```

Devuelve memorias que contienen "docker" o "kubernetes", pero no "test".

## Ejemplos prácticos

### Buscar memorias sobre un proyecto

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"
```

### Buscar frase exacta

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"
```

### Excluir memorias de test

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=production+-test"
```

### Buscar por tecnología

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"
```

## Ranking

FTS5 ordena los resultados por relevancia usando el algoritmo BM25. Factores:

- Frecuencia del término (con qué frecuencia aparece)
- Frecuencia inversa de documento (términos más raros obtienen mayor ranking)
- Longitud del documento (documentos más cortos con el término suben)
- Peso de columna (title > content)

Los resultados se devuelven en orden de ranking (más relevantes primero).

## Rendimiento

| Operación | Latencia |
|-----------|---------|
| Search 100 memories | < 5ms |
| Search 1,000 memories | < 10ms |
| Search 10,000 memories | < 25ms |
| Search 100,000 memories | < 100ms |

FTS5 está altamente optimizado para cargas de trabajo con muchas lecturas.

## Limitaciones

### Stemming

FTS5 no hace stemming por defecto. "running" y "run" son términos diferentes.

**Workaround:** Use coincidencia por prefijo: `?q=run*`

### Tolerancia a erratas

FTS5 no admite coincidencia difusa. Una errata no devolverá resultados.

**Workaround:** Use búsqueda semántica (`/memory/semantic-search`) para
coincidencia conceptual.

### Stop words

Las palabras comunes (the, a, an, is) se indexan pero pueden no ser útiles para
la búsqueda. FTS5 lo gestiona automáticamente.

## FTS5 vs Búsqueda semántica

| Aspecto | FTS5 | Búsqueda semántica |
|--------|------|-----------------|
| Velocidad | Sub-milisegundo | 50-100ms |
| Coincidencia | Palabras clave exactas | Conceptual |
| Tolerancia a erratas | Ninguna | Alguna |
| Stemming | Ninguno | Implícito |
| Requiere embeddings | No | Sí |
| Mejor para | Términos específicos | Conceptos |

Use FTS5 cuando conozca las palabras clave. Use búsqueda semántica cuando quiera
"memorias sobre X" donde X se describe de forma diferente.

## Mejores prácticas

> [!TIP]
> - **Use términos específicos** — "docker swarm" vence a "container orchestration"
> - **Encadene frases entre comillas** — `"docker swarm"` garantiza coincidencia de frase
> - **Use prefijo para variaciones** — `deploy*` captura "deploy", "deployment", "deploying"
> - **Excluya ruido** — `-test` filtra memorias de test
> - **Combine con etiquetas** — `?q=docker&tag=production` acota resultados

## Próximos pasos

- [Búsqueda semántica](/docs/concepts/semantic-search)
- [API de Memory](/docs/api/memory)
- [Mejores prácticas de memoria](/docs/guides/memory-best-practices)