semantic_search
Find cached entries that match the meaning of a natural-language query instead of exact keywords. Submit a question or topic to retrieve semantically similar content with a similarity score.
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"instance_id": "<instance_id>",
"query": "<query>"
},
"name": "semantic_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language query to find similar cached content | |
| top_k | No | Maximum number of results to return (default: 5) | |
| namespace | No | Semantic namespace to search in (default: cachly:sem) | |
| threshold | No | Minimum cosine similarity 0–1 (default: 0.82). Lower = broader matches. | |
| 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. | |
| instance_id | Yes | UUID of the cache instance (from list_instances) | |
| 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). |