Skip to content
Halyard Docs Halyard Docs Halyard Docs

Knowledge entries & the graph

A knowledge entry is the unit of memory in Halyard — a captured decision, work output, process, or person. Each entry has a type, moves through a lifecycle, and connects to other entries through relations. The important idea up front: the type is a lens for finding things, not a schema you have to satisfy to write something down. Structure in Halyard comes from the links between entries, not from a rigid hierarchy.

Entry types are lenses, not schemas

Section titled “Entry types are lenses, not schemas”

Every entry carries an entryType. There are six:

TypeLens for
WORK_OUTPUTSomething an agent or person produced or shipped
DECISIONA choice the org made, and why
PROCESSHow something is done — a repeatable procedure
CONTEXTBackground that doesn’t fit the others
CONTACTA person record (every user has a paired one)
COMPANYAn organization record

These types exist for filtering and retrieval — pass type to search_knowledge to narrow a query. They never gate creation. There are no required fields and no validation refusals; the system never rejects knowledge because it doesn’t fit a shape (principle P3, “types are lenses, not schemas”). Pick the closest type and move on — the lens helps later searchers, it doesn’t block the writer.

Lifecycle

Section titled “Lifecycle”

An entry moves through three states:

INBOX  ->  FILED  ->  ARCHIVED
  • INBOX — newly created and, when AI-generated, awaiting human review. New entries from summarize_work and ingestion land here.
  • FILED — accepted into the org’s living memory and fully searchable.
  • ARCHIVED — retired; kept for history but out of the way.

The INBOX stage is the review gate. AI-generated entries wait there for a human to accept or dismiss them before they become part of trusted memory — see the inbox.

Section titled “Relations: structure emerges from links”

Entries connect to each other through typed relations. There are five:

RelationMeaning
RELATED_TOGeneral association between two entries
SUPERSEDESThis entry replaces an older one
DERIVED_FROMThis entry was produced from another
REFERENCESThis entry points at another as a source
WORKS_ATA CONTACT is linked to a COMPANY

Many of these are discovered automatically — Halyard invests in relation discovery, mention detection, and semantic clustering rather than asking people to wire links by hand (principle P4, “structure emerges from links, not labels”). The graph grows as a side-effect of capture; the connections are bidirectional and cheap.

Search results expose this connectedness directly. Every hit carries relation_count (how linked the entry is) and is_superseded (whether a newer version exists):

{
  "id": "cc582283-…",
  "entry_type": "DECISION",
  "title": "Use per-user OAuth for calendar import (not domain-wide sync)",
  "similarity": 0.71,
  "relation_count": 3,
  "is_superseded": false
}

A high relation_count signals a well-connected, load-bearing entry. is_superseded: true warns you a newer entry exists — follow the graph to find it.

Traversing the graph

Section titled “Traversing the graph”

explore_knowledge(entry_id, depth?, types?) walks the relations out from any entry — to see what superseded it, what it derived from, and what else it connects to. Start from a search_knowledge hit (or from caller_profile.profile_entry_id on a search response) and explore outward when one entry isn’t the whole picture. When an entry is marked superseded, exploring its relations is how you reach the current version.

In practice

Section titled “In practice”