# Semantic Search (Embeddings)

Synapse supports semantic search using vector embeddings. Unlike FTS5 (keyword
matching), semantic search finds memories by **meaning** — even if no keywords
match.

## How It Works

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

### What are embeddings?

Embeddings are numerical vector representations of text. Text with similar
meaning has similar vectors. Synapse generates a vector (e.g. 1536 dimensions)
for each memory's content.

### Cosine similarity

To find semantically similar memories, Synapse computes the cosine similarity
between the query vector and each memory vector. Higher similarity = more
relevant.

## When to Use Semantic Search

### Use semantic search when:

- You want "memories about X" where X is described differently than stored
- FTS5 returns no results (no keyword match)
- You want conceptual grouping (e.g. all "deployment" memories, even if some say "release")
- Query is a question: "how do we handle authentication?"

### Use FTS5 when:

- You know exact keywords
- You need boolean logic (AND, OR, NOT)
- You need sub-millisecond response
- You want phrase matching

## Endpoint

### GET /memory/semantic-search

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

Response:

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

## Examples

### Find deployment memories

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

Returns memories about "deployment", "release", "publishing", "rolling out",
etc.

### Find authentication patterns

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

Returns memories about login, auth, JWT, session management, OAuth, etc.

### Find similar memories

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

Uses semantic similarity (via shared tags AND embedding vectors).

## Embedding Generation

### When are embeddings generated?

- **On memory store** — if embeddings service is configured, embedding is generated synchronously
- **Batch generation** — `POST /memory/embed-batch` generates embeddings for memories missing them
- **Async updates** — when content is updated, embedding is regenerated

### Embedding providers

Synapse supports configurable embedding providers:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Local models** (via Ollama or similar)
- **Custom** (implement the embeddings interface)

Configure via environment variables:

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

### Batch generation

For minds with many memories missing 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
```

## Performance

| Operation | Latency |
|-----------|---------|
| Generate embedding (OpenAI) | 100-200ms |
| Semantic search (1k memories) | 50-100ms |
| Semantic search (10k memories) | 200-500ms |
| Batch generation (100 memories) | 10-20s |

> [!NOTE]
> Semantic search is slower than FTS5 due to vector computation. Use FTS5
> for known keywords, semantic for conceptual queries.

## Limitations

### Embeddings cost

If using OpenAI, generating embeddings costs money (~$0.02 per 1M tokens
for text-embedding-3-small). For 10,000 memories averaging 100 tokens each,
that's ~$0.02 — negligible.

### Cold start

Memories stored before embeddings were configured won't have embeddings. Run
`POST /memory/embed-batch` to backfill.

### Provider dependency

If the embeddings provider is down, semantic search fails gracefully (returns
empty results or error). FTS5 still works.

## When Embeddings Aren't Available

If embeddings service is not configured:

- `GET /memory/semantic-search` returns 503 Service Unavailable
- `POST /memory` still works (just no embedding generated)
- FTS5 search still works

## Best Practices

> [!TIP]
> - **Use semantic for conceptual queries** — "how do we handle X?"
> - **Use FTS5 for specific terms** — "docker swarm"
> - **Backfill embeddings regularly** — `POST /memory/embed-batch`
> - **Monitor provider health** — semantic search depends on it
> - **Combine with tags** — semantic + tag filter narrows results

## Next Steps

- [FTS5 Search](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Architecture](/docs/concepts/architecture)