distillery_search
Find knowledge entries by semantic similarity to a natural-language query, returning ranked results with relevance scores. Filter by type, author, tags, status, or dates; optionally expand via related-entry graph hops.
Instructions
Search knowledge entries using semantic similarity (cosine distance, ranked descending).
USE WHEN: finding entries that match a natural-language question or topic. Each result includes a similarity score (0-1, higher is more relevant).
By default, only entries with status in (active, pending_review) are
considered — archived entries are hidden. Pass status="archived"
to search only archived entries, status="any" to include every
status, or include_archived=true to add archived entries to the
default candidate set.
When expand_graph=true, after the semantic search returns its
seed result set, the tool BFS-expands 1 or 2 hops via
entry_relations to surface structurally connected entries.
Graph entries are scored at parent_score * 0.5 ** depth, marked
with provenance="graph", and merged into the result list (sorted
by descending score, truncated to limit). Seeds are tagged
provenance="search". The envelope gains a graph_expansion
summary. When expand_graph=false (default), the existing
envelope is unchanged — strictly additive.
PARAMS:
query (str, required): Natural-language search query.
entry_type (str | list[str], optional): Filter by type, or a list of types matched with OR (e.g. ["session", "reference"]).
author (str, optional): Filter by author.
project (str, optional): Filter by project scope.
tags (list[str], optional): Filter by tags (AND match).
status (str, optional): Filter by status.
source (str, optional): Filter by origin.
session_id (str, optional): Filter by session identifier.
date_from (str, optional): ISO 8601 lower bound.
date_to (str, optional): ISO 8601 upper bound.
limit (int, optional, default=10): Max results (1-200).
tag_prefix (str, optional): Filter tags by namespace prefix.
include_archived (bool, optional, default=False): Include archived entries in the candidate set.
published_after (str, optional): ISO 8601 inclusive lower bound on metadata.published_at (poller-recorded publication timestamp). Used by /radar to bound the candidate set by the configured digest window.
published_before (str, optional): ISO 8601 inclusive upper bound on metadata.published_at.
include_evergreen (bool, optional, default=False): When False (default) and published_after/published_before is set, also drops entries flagged metadata.backfill=true so first-poll backfill items don't surface as "new intelligence". Set to True to surface older / evergreen items explicitly. See issue #444.
expand_graph (bool, optional, default=False): When true, expand the seed result set via
entry_relationsand merge the neighbours into the results.expand_hops (int, optional, default=1): Depth of graph expansion when
expand_graph=true. Must be 1 or 2.output_mode (str, optional, default="summary"): Response shape. Valid: [summary, full, ids]. "summary" returns score plus a compact entry (id/title/~200-char content_preview, no full body — default, keeps responses small to conserve context). "full" returns score plus the entire entry (pre-output_mode behaviour). "ids" returns score + id only.
RETURNS (success): { results: [{ score: float, ... }], count: int }.
Result shape follows output_mode: "summary" (default) nests a compact
entry (no full content); "full" nests the complete entry; "ids"
returns score + id only.
When expand_graph=true each result also has provenance ("search" or
"graph"); graph results additionally carry depth and parent_id, and
the envelope includes graph_expansion: { seed_count, expanded_count }.
RETURNS (error): { error: true, code: "INVALID_PARAMS" | "BUDGET_EXCEEDED" | "INTERNAL", message: "..." }
RELATED: distillery_list (for filter-based browsing without semantic ranking), distillery_find_similar (to compare against arbitrary text)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| limit | No | ||
| query | Yes | ||
| author | No | ||
| source | No | ||
| status | No | ||
| date_to | No | ||
| project | No | ||
| date_from | No | ||
| entry_type | No | ||
| session_id | No | ||
| tag_prefix | No | ||
| expand_hops | No | ||
| output_mode | No | summary | |
| expand_graph | No | ||
| published_after | No | ||
| include_archived | No | ||
| published_before | No | ||
| include_evergreen | No |