{"title":"Semantic Search (Embeddings)","slug":"semantic-search","category":"concepts","summary":"Conceptual memory search using vector embeddings — find by meaning, not just keywords.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":513,"read_minutes":3,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Semantic Search (Embeddings)\n\nSynapse supports semantic search using vector embeddings. Unlike FTS5 (keyword\nmatching), semantic search finds memories by **meaning** — even if no keywords\nmatch.\n\n## How It Works\n\n```\n1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned\n```\n\n### What are embeddings?\n\nEmbeddings are numerical vector representations of text. Text with similar\nmeaning has similar vectors. Synapse generates a vector (e.g. 1536 dimensions)\nfor each memory's content.\n\n### Cosine similarity\n\nTo find semantically similar memories, Synapse computes the cosine similarity\nbetween the query vector and each memory vector. Higher similarity = more\nrelevant.\n\n## When to Use Semantic Search\n\n### Use semantic search when:\n\n- You want \"memories about X\" where X is described differently than stored\n- FTS5 returns no results (no keyword match)\n- You want conceptual grouping (e.g. all \"deployment\" memories, even if some say \"release\")\n- Query is a question: \"how do we handle authentication?\"\n\n### Use FTS5 when:\n\n- You know exact keywords\n- You need boolean logic (AND, OR, NOT)\n- You need sub-millisecond response\n- You want phrase matching\n\n## Endpoint\n\n### GET /memory/semantic-search\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nResponse:\n\n```json\n{\n \"results\": [\n {\n \"id\": \"mem_001\",\n \"category\": \"project\",\n \"key\": \"project_synapse_deployment\",\n \"content\": \"Synapse deployed using Docker Swarm on vps1...\",\n \"tags\": [\"docker\", \"swarm\", \"deployment\"],\n \"similarity\": 0.89\n },\n {\n \"id\": \"mem_042\",\n \"category\": \"fact\",\n \"key\": \"kubernetes_cluster\",\n \"content\": \"We use Kubernetes for production orchestration...\",\n \"tags\": [\"kubernetes\", \"orchestration\"],\n \"similarity\": 0.84\n }\n ]\n}\n```\n\n## Examples\n\n### Find deployment memories\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nReturns memories about \"deployment\", \"release\", \"publishing\", \"rolling out\",\netc.\n\n### Find authentication patterns\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nReturns memories about login, auth, JWT, session management, OAuth, etc.\n\n### Find similar memories\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nUses semantic similarity (via shared tags AND embedding vectors).\n\n## Embedding Generation\n\n### When are embeddings generated?\n\n- **On memory store** — if embeddings service is configured, embedding is generated synchronously\n- **Batch generation** — `POST /memory/embed-batch` generates embeddings for memories missing them\n- **Async updates** — when content is updated, embedding is regenerated\n\n### Embedding providers\n\nSynapse supports configurable embedding providers:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Local models** (via Ollama or similar)\n- **Custom** (implement the embeddings interface)\n\nConfigure via environment variables:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Batch generation\n\nFor minds with many memories missing embeddings:\n\n```bash\n# Generate embeddings for up to 100 memories\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n\n# Check progress\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Performance\n\n| Operation | Latency |\n|-----------|---------|\n| Generate embedding (OpenAI) | 100-200ms |\n| Semantic search (1k memories) | 50-100ms |\n| Semantic search (10k memories) | 200-500ms |\n| Batch generation (100 memories) | 10-20s |\n\n> [!NOTE]\n> Semantic search is slower than FTS5 due to vector computation. Use FTS5\n> for known keywords, semantic for conceptual queries.\n\n## Limitations\n\n### Embeddings cost\n\nIf using OpenAI, generating embeddings costs money (~$0.02 per 1M tokens\nfor text-embedding-3-small). For 10,000 memories averaging 100 tokens each,\nthat's ~$0.02 — negligible.\n\n### Cold start\n\nMemories stored before embeddings were configured won't have embeddings. Run\n`POST /memory/embed-batch` to backfill.\n\n### Provider dependency\n\nIf the embeddings provider is down, semantic search fails gracefully (returns\nempty results or error). FTS5 still works.\n\n## When Embeddings Aren't Available\n\nIf embeddings service is not configured:\n\n- `GET /memory/semantic-search` returns 503 Service Unavailable\n- `POST /memory` still works (just no embedding generated)\n- FTS5 search still works\n\n## Best Practices\n\n> [!TIP]\n> - **Use semantic for conceptual queries** — \"how do we handle X?\"\n> - **Use FTS5 for specific terms** — \"docker swarm\"\n> - **Backfill embeddings regularly** — `POST /memory/embed-batch`\n> - **Monitor provider health** — semantic search depends on it\n> - **Combine with tags** — semantic + tag filter narrows results\n\n## Next Steps\n\n- [FTS5 Search](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Architecture](/docs/concepts/architecture)\n","content_html":"

Semantic Search (Embeddings)

\n

Synapse supports semantic search using vector embeddings. Unlike FTS5 (keyword\nmatching), semantic search finds memories by meaning — even if no keywords\nmatch.

\n

How It Works

\n
1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned

What are embeddings?

\n

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

\n

Cosine similarity

\n

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

\n

When to Use Semantic Search

\n

Use semantic search when:

\n\n

Use FTS5 when:

\n\n

Endpoint

\n

GET /memory/semantic-search

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

Response:

\n
{\n  "results": [\n    {\n      "id": "mem_001",\n      "category": "project",\n      "key": "project_synapse_deployment",\n      "content": "Synapse deployed using Docker Swarm on vps1...",\n      "tags": ["docker", "swarm", "deployment"],\n      "similarity": 0.89\n    },\n    {\n      "id": "mem_042",\n      "category": "fact",\n      "key": "kubernetes_cluster",\n      "content": "We use Kubernetes for production orchestration...",\n      "tags": ["kubernetes", "orchestration"],\n      "similarity": 0.84\n    }\n  ]\n}

Examples

\n

Find deployment memories

\n
# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process

Returns memories about "deployment", "release", "publishing", "rolling out",\netc.

\n

Find authentication patterns

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

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

\n

Find similar memories

\n
# Find memories similar to a specific one\ncurl .../memory/related/mem_001

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

\n

Embedding Generation

\n

When are embeddings generated?

\n\n

Embedding providers

\n

Synapse supports configurable embedding providers:

\n\n

Configure via environment variables:

\n
EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small

Batch generation

\n

For minds with many memories missing embeddings:

\n
# Generate embeddings for up to 100 memories\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'\n\n# Check progress\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

Performance

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperationLatency
Generate embedding (OpenAI)100-200ms
Semantic search (1k memories)50-100ms
Semantic search (10k memories)200-500ms
Batch generation (100 memories)10-20s
\n
Semantic search is slower than FTS5 due to vector computation. Use FTS5\nfor known keywords, semantic for conceptual queries.

Limitations

\n

Embeddings cost

\n

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

\n

Cold start

\n

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

\n

Provider dependency

\n

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

\n

When Embeddings Aren't Available

\n

If embeddings service is not configured:

\n\n

Best Practices

\n

Next Steps

\n\n","urls":{"html":"/docs/concepts/semantic-search","text":"/docs/concepts/semantic-search?format=text","json":"/docs/concepts/semantic-search?format=json","llm":"/docs/concepts/semantic-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}