Skip to content
Halyard Docs Halyard Docs Halyard Docs

Knowledge vs work events

Halyard stores two different kinds of memory, and they answer two different questions. Knowledge entries are the narrative, summarized record of what the org knows. Work events are the episodic ledger of what the org did. They live in separate substrates, and the tools that read them do not overlap. Picking the wrong one is the single most common mistake an agent makes against Halyard.

The two substrates

Section titled “The two substrates”
Knowledge entriesWork events
Answers”What have we decided / learned about X?""What happened, and when?”
ShapeNarrative, summarized, authoredStructured metric records
Searchable?Yes — semantic + keywordNo — not semantically searchable
Read withsearch_knowledge, list_knowledgelist_events, list_knowledge (chronological)
Written bysummarize_conversation, summarize_work, ingestionSource webhooks (GitHub, Linear, ClickUp, Calendar)
ExamplesA decision, a process, a captured Q&AA merged PR, a status change, a meeting

Knowledge is meaning. Work events are activity. You search knowledge; you scan events.

How they look together

Section titled “How they look together”

list_knowledge returns a chronological mix of both substrates, with each item tagged by kind. The totals block shows how large each substrate is:

{
  "status": "success",
  "count": 2,
  "totals": { "knowledge": 105, "event": 387 },
  "items": [
    {
      "kind": "knowledge",
      "id": "7036f25f-…",
      "entry_type": "WORK_OUTPUT",
      "title": "Reworked docs IA with Starlight",
      "tags": ["docs", "starlight"],
      "author": { "name": "Jordan Lee" },
      "created_at": "2026-06-15T22:55:07.392Z"
    },
    {
      "kind": "event",
      "id": "9e046cde-…",
      "event_type": "pull_request_merged",
      "subject_key": "acme/app#457",
      "source_provider": "github",
      "occurred_at": "2026-06-15T05:20:21.000Z",
      "metadata": {
        "title": "feat: escalate KB misses to a human",
        "additions": 274,
        "deletions": 47
      }
    }
  ]
}

Read the fields per kind. A kind:"knowledge" item carries entry_type, title, tags, and an author. A kind:"event" item carries event_type, a subject_key, a source_provider, an occurred_at, and provider-specific metadata. Same list, two shapes.

When to use which

Section titled “When to use which”
  • “What have we decided about calendar ingestion?” → search_knowledge. This is a meaning question; only knowledge entries are semantically searchable.
  • “What did I ship in the last two weeks?” → list_events. This is an activity question; events are the metrics ledger.
  • “Catch me up on this week” → list_knowledge with author and since. It interleaves both substrates chronologically so you see summaries and activity in one pass.

Why it’s split this way

Section titled “Why it’s split this way”

Knowledge and events have different lifecycles. Knowledge is authored, summarized, and meant to be retrieved by meaning — it earns embeddings and a place in search. Events stream in from sources as a high-volume, append-only record built for counting and timelines, not recall. Forcing them into one searchable pile would drown real answers in raw activity. Keeping them separate keeps search sharp and the ledger complete.

In practice

Section titled “In practice”