# Semantic Search (Embeddings)
SUMMARY: Conceptual memory search using vector embeddings — find by meaning, not just keywords.

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
[CODE BLOCK]
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
[CODE BLOCK]
Response:
[CODE BLOCK]
Examples
Find deployment memories
[CODE BLOCK]
Returns memories about "deployment", "release", "publishing", "rolling out",
etc.
Find authentication patterns
[CODE BLOCK]
Returns memories about login, auth, JWT, session management, OAuth, etc.
Find similar memories
[CODE BLOCK]
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 —  generates embeddings for memories missing them
- Async updates — when content is updated, embedding is regenerated
Embedding providers
Synapse supports configurable embedding providers:
- OpenAI (, )
- Local models (via Ollama or similar)
- Custom (implement the embeddings interface)
Configure via environment variables:
[CODE BLOCK]
Batch generation
For minds with many memories missing embeddings:
[CODE BLOCK]
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
 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:
-  returns 503 Service Unavailable
-  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 — 
> - Monitor provider health — semantic search depends on it
> - Combine with tags — semantic + tag filter narrows results
Next Steps
- FTS5 Search
- Memory API
- Architecture