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

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

Response:

{
  "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

# 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

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

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

Find similar memories

# 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:

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

Batch generation

For minds with many memories missing embeddings:

# 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

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

Next Steps

• FTS5 Search
• Memory API
• Architecture