Skip to main content

​
Semantic Search

Semantic search finds sessions based on meaning rather than exact keywords. It uses vector embeddings to match your query against session content, returning results that are conceptually similar even when they use different words.

​
How it works

  1. When a session is synced, OpenSync generates a 1536-dimension vector embedding from the session’s searchable text using OpenAI’s text-embedding-3-small model.
  2. The embedding is stored in the sessionEmbeddings table alongside a text hash for change detection.
  3. When you search, your query is also converted to an embedding using the same model.
  4. Convex’s vector search compares the query embedding against all stored embeddings using cosine similarity.
  5. Results are ranked by similarity score (0.0 to 1.0, where 1.0 is identical).

​
Embedding model

The cost is negligible. A typical session produces 2K-10K tokens of searchable text. At $0.02 per million tokens, embedding 1000 sessions costs less than a penny.

​
What gets embedded

Session embeddings are generated from sessions.searchableText, which concatenates:
  • Session title
  • All user message text
  • All assistant message text
Tool call names and results are not included in the embedding. Only human-readable text is vectorized.

​
Embedding storage

Each embedding is stored with these fields: The textHash field enables idempotency. If a session is re-synced with the same text content, the embedding is not regenerated.

​
Message-level embeddings

In addition to session-level embeddings, OpenSync generates embeddings for individual messages. These are stored in the messageEmbeddings table and enable finer-grained search within specific conversations.

​
Examples

​
Natural language question

Returns sessions discussing CORS configuration, HTTP endpoint setup, and related error handling, even if they never use the exact phrase “CORS errors.”
Returns sessions about schema changes, data backfilling, and migration strategies across different tools and frameworks.
Returns sessions about performance optimization, memoization, and state management, even if the conversations used terms like “useCallback” or “useMemo” rather than “re-renders.”

​
Requirements

Semantic search requires an OpenAI API key:
  • Hosted version: Already configured. No action needed.
  • Self-hosted: Set the OPENAI_API_KEY environment variable on your Convex deployment.
Without an OpenAI key, semantic search is disabled and sessions will not have embeddings generated.

​
Using in the dashboard

  1. Go to the Context tab in the sidebar.
  2. Select Semantic as the search type.
  3. Type a natural language query.
  4. Results appear ranked by similarity score.
Each result shows the session title, a content snippet, and the similarity score (higher is better).

​
Using via API

Response:

​
Tips

  • Ask questions naturally. Semantic search works best with complete questions or descriptions, not individual keywords.
  • Be specific about the domain. “How to handle auth in a Next.js app” performs better than “auth.”
  • Embedding latency. Newly synced sessions may take a few seconds to appear in semantic search results while embeddings are generated asynchronously.
  • Score threshold. Results with scores below 0.5 are typically not relevant. The dashboard hides very low-scoring results automatically.

​
Comparison with full-text

For combining both approaches, see Hybrid Search.