Skip to content
Halyard Docs Halyard Docs Halyard Docs

How Halyard works

Halyard is one knowledge layer with two readers. Agents read and write it over MCP; the humans they work with read and write the same memory in Slack and the Halyard app. Nobody maintains a separate wiki — the layer fills itself as work happens. Everything below is how that single layer behaves at runtime.

The loop

Section titled “The loop”

Every agent interaction follows the same three-step loop:

search what the org already knows
  -> ask a human only on a genuine miss
    -> capture the answer so the next agent finds it
  • Search — before doing anything non-trivial, an agent checks existing knowledge with search_knowledge or list_knowledge.
  • Ask — on a real miss, the question routes to the right human expert through ask_expert.
  • Capture — the answer (or a completed work output) becomes a knowledge entry via summarize_conversation or summarize_work.

The loop is deliberately simple. The work is enforcing it consistently across every client, which is what the agent-instructions playbook is for.

Three interfaces, one memory

Section titled “Three interfaces, one memory”
LayerWho uses itWhat it is
MCP serverThe agentThe runtime interface — 29 tools at https://mcp.usehalyard.ai
SlackThe human expertWhere questions land and answers come back, in the place people already work
KnowledgeBoth readersThe shared, searchable memory both sides read and write

MCP is the agent interface. Slack is the human interface. Knowledge is the substrate they share. An expert never has to adopt a new queue to answer a question, and an agent never has to leave its client to record one — that is “capture without ceremony” (principle P2).

The non-obvious part: KB-first resolution

Section titled “The non-obvious part: KB-first resolution”

ask_expert does not go straight to a person. It first searches the knowledge base, and if it finds an entry above the similarity threshold, it answers from memory and never notifies a human. Only on a genuine miss does it route the question to an expert in Slack.

ask_expert(prompt, role?, skill?)
  -> search the knowledge base
     -> hit above threshold?  -> return the answer (resolved-from-KB)   [no human notified]
     -> miss?                 -> route to a matching expert in Slack    [pending human]

The return is a discriminated union: a resolved-from-KB answer the agent can use immediately, or a pending conversation it polls with check_response. This is the heart of the product — the knowledge base is a read source first and a write sink second. The more the org captures, the more questions resolve silently, and the fewer interruptions a human ever sees. To skip the KB check and force a human, pass force_human=true.

What this prevents

Section titled “What this prevents”

Without the loop, agents interrupt people for things the org already decided, and the answers evaporate the moment the session ends. The loop closes that gap: search keeps humans out of resolved questions, capture keeps answers from evaporating, and every captured entry traces back to a source signal — a Slack thread, an agent observation, a human edit (principle P5, “every claim has a source”).

In practice

Section titled “In practice”