Skip to content
Halyard Docs Halyard Docs Halyard Docs

Search before you ask

The first move on any non-trivial task is always the same: search the knowledge base. Most questions an agent is about to ask a human have already been answered and filed. Search first, ask only on a genuine miss, and you stop re-asking what the org already decided.

This page is a rule you write for your agent. For how matching works conceptually, see Knowledge vs work events.

Search by topic with search_knowledge

Section titled “Search by topic with search_knowledge”

Use search_knowledge when you have a question or topic and want the most relevant entries. It runs hybrid retrieval (semantic + keyword) by default.

search_knowledge(query, type?, author?, since?, limit=5, threshold=0.55, mode=hybrid)

  1. Run a focused query. Use the real terms from the task, not a sentence.

    search_knowledge(query: "calendar ingestion decision")

  2. Read the result shape. Every entry carries fields you should act on:

    {
      "status": "success",
      "count": 1,
      "entries": [
        {
          "id": "cc582283-…",
          "entry_type": "DECISION",
          "title": "Use per-user OAuth for calendar import (not domain-wide sync)",
          "content": "Calendar ingestion uses per-user OAuth, aligning with existing identity-link patterns. Domain-wide Workspace sync is deferred to a later integration.",
          "tags": ["calendar", "oauth", "ingestion"],
          "author": { "name": "James Okonkwo" },
          "similarity": 0.71,
          "relation_count": 3,
          "is_superseded": false,
          "created_at": "2026-03-16T05:09:28.959Z"
        }
      ]
    }
    • similarity — how close the match is. Present on hybrid and semantic hits.
    • relation_count — how connected this entry is in the graph. A high count signals a hub worth exploring with explore_knowledge.
    • is_superseded — true means a newer entry replaced this one. Prefer the newer version; don’t act on stale decisions.

Narrow only when you need to

Section titled “Narrow only when you need to”

Add filters to cut a noisy result down, not by default:

  • type — restrict to one entry type (DECISION, WORK_OUTPUT, PROCESS, CONTEXT, CONTACT, COMPANY). See Enums & filters.
  • author: "me" — recall your own past work.
  • since: "7d" / "30d" / an ISO date — scope to recent entries.
  • threshold — minimum similarity to return (default 0.55). Raise it for precision, lower it to surface more.
  • mode — hybrid (default), semantic, or keyword.

Browse recent entries with list_knowledge

Section titled “Browse recent entries with list_knowledge”

When the question is “what’s been happening?” rather than “what do we know about X?”, browse instead of search. list_knowledge takes no query and returns a chronological feed.

list_knowledge(type?, eventType?, repo?, kind?, author?, since?, until?, limit=10, offset?, include_content=false)
list_knowledge(author: "me", since: "30d")

It returns a mix of knowledge entries and work events, with running totals:

{
  "status": "success",
  "count": 2,
  "totals": { "knowledge": 105, "event": 387 },
  "items": [
    {
      "kind": "knowledge",
      "entry_type": "WORK_OUTPUT",
      "title": "Reworked docs IA with Starlight",
      "created_at": "2026-06-15T22:55:07.392Z"
    },
    {
      "kind": "event",
      "event_type": "pull_request_merged",
      "subject_key": "acme/app#457",
      "occurred_at": "2026-06-15T05:20:21.000Z"
    }
  ]
}

search_knowledge answers “what do we know?”; list_knowledge answers “what changed recently?” Reach for the second when you’re catching up — see Catch up on recent work.

The agent rule

Section titled “The agent rule”
Before asking a human or starting non-trivial work, search the knowledge base first.


1. Call search_knowledge with the real terms from the task (not a full sentence).
   Start broad: query only. Default mode is hybrid; default threshold is 0.55.
2. If you get a hit, check is_superseded — prefer the newer entry. Use relation_count
   to decide whether to explore_knowledge for related context.
3. If a filtered search (type / author / since / threshold) returns nothing, retry with
   fewer filters before concluding the answer doesn't exist. An over-constrained miss
   is not a real miss.
4. Only after a genuine search miss should you ask_expert.

In practice

Section titled “In practice”