semantic_search
Find cached entries semantically similar to a natural-language query. Returns results with similarity scores from pgvector HNSW index.
Instructions
Find cached entries that are semantically similar to a natural-language query. Read-only — no side effects. Returns an array of objects, each with: key, value, similarity_score (0–1), and namespace. Returns an empty array if no entries meet the similarity threshold. Requires OPENAI_API_KEY (or compatible provider) and the Speed/Business tier with CACHLY_VECTOR_URL. Embeddings are computed server-side and never leave Germany (pgvector HNSW index). Example: "find all cached responses about password reset" or "what did we answer about pricing?". Use cache_get for exact key lookup; use smart_recall for brain lessons.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance_id | Yes | UUID of the cache instance (from list_instances) | |
| query | Yes | Natural-language query to find similar cached content | |
| threshold | No | Minimum cosine similarity 0–1 (default: 0.82). Lower = broader matches. | |
| namespace | No | Semantic namespace to search in (default: cachly:sem) | |
| top_k | No | Maximum number of results to return (default: 5) | |
| use_hybrid | No | Enable Hybrid BM25+Vector RRF fusion search. Passes `hybrid: true` and the query text to the pgvector API for higher precision on named entities. Default: false. | |
| auto_namespace | No | Auto-detect the namespace from the query text using text heuristics instead of using the `namespace` parameter. Returns results only from the matching domain (code/translation/summary/qa/creative). |