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

	Knowledge entries	Work events
Answers	”What have we decided / learned about X?"	"What happened, and when?”
Shape	Narrative, summarized, authored	Structured metric records
Searchable?	Yes — semantic + keyword	Keyword only — list_events query; never semantic
Read with	search_knowledge, list_knowledge	list_events, list_knowledge (chronological)
Written by	summarize_conversation, summarize_work, ingestion	Source webhooks (GitHub, Linear, ClickUp, Calendar)
Examples	A decision, a process, a captured Q&A	A merged PR, a status change, a meeting

Knowledge is meaning. Work events are activity. You search knowledge; you scan (or keyword-filter) events.

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.

Coding-agent sessions land in both substrates at once: each synced session becomes a knowledge entry (the summary, searchable by meaning) and an agent_session_completed event (source_provider claude, codex, gemini, opencode, or copilot). The event’s metadata is numbers-only — costUsd, durationSeconds, userTurnCount/assistantTurnCount, token totals, primaryModel, and toolCallCount — so agent-driven work shows up in the same per-person activity ledger as merged PRs and closed tickets, without any prompt content leaving the session summary.

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.
• “Find the PR about the auth rewrite” → list_events with query: "auth rewrite". Keyword matching over event titles and subject keys — a lookup, not a meaning search.
• “What happened around this decision?” → explore_knowledge on the entry. Its activity block lists the events whose subjects the entry mentions (PRs, issues, pages, the meeting’s calendar slot).
• “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.

Caution

Do not reach for search_knowledge to find a pull request, and do not expect list_events to surface a decision. Events are not indexed for semantic search — list_events query is keyword matching on titles and subject keys, nothing more. If a question is about what was concluded, search knowledge; if it’s about what occurred, list events.

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.

How they connect

The two substrates are joined by subject, not by similarity. When a knowledge entry names a pull request, an issue, a task, or a page — by URL or by key such as acme/app#457 or ENG-42 — Halyard records a link from the entry to that subject. Every event on the subject (opened, reviewed, merged, status changed) then hangs off the entry, including events that arrive after the entry was written. Session summaries also link to the pull requests raised from the session’s branch, and meeting notes link to the calendar slot they were captured in.

• explore_knowledge returns an activity block: event count, last activity, and the most recent events.
• search_knowledge results carry event_count and last_activity_at.
• list_events accepts knowledge_entry_id to list one entry’s activity, and each event carries the knowledge entries linked to its subject.

Links are derived, never authored: they appear when an entry is written or edited, and disappear when the mention does.

In practice

• Search before you ask — querying knowledge entries.
• Catch up on recent work — events vs knowledge for “what happened” questions.
• Knowledge entries & the graph — how knowledge entries are typed and linked.
• Tool reference — search_knowledge, list_knowledge, and list_events signatures.