Distillery

Sync GitHub issues and PRs into the knowledge base using a batched pipeline. url: repository slug (owner/repo) or full GitHub URL. author: author field for created entries (default: gh-sync). project: optional project name to scope entries. background: when true, runs async and returns a job_id immediately.

Check the status of background sync jobs. job_id: look up a specific job by ID. source_url: list jobs for a specific source URL. If neither is provided, lists all recent jobs.

Store a new knowledge entry and return its ID with dedup/conflict information. USE WHEN: capturing a new piece of knowledge (session notes, bookmarks, meeting minutes, ideas, etc.) into the Distillery store. PARAMS: - content (str, required): The knowledge content to store. - entry_type (str, required): Entry classification. Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. - author (str, required): Who authored this entry. - project (str, optional): Project scope for the entry. - tags (list[str], optional): Tags for categorisation; supports namespaced tags (e.g. "topic/ai"). - metadata (dict, optional): Arbitrary key-value metadata. Some entry types REQUIRE specific metadata keys (TYPE_METADATA_SCHEMAS); omitting them returns INVALID_PARAMS naming the missing/invalid field: - person: expertise (list[str]) - project: repo (str) - digest: period_start, period_end (str) - github: repo, ref_type, ref_number; ref_type in [issue, pr, discussion, release] - feed: source_url, source_type; source_type in [rss, github] Other types (session, bookmark, minutes, meeting, reference, idea, inbox) accept arbitrary metadata. - source (str, optional, default="claude-code"): Origin of the entry. Valid: [claude-code, manual, import, inference, documentation, external]. - session_id (str, optional): Opaque session identifier for grouping related entries. - dedup_threshold (float, optional, default=config): Cosine similarity threshold (0-1) for near-duplicate warnings. - dedup_limit (int, optional, default=config): Max duplicates to report. - verification (str, optional, default="unverified"): Verification status. Valid: [unverified, testing, verified]. - expires_at (str, optional): ISO 8601 datetime; entries past expiry appear in stale results. - output_mode (str, optional, default="full"): Response verbosity. Valid: [full, summary]. Use "summary" for bulk imports to skip dedup/conflict checks. - include_conflict_prompt (bool, optional, default=False): When true, each conflict candidate carries the ~1–2 KB ``conflict_prompt`` LLM template required to round-trip through ``distillery_find_similar(conflict_check=true)``. Defaults to false to keep store responses small (issue #348). RETURNS (success): { entry_id: str, persisted: bool, dedup_action: str, conflicts?: list[{entry_id, content_preview, similarity_score, conflict_prompt?}], warnings?: list } RETURNS (error): { error: true, code: "INVALID_PARAMS" | "BUDGET_EXCEEDED" | "INTERNAL", message: "..." } RELATED: distillery_find_similar (for pre-store dedup checks), distillery_correct (to supersede an existing entry)

Batch-store multiple knowledge entries in one call (no dedup/conflict checks). USE WHEN: bulk-importing entries (e.g. GitHub history sync, migration, backfill) where per-entry dedup is unnecessary and throughput matters. PARAMS: - entries (list[dict], required): List of entry dicts. Each must have: - content (str, required): The knowledge content. - author (str, required): Who authored this entry. - entry_type (str, optional, default="inbox"): Entry classification. Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. - tags (list[str], optional): Tags for categorisation. - metadata (dict, optional): Arbitrary key-value metadata. - source (str, optional, default="claude-code"): Origin of the entry. - project (str, optional): Per-entry project override. - project (str, optional): Default project applied to entries lacking one. RETURNS (success): { entry_ids: list[str | None], # per-item ids; null for failed items count: int, # number actually persisted results: list[dict], # per-item status preserving input order } - Successful items: { entry_id, persisted: true, dedup_action: "stored" } - Failed items: { entry_id: null, persisted: false, error: { code, message, details? } } Validation failures on individual items no longer abort the batch — valid entries are persisted and failures are reported per item in ``results`` (issue #364). Iterate ``results`` to discover failures. RETURNS (error): { error: true, code: "INVALID_PARAMS" | "BUDGET_EXCEEDED" | "INTERNAL", message: "..." } Top-level error is returned only for schema-level problems (``entries`` not a list, budget exhaustion, persistence failure). RELATED: distillery_store (single entry with dedup/conflict checks), distillery_watch (add feed sources with optional history sync)

Ingest an arbitrary document (ADR, spec, decision, customer feedback). USE WHEN: importing a standalone document — a markdown ADR/spec/RFC, a design decision, or a customer-feedback transcript/doc — so it becomes queryable knowledge with provenance. Distinct from distillery_store (single entry, semantic dedup) and from PreCompact transcripts: this chunks large text into multiple linked entries and deduplicates idempotently by content hash, so re-ingesting identical content adds no second entry. PARAMS: - text (str, required): The full document text. Large text is split into multiple linked entries (relation_type="chunk"). - author (str, required): Who is ingesting / owns this document. - doctype (str, optional, default="doc"): Document kind. Valid: [adr, spec, decision, feedback, doc]. Applied as both a "doctype/<value>" tag and metadata.doctype for faceted retrieval. - source (str, optional): Provenance label (file path, Drive URL, etc.). Stored in metadata.source. - external_id (str, optional): Explicit dedup key. Defaults to the SHA-256 hash of text, making re-ingest idempotent. - title (str, optional): Human-readable title (stored in metadata.title). - project (str, optional): Project scope. - tags (list[str], optional): Extra namespaced tags. - metadata (dict, optional): Arbitrary extra metadata. RETURNS (success): { entry_ids: list[str], count: int, doctype: str, external_id: str, chunked: bool, persisted: bool, dedup_action: "stored" | "skipped" } On re-ingest of identical content, persisted=false, dedup_action="skipped", and entry_ids points at the existing entries. RETURNS (error): { error: true, code: "INVALID_PARAMS" | "INTERNAL", message: "..." } RELATED: distillery_store (single entry with semantic dedup), distillery_search (to retrieve ingested documents)

Retrieve a single knowledge entry by its unique ID. USE WHEN: fetching the full content and metadata of a specific entry (e.g. after finding its ID via search or list). PARAMS: - entry_id (str, required): UUID of the entry to retrieve. RETURNS (success): { id: str, content: str, entry_type: str, ... } RETURNS (error): { error: true, code: "NOT_FOUND" | "INTERNAL", message: "..." } RELATED: distillery_search (to find entries by content), distillery_list (to browse entries by filters)

Update one or more fields on an existing knowledge entry. USE WHEN: modifying an entry's content, type, tags, status, or other mutable fields. At least one updatable field must be provided. PARAMS: - entry_id (str, required): UUID of the entry to update. - content (str, optional): Replacement content. - entry_type (str, optional): New type. Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. - author (str, optional): New author. - project (str, optional): New project scope. - tags (list[str], optional): Replacement tag list. - status (str, optional): New status. Valid: [active, pending_review, archived]. - verification (str, optional): New verification. Valid: [unverified, testing, verified]. - metadata (dict, optional): Replacement metadata dict. - session_id (str, optional): Session identifier for grouping. - expires_at (str, optional): ISO 8601 datetime; pass null to clear. RETURNS (success): { id: str, content: str, entry_type: str, ... } (full updated entry) RETURNS (error): { error: true, code: "NOT_FOUND" | "INVALID_PARAMS" | "FORBIDDEN" | "INTERNAL", message: "..." } RELATED: distillery_correct (to supersede rather than edit), distillery_get (to read before updating)

Store a correction that supersedes an existing entry. USE WHEN: an existing entry contains wrong information and you want to replace it with corrected content while preserving the audit trail. PARAMS: - wrong_entry_id (str, required): UUID of the entry being corrected. - content (str, required): The corrected content. - entry_type (str, optional): Override type; inherited from original if omitted. Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. - author (str, optional): Override author; inherited from original if omitted. - project (str, optional): Override project; inherited from original if omitted. - tags (list[str], optional): Override tags; inherited from original if omitted. - metadata (dict, optional): Additional metadata for the correction entry. RETURNS (success): { correction_entry_id: str, archived_entry_id: str } RETURNS (error): { error: true, code: "NOT_FOUND" | "INVALID_PARAMS" | "FORBIDDEN" | "INTERNAL", message: "..." } RELATED: distillery_update (for non-breaking edits), distillery_relations (to view the 'corrects' relation)

List knowledge entries with optional filters and pagination (newest first). USE WHEN: browsing or filtering entries without a semantic query. Use distillery_search instead when you have a natural-language question. By default, only entries with status in (active, pending_review) are returned — archived entries are hidden. Pass ``status="archived"`` to list only archived entries, ``status="any"`` to include every status, or ``include_archived=true`` to add archived entries to the default view. PARAMS: - entry_type (str | list[str], optional): Filter by type, or a list of types matched with OR (e.g. ["session", "reference"]) — pair with group_by to aggregate across several types in one call. Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. - 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. Valid: [active, pending_review, archived, any]. Default hides archived; use "any" to include all. - verification (str, optional): Filter by verification. Valid: [unverified, testing, verified]. - source (str, optional): Filter by origin. Valid: [claude-code, manual, import, inference, documentation, external]. As a convenience, a URL-shaped value (starting with "http://" or "https://") is aliased to ``feed_url`` so ``source="https://hnrss.org/frontpage"`` matches feed items ingested from that source (same semantics as passing ``feed_url=...``). - session_id (str, optional): Filter by session identifier. - date_from (str, optional): ISO 8601 lower bound on created_at. - date_to (str, optional): ISO 8601 upper bound on created_at. - limit (int, optional, default=20): Max entries to return (1-500). - offset (int, optional, default=0): Pagination offset. - tag_prefix (str, optional): Filter tags by namespace prefix. - output_mode (str, optional, default="summary"): Response shape. Valid: [full, summary, ids, review]. "summary" returns id/title/tags/project/ author/created_at plus a ~200-char content_preview (default — keeps responses small to conserve context). "full" returns entire content body. "ids" returns id/entry_type/created_at only. "review" filters to pending_review and enriches with confidence/classification_reasoning. - content_max_length (int, optional): Truncate content to N chars (full mode only). - stale_days (int, optional): Restrict to entries not accessed in N days (>= 1). - group_by (str, optional): Return grouped counts instead of entries. Valid: [entry_type, status, author, project, source, tags]. Mutually exclusive with output="stats". - output (str, optional): Set to "stats" for aggregate statistics. Mutually exclusive with group_by. - feed_url (str, optional): Filter to entries ingested from a registered feed source URL (matches metadata.source_url written by the poller). Use this to retrieve all items polled from e.g. "https://hnrss.org/frontpage". - include_archived (bool, optional, default=False): Include archived entries in the default view (same effect as status="any" when status is unset). - published_after (str, optional): ISO 8601 inclusive lower bound on metadata.published_at (the feed-item publication timestamp written by the poller). Use this to bound the /radar candidate set by the 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. - structural (list[str], optional): Surface entries with specific graph anomalies relative to ``entry_relations``. Accepted values: ["orphans"] — entries that do not appear as either endpoint of any relation row. Unknown values yield INVALID_PARAMS. Combines (AND) with every other filter (project, tags, status, date range, stale_days, etc.) — orphans are first restricted by those filters, then the no-relations predicate is applied. RETURNS (success): { entries: list, count: int, total_count: int, limit: int, offset: int, output_mode: str } — when ``structural`` is set, the payload additionally includes ``structural_filter`` (comma-joined applied filters, e.g. "orphans"). Existing fields are unchanged. RETURNS (error): { error: true, code: "INVALID_PARAMS" | "INTERNAL", message: "..." } RELATED: distillery_search (for semantic search), distillery_status (for lightweight server health/metadata)

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_relations`` and 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)

Find stored entries similar to the given text (cosine similarity). USE WHEN: checking for duplicates or conflicts before storing, finding entries related to arbitrary text, or surfacing hidden connections to a known entry (entries that are similar but not yet linked via relations). Supports progressive disclosure modes. PARAMS: - content (str, optional): Text to compare against stored entries. Required unless source_entry_id is provided. When both are set, content wins as the similarity probe. - threshold (float, optional, default=0.8): Cosine similarity cutoff (0-1). - limit (int, optional, default=10): Max results (1-200). - dedup_action (bool, optional, default=false): When true, includes dedup check with recommended action (create/skip/merge/link). - conflict_check (bool, optional, default=false): When true, includes conflict candidates with LLM evaluation prompts. - llm_responses (list[dict], optional): With conflict_check=true, evaluates LLM conflict verdicts. Each item: { entry_id: str, is_conflict: bool, reasoning: str }. - source_entry_id (str, optional): Anchor entry whose content is used as the similarity probe when content is omitted, and whose id is self-excluded from results. Required when exclude_linked=true. When set without content/dedup/conflict/accept_action, reuses the entry's STORED embedding (no re-embed, no embedding-budget spend). - source_entry_ids (list[str], optional): BATCH mode. Up to 50 seed ids. Reuses each seed's STORED embedding (no re-embed, no embedding-budget spend) and runs all similarity queries in ONE round-trip. Standalone — cannot be combined with content, source_entry_id, dedup_action, conflict_check, accept_action, or llm_responses (INVALID_PARAMS). Honours threshold, limit, and exclude_linked per seed; each seed always self-excludes. - exclude_linked (bool, optional, default=false): When true, filters out entries already linked to source_entry_id (or, in batch mode, to each seed) via entry_relations (any direction, any relation_type). Surfaces hidden connections. - accept_action (str, optional): When set, persists an entry_relations row from source_entry_id to each result above threshold. Valid: ['link' → related, 'merge' → merge_source, 'duplicate' → duplicate]. Requires source_entry_id. Idempotent via the unique (from_id, to_id, relation_type) index. RETURNS (success, single/content): { results: [{ score: float, entry: {...} }], count: int, threshold: float, dedup?: { action: str, similar_entries: list }, conflict_candidates?: list, conflict_evaluation?: dict, excluded_linked_count?: int } Note: excluded_linked_count is present whenever source_entry_id is set or exclude_linked=true. It counts both linked-source exclusions (when exclude_linked=true) and the self-exclusion of source_entry_id itself (when source_entry_id == candidate); a non-zero value is therefore possible even with exclude_linked=false. RETURNS (success, batch / source_entry_ids): { results_by_seed: { "<seed_id>": { results: [{ score: float, entry: {...} }], count: int, excluded_count: int } }, seed_count: int, threshold: float } A seed with no stored embedding maps to an empty results list (not an error). excluded_count is best-effort (reported as 0 in batch mode). RETURNS (error): { error: true, code: "INVALID_PARAMS" | "NOT_FOUND" | "BUDGET_EXCEEDED" | "INTERNAL", message: "..." } RELATED: distillery_store (stores with automatic dedup/conflict checks), distillery_search (for natural-language queries), distillery_relations (to inspect existing links between entries)

Apply a pre-computed classification to an existing entry. USE WHEN: you have determined an entry's type and confidence via LLM or heuristic analysis and want to persist the classification result. PARAMS: - entry_id (str, required): UUID of the entry to classify. - entry_type (str, required): Assigned type. Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. Common intuitive aliases like ``"note"`` are NOT accepted but the error response includes a ``details.suggestion`` pointing to the canonical type (e.g. ``"note"`` -> ``"inbox"``). - confidence (float, required): Classification confidence (0-1). Entries below the configured threshold (default 0.6) go to pending_review. - reasoning (str, optional): Explanation of the classification decision. - suggested_tags (list[str], optional): Tags to merge onto the entry. - suggested_project (str, optional): Project to assign if entry has none. RETURNS (success): { id: str, entry_type: str, status: str, ... } (full updated entry) RETURNS (error): { error: true, code: "NOT_FOUND" | "INVALID_PARAMS" | "INTERNAL", message: "...", details?: { field, provided, allowed, suggestion? } } RELATED: distillery_resolve_review (to act on pending_review entries), distillery_list (with output_mode="review" to see the review queue)

Resolve a pending-review entry by approving, reclassifying, or archiving it. USE WHEN: acting on entries in the review queue (entries with status=pending_review from low-confidence classifications). PARAMS: - entry_id (str, required): UUID of the pending-review entry. - action (str, required): Resolution action. Valid: [approve, reclassify, archive]. - new_entry_type (str, optional): Required when action="reclassify". Valid: [session, bookmark, minutes, meeting, reference, idea, inbox, github, person, project, digest, feed]. - reviewer (str, optional): Reviewer identity for audit metadata. RETURNS (success): { id: str, status: str, ... } (full updated entry). When the requested action is a no-op (e.g. approve on an already-active entry), the response also includes { already_in_state: true } and the entry is returned unchanged (version is NOT bumped, reviewed_at / archived_at are NOT rewritten). RETURNS (error): { error: true, code: "NOT_FOUND" | "INVALID_PARAMS" | "FORBIDDEN" | "INTERNAL", message: "..." } RELATED: distillery_classify (to classify entries), distillery_list (with output_mode="review" to see the queue)

Manage monitored feed sources for ambient intelligence. USE WHEN: listing, adding, or removing RSS/GitHub feed sources that Distillery polls for new content. PARAMS: - action (str, required): Operation to perform. Valid: [list, add, remove]. - url (str, required for add/remove): Feed URL or GitHub owner/repo slug. - source_type (str, required for add): Feed type. Valid: [rss, github]. - label (str, optional): Human-readable label for the source. - poll_interval_minutes (int, optional, default=60): Polling frequency in minutes. - trust_weight (float, optional, default=1.0): Source trust weight (0-1). - thresholds (object, optional): Per-source overrides for the global ``feeds.thresholds`` values. Mapping with optional float keys ``alert`` and/or ``digest`` in [0.0, 1.0] (when both set, ``digest <= alert``). When omitted, the global cutoffs apply (pre-existing behaviour). Use this to raise the bar for noisy aggregators (HN/Lobsters/Reddit) since ``trust_weight`` only attenuates downward. - sync_history (bool, optional, default=false): When true and source_type is "github", kicks off an async background import of historical issues/PRs (returns immediately with job_id; use distillery_sync_status to check progress). - purge (bool, optional, default=false): When true and action is "remove", archives all entries from the removed source (soft-delete). Returns the count of archived entries in purged_entries. - probe (bool, optional, default=true): When adding, lightly probe the URL for reachability (HEAD with GET fallback, short timeout). Returns an INVALID_PARAMS error (with details.probe_failed=true) if the probe fails. - force (bool, optional, default=false): When adding, persist the source even if the reachability probe fails (useful for sites that block HEAD but work via the poller). - mode (str, optional, github only): Which content-bearing surface to poll. Valid: [releases, events]. Defaults to "releases" (one body-bearing entry per release). "events" is the opt-in contentless firehose. RETURNS (success): { sources: list, count: int } (list) or { added: dict, sources: list, sync_job?: dict } (add) or { removed_url: str, removed: bool, sources: list, purged_entries?: int } (remove) RETURNS (error): { error: true, code: "INVALID_PARAMS" | "CONFLICT" | "INTERNAL", message: "..." } RELATED: distillery_configure (to adjust feed thresholds), distillery_store_batch (for bulk entry ingestion)

Manage typed relations between knowledge entries. USE WHEN: linking entries together (e.g. marking one as blocking another, citing a reference, or flagging duplicates), walking the relation graph from a seed entry to surface multi-hop neighbours, or computing graph metrics (bridges, communities) on the relations subgraph. PARAMS: - action (str, required): Operation. Valid: [add, get, remove, traverse, metrics, promote_entities]. - from_id (str, required for add): Source entry UUID. - to_id (str, required for add): Target entry UUID. - relation_type (str, required for add, optional for get/traverse): Relation type. Valid: [link, corrects, supersedes, related, blocks, depends_on, citation, duplicate, merge_source, sync_source, mentions, chunk]. - weight (float, optional for add): Edge strength (e.g. interest/engagement magnitude). On a re-assert of an existing edge, supplied attributes are upserted. - valid_at / invalid_at (str ISO 8601, optional for add): Bi-temporal validity window — when the relationship became / stopped being true (invalid_at null = current). - metadata (object, optional for add): Arbitrary per-edge attributes (JSON). - entry_id (str, required for get/traverse, required for metrics scope='ego'): Entry UUID to query relations for (BFS root for traverse / ego-graph). - direction (str, optional for get/traverse, default="both"): Filter direction. Valid: [outgoing, incoming, both]. - relation_id (str, required for remove): UUID of the relation to delete. - hops (int, optional for traverse, default=2): BFS depth, capped at [1, 3]. - metric (str, required for metrics): Graph metric to compute. Valid: [bridges, communities, constraint, link_prediction, orphans]. Requires the [graph] optional extra. - scope (str, optional for metrics, default="global"): Subgraph scope. Valid: [global, ego]. ``"ego"`` requires ``entry_id``. - limit (int, optional for metrics, default=10): top-k results. ``bridges`` = entries by betweenness centrality; ``communities`` = K largest communities; ``constraint`` = entries by lowest Burt constraint (strongest structural-hole brokers); ``link_prediction`` = top predicted edges by Adamic-Adar (pass ``entry_id`` to score adjacencies for one entry); ``orphans`` = sample (<=50) of entry IDs absent from the relations graph (unlinked entries — feeds a linking / gap-scan pass). - project / tags / date_from / date_to (optional, metrics global scope): restrict the entries whose relations participate in the graph. RETURNS (success): { relation_id: str, from_id: str, to_id: str, relation_type: str, weight: float | null, valid_at: str | null, invalid_at: str | null, metadata: object | null } (add) or { entry_id: str, relations: list, count: int } (get) or { relation_id: str, removed: bool } (remove) or { action: "traverse", root: str, hops: int, direction: str, relation_type: str | null, nodes: [{id: str, depth: int}], edges: [{from_id, to_id, relation_type}], node_count: int, edge_count: int } (traverse) or { action: "metrics", metric: str, scope: str, node_count: int, edge_count: int, total_entries: int, graph_node_count: int, orphan_rate: float, results: list, count: int, computed_at: str, cache_hit: bool } (metrics). ``orphan_rate`` = 1 - graph_node_count/total_entries (graph-health signal; 0.0 when total_entries is 0). Or { action: "promote_entities", entities_created: int, entities_reused: int, mentions_created: int, threshold: int } (promote_entities). Scans ``entity/*`` and ``tech/*`` tags and promotes any canonical tag meeting the configured ``tags.entity_promotion_threshold`` to an ENTITY entry node, linking each tagged entry with a ``mentions`` edge. Idempotent. RETURNS (error): { error: true, code: "NOT_FOUND" | "INVALID_PARAMS" | "INTERNAL", message: "..." } RELATED: distillery_correct (creates 'corrects' relations automatically), distillery_find_similar (to discover related entries)

Read or update a runtime configuration value. USE WHEN: reading current thresholds/settings, or adjusting them at runtime without editing the config file directly. PARAMS: - section (str, required): Config section path (dotted notation). Valid: [feeds, feeds.thresholds, defaults, classification]. - key (str, required): Config key within the section. Valid keys by section: feeds: [user_agent]; feeds.thresholds: [alert, digest]; defaults: [dedup_threshold, dedup_limit, stale_days]; classification: [confidence_threshold, mode]. - value (str | int | float | None, optional): New value. Omit to read the current value. When provided, must satisfy type and range constraints for the given key. RETURNS (read): { section: str, key: str, value: any, message: str } RETURNS (write): { changed: bool, section: str, key: str, previous_value: any, new_value: any, disk_written: bool, message: str } RETURNS (error): { error: true, code: "INVALID_PARAMS" | "INTERNAL", message: "..." } RELATED: distillery_watch (to manage feed sources), distillery_status (to review current system state)

Return a lightweight in-protocol health/metadata probe. USE WHEN: verifying MCP connectivity (e.g. from the ``/setup`` wizard) without relying on the HTTP-only ``/health`` endpoint. Works uniformly on stdio and HTTP transports. PARAMS: (none) RETURNS (success): { status: "ok", version: str, # distillery package version build_sha: str, # git SHA (or "dev") transport: "stdio" | "http" | "unknown", tool_count: int, # number of registered MCP tools store: { entry_count: int | null, db_size_bytes: int | null }, embedding_provider: str, # model name or provider class name last_feed_poll: { source_count: int, last_poll_at: str | null }, uptime_seconds?: int # seconds since server startup } RELATED: distillery_list (for entry counts, filtering, and per-group aggregates), distillery_configure (to inspect/adjust runtime configuration)