semantic_search
Find notes by meaning, not exact words. Uses vector embeddings to match conceptual or paraphrased queries, returning deduped notes with previews and staleness indicators.
Instructions
Vector similarity search over the vault's chunk embeddings. Use this for conceptual or paraphrased queries — anywhere exact word matching would miss the point.
For exact identifiers, code symbols, proper nouns, or known phrases, use keyword_search instead.
Each result is one note (deduped) with its best-matching chunk as a ~200-character preview.
Call read_note on a result's path to get the full note content.
The header line carries a stale count and a truncated count, always — including when both are zero, so "nothing here is degraded" is distinguishable from a build that does not report it.
stale: true on a row means the note changed after it was embedded: it was
matched and ranked against its previous content, and its preview is
withheld rather than shown, because that excerpt is text the note no
longer has. Its path, title and tags are current — the indexer refreshed
them, which is how the staleness is known at all — so read_note on that
path returns the true content and is the remedy. Stale notes are never
filtered out: during an embedding outage that would empty the result set
rather than degrade it.
embedding_truncated: true means the note is longer than the indexer's
per-note chunk cap and only its head was embedded. A match against such a
note is a match against its head; its tail is not reachable by semantic
search at all, though keyword_search still covers the whole note.
The bound on the staleness signal, stated so it is not over-read: it reports what the index has committed. An edit that the indexer has not yet scanned is not marked, so a note edited in the last few minutes may come back unmarked with a superseded preview. The guarantee is "no result presents text the index knows to be superseded", not "no result is ever out of date".
Args: query: Natural language description of what you're looking for. limit: Maximum number of distinct notes to return (default 15). folder: Optional folder prefix (e.g. "Projects/"). tags: Optional list of tag names; only notes carrying ALL listed tags match (e.g. ["product"]). frontmatter: Optional dict of frontmatter key/value pairs; strict type matching — string "0" does not match integer 0 (e.g. {"status": "active"}).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| limit | No | ||
| query | Yes | ||
| folder | No | ||
| frontmatter | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |