diff --git a/packages/plugin/src/shared/prompt-surface-a1-golden.md b/packages/plugin/src/shared/prompt-surface-a1-golden.md index bceace2ad..f6e05e8d6 100644 --- a/packages/plugin/src/shared/prompt-surface-a1-golden.md +++ b/packages/plugin/src/shared/prompt-surface-a1-golden.md @@ -400,6 +400,8 @@ Example: ctx_memory(action="write", category="CONSTRAINTS", content="Pi stores s ``` Your long-term recall for this project — search everything that ever happened here, not just what's currently visible. +Retrieval is HYBRID when embeddings are enabled: ~0.7 semantic (embedding cosine) + ~0.3 keyword (FTS5 BM25), fused with per-source boosts; with embeddings disabled it silently falls back to keyword-only matching. Phrase `query` as a natural-language QUESTION that still embeds the key literal terms (paths, symbols, commands, config keys) — pure keyword stacks starve the semantic leg (0.7 weight), while pure prose without literal terms may miss exact FTS matches. Good: "Where is the dream log file and which error counters indicate failures?" Bad: "dream log error counter". + Reach for it when something feels familiar but isn't in view: "did we solve this before?", "what did we decide about X?", "when did this break?", "where does Y live?". Results only contain things you CANNOT currently see — memories already shown in and the live conversation tail are filtered out. A query that is just one or more memory ids (e.g. `#7234` or `12, 34`) bypasses text search and resolves those ids directly. Sources (omit for a broad search across all): diff --git a/packages/plugin/src/tools/ctx-search/constants.ts b/packages/plugin/src/tools/ctx-search/constants.ts index 0bfbf0dc8..e589bc713 100644 --- a/packages/plugin/src/tools/ctx-search/constants.ts +++ b/packages/plugin/src/tools/ctx-search/constants.ts @@ -1,6 +1,8 @@ export const CTX_SEARCH_TOOL_NAME = "ctx_search"; export const CTX_SEARCH_DESCRIPTION = `Your long-term recall for this project — search everything that ever happened here, not just what's currently visible. +Retrieval is HYBRID when embeddings are enabled: ~0.7 semantic (embedding cosine) + ~0.3 keyword (FTS5 BM25), fused with per-source boosts; with embeddings disabled it silently falls back to keyword-only matching. Phrase \`query\` as a natural-language QUESTION that still embeds the key literal terms (paths, symbols, commands, config keys) — pure keyword stacks starve the semantic leg (0.7 weight), while pure prose without literal terms may miss exact FTS matches. Good: "Where is the dream log file and which error counters indicate failures?" Bad: "dream log error counter". + Reach for it when something feels familiar but isn't in view: "did we solve this before?", "what did we decide about X?", "when did this break?", "where does Y live?". Results only contain things you CANNOT currently see — memories already shown in and the live conversation tail are filtered out. A query that is just one or more memory ids (e.g. \`#7234\` or \`12, 34\`) bypasses text search and resolves those ids directly. Sources (omit for a broad search across all):