| name | semantic-search |
| description | Deterministic vector retrieval over embedded messages. Finds conversations by meaning, not keyword. Use when the user's phrasing may not match what they wrote at the time. |
| layer | L1 |
| reads | ["L0.all_conversations","L1.embeddings"] |
| writes | [] |
| citations | output-is-citation |
| determinism | pure-function |
| allowed-tools | mcp__my-brain__semantic_search |
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
