semantic-search — L1 vector retrieval

Framework context

L1 skill: pure function of L0 given a fixed embedding model. Same query + same corpus + same model → identical results, always. No LLM judgment. The returned message IDs are themselves the citations — no synthesis is performed.

This is the retrieval layer that feeds all L2 synthesis skills. When tunnel_state or what_do_i_think is called with a topic, it calls semantic-search first.

When to invoke

• User's phrasing is conceptual ("what do I think about X") rather than verbatim
• Starting any new topic — check if they've thought about this before
• Before any L2 synthesis to seed the candidate set
• When keyword search (search-conversations) returns zero results but the topic probably was discussed

Input

query: str          # natural language query
limit: int = 10     # number of results to return

Output contract

Markdown list of the top N results, each carrying structural citations:

### [N] {conversation_title}
**Similarity**: 0.XXXX
**Source**: {source} · **Date**: YYYY-MM-DD · **conv_id**: {id}

> {400-char preview}

Each result IS a citation. No synthesis. No interpretation. No merging.

Does NOT do

• Summarize the results (that's L2 what_do_i_think)
• Deduplicate semantically similar results (that's L3 dormant_contexts)
• Filter by domain without explicit request (that's L2 tunnel_state)
• Rewrite the query for the user — if query is bad, empty result is honest

Execution

Internally wraps brain_mcp.server.tools_search.semantic_search(query, limit). Embedding generated via get_embedding(f"search_query: {query}"), searched against LanceDB message table, ranked by 1/(1+distance).

Verification checklist

• [ ] Similarity score is present on every result
• [ ] conv_id is present on every result (future L2 will cite it)
• [ ] If embedding model unavailable, output explicit "embedding unavailable" message — do not silently fall back to keyword
• [ ] Result order is distance-sorted ascending (similarity descending)
• [ ] Re-running with identical query returns identical result order