Semantic Search
Relevant source files
The following files were used as context for generating this wiki page:
Semantic search in e-zer0 provides AI agents with the ability to locate emails and tasks based on intent and meaning rather than exact keyword matches. The system leverages vector embeddings to represent text numerically, allowing for queries such as "find emails about cheap flights" to return relevant results even if the specific phrase "cheap flights" is absent.
Sources: README.md:27-28, AGENTS.md:20
Architecture and Components
The semantic search system operates on the Cloudflare Developer Platform, integrating compute, artificial intelligence, and specialized database services.
- Compute: Cloudflare Workers (TypeScript) handle the logic for indexing and searching.
- Vector Database: Cloudflare Vectorize stores high-dimensional embeddings and performs similarity searches using cosine metric distance.
- Embedding Model: Cloudflare Workers AI runs the
bge-small-en-v1.5(orbge-base-en-v1.5) model to convert text into 384-dimensional vectors. - Sanitization: The system redacts PII and detects prompt injection before presenting results to agents.
Sources: AGENTS.md:17-21, wrangler.toml:21-30, scripts/setup-cf.js:126-130, src/lib/vector.test.ts:32
Component Summary Table
| Component | Technology | Role |
|---|---|---|
| Vector Index | Cloudflare Vectorize | Stores and queries document embeddings |
| Embedding Engine | Cloudflare Workers AI | Generates vectors from email text |
| Model | bge-small-en-v1.5 | The specific LLM used for vectorization (384 dims) |
| Sanitizer | Custom Regex/Logic | Redacts sensitive data and flags injections |
Sources: AGENTS.md:20, scripts/setup-cf.js:129, src/lib/sanitizer.ts:4-100, src/lib/vector.test.ts:32
Data Flow: Indexing and Search
The semantic search lifecycle consists of two primary phases: indexing (ingestion) and querying.
Indexing Flow
Indexing occurs automatically when an agent fetches emails via read_recent_emails or get_emails. The system processes messages in batches to optimize performance.
- Text Extraction: The system combines the email subject and a text snippet.
- Truncation: Input text is truncated to a maximum of 500 characters to meet model constraints.
- Embedding Generation: Workers AI generates a vector for the text.
- Upsert: The vector is stored in the
VECTOR_INDEXwith metadata includingaccount_idandmessage_id.
This diagram illustrates the background process of updating the vector database during standard email retrieval operations.
Sources: src/mcp/tools.ts:162-177, src/lib/vector.test.ts:12-30, src/lib/vector.test.ts:74-90
Search Flow
When an agent executes the search_emails_semantic tool, the system follows a secure retrieval path.
- Auth Check: The system verifies that the requesting MCP client has permissions for the specific
account_idto prevent cross-tenant data leakage. - Query Vectorization: The user's natural language query is converted into a vector.
- Vector Search: Vectorize finds the top-K matches filtered by the permitted
account_id. - Enrichment: The system fetches full message details (subject, body) from the email provider.
- Sanitization:
sanitizeEmailContentredacts PII and assigns a risk score for prompt injection.
This diagram shows the end-to-end execution of a semantic search request, emphasizing the security and sanitization layers.
Sources: src/mcp/tools.ts:303-348, src/mcp/server.ts:601-630, src/lib/sanitizer.ts:210-250
Security and Privacy
Semantic search includes several safeguards to protect sensitive information:
- Account Isolation: The system applies a metadata filter (
account_id) to every vector query. This ensures that even if an agent queries the global index, it only receives results from mailboxes it is explicitly authorized to access. - PII Redaction: Before search results are returned, the
Sanitizerscans the content for patterns such as credit card numbers, national IDs, passwords, and API keys. - Prompt Injection Detection: The system evaluates search results for malicious instructions (e.g., "ignore previous instructions") and prepends a safety warning if the risk score exceeds 50.
- Audit Logging: Every execution of
search_emails_semanticis logged in theaudit_logstable, recording the query string, the client identity, and the success status.
Sources: src/mcp/tools.ts:31-70, src/mcp/tools.ts:303-311, src/lib/sanitizer.ts:245-249, src/mcp/server.ts:607-628
Technical Constraints
Developers must account for the following limitations when working with the semantic search module:
- Batch Size: Vector indexing is capped at 20 emails per batch to manage subrequest limits.
- Text Length: Embedding generation only considers the first 500 characters of the provided text.
- Best-Effort Indexing: Vector indexing is treated as a best-effort operation; failures during indexing do not cause the primary email retrieval tool to fail.
- Deletion: When a message is deleted via
manage_email, the system attempts to remove the corresponding vector from the index using a composite ID.
Sources: src/lib/vector.test.ts:20-25, src/lib/vector.test.ts:114-118, src/mcp/tools.ts:176, src/mcp/tools.ts:289-295