# FTS5-Volltextsuche

Synapse verwendet FTS5 (Full-Text Search 5) für schnelle, flexible Memory-Suche.
Diese Seite erklärt, wie es funktioniert und wie du es effektiv nutzt.

## Was ist FTS5?

FTS5 ist eine SQLite-Erweiterung (in PostgreSQL ebenfalls über Erweiterungen
verfügbar), die Volltextsuche bietet. Sie:

- Indiziert Textinhalte für schnelle Keyword-Suche
- Unterstützt boolesche Operatoren (AND, OR, NOT)
- Unterstützt Phrase-Matching mit Anführungszeichen
- Unterstützt Präfix-Matching mit `*`
- Bewertet Ergebnisse nach Relevanz

Synapse nutzt FTS5, um alle Memory-Inhalte zu indizieren — das ermöglicht
sub-millisecond Suche über Tausende von Memories.

## Wie Synapse FTS5 nutzt

Wenn du `POST /memory` aufrufst:

1. Memory-Inhalt wird in der `memories`-Tabelle gespeichert
2. Inhalt wird zusätzlich in die FTS5-Virtual-Table eingefügt
3. FTS5 tokenisiert und indiziert den Inhalt automatisch

Wenn du `GET /memory/search?q=...` aufrufst:

1. Synapse parst die Anfrage mit FTS5-Syntax
2. Führt ein `MATCH` gegen den FTS5-Index aus
3. Filtert nach `mind_id` (Tenant-Isolation)
4. Liefert bewertete Ergebnisse

## Query-Syntax

### Einfache Keyword-Suche

```
?q=docker
```

Liefert Memories, die „docker" enthalten.

### Mehrere Keywords (implizites AND)

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

Liefert Memories, die SOWOHL „docker" ALS AUCH „swarm" enthalten.

### Phrase-Matching

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

Liefert Memories, die die exakte Phrase „docker swarm" enthalten.

### Präfix-Matching

```
?q=docker*
```

Liefert Memories mit Wörtern, die mit „docker" beginnen (z. B. „dockers",
„dockerfile", „dockerize").

### Boolesches OR

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

Liefert Memories, die „docker" ODER „kubernetes" enthalten.

### Boolesches NOT

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

Liefert Memories, die „docker", aber NICHT „swarm" enthalten.

### Gruppierung

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

Liefert Memories mit „docker" oder „kubernetes", aber nicht „test".

## Praktische Beispiele

### Memories zu einem Projekt finden

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

### Exakte Phrase finden

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

### Test-Memories ausschließen

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

### Nach Technologie suchen

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

## Ranking

FTS5 bewertet Ergebnisse nach Relevanz mit dem BM25-Algorithmus. Faktoren:

- Term-Frequency (wie oft der Begriff vorkommt)
- Inverse Document Frequency (seltenere Begriffe ranken höher)
- Dokumentlänge (kürzere Docs mit dem Begriff ranken höher)
- Spalten-Gewichtung (title > content)

Ergebnisse werden in Reihenfolge des Rankings zurückgegeben (relevanteste zuerst).

## Performance

| Operation | Latenz |
|-----------|--------|
| 100 Memories durchsuchen | < 5ms |
| 1.000 Memories durchsuchen | < 10ms |
| 10.000 Memories durchsuchen | < 25ms |
| 100.000 Memories durchsuchen | < 100ms |

FTS5 ist stark für lese-lastige Workloads optimiert.

## Einschränkungen

### Stemming

FTS5 macht standardmäßig kein Stemming. „running" und „run" sind unterschiedliche
Begriffe.

**Workaround:** Präfix-Matching verwenden: `?q=run*`

### Tippfehler-Toleranz

FTS5 unterstützt kein Fuzzy-Matching. Ein Tippfehler liefert keine Ergebnisse.

**Workaround:** Verwende semantische Suche (`/memory/semantic-search`) für
konzeptionelles Matching.

### Stoppwörter

Häufige Wörter (the, a, an, is) werden indiziert, sind aber für die Suche
meist nicht nützlich. FTS5 behandelt das automatisch.

## FTS5 vs semantische Suche

| Aspekt | FTS5 | Semantische Suche |
|--------|------|-------------------|
| Geschwindigkeit | Sub-millisecond | 50-100ms |
| Matching | Exakte Keywords | Konzeptionell |
| Tippfehler-Toleranz | Keine | Etwas |
| Stemming | Keins | Implizit |
| Benötigt Embeddings | Nein | Ja |
| Optimal für | Spezifische Begriffe | Konzepte |

Verwende FTS5, wenn du die Keywords kennst. Verwende semantische Suche, wenn du
„Memories über X" suchst und X anders beschrieben wird.

## Best Practices

> [!TIP]
> - **Verwende spezifische Begriffe** — „docker swarm" schlägt „container orchestration"
> - **Phrasen in Anführungszeichen** — `"docker swarm"` sichert Phrase-Match
> - **Präfix für Variationen** — `deploy*` erfasst „deploy", „deployment", „deploying"
> - **Noise ausschließen** — `-test` filtert Test-Memories heraus
> - **Mit Tags kombinieren** — `?q=docker&tag=production` schränkt Ergebnisse ein

## Nächste Schritte

- [Semantische Suche](/docs/concepts/semantic-search)
- [Memory-API](/docs/api/memory)
- [Memory-Best-Practices](/docs/guides/memory-best-practices)