References

Knowledge in Task Machine is only useful if the pieces connect, and references are the connective tissue. A reference is a markdown link that points at another record in the workspace — a document, an artifact, a task, a goal, a person, or an agent — and stays correct as that record is renamed or moved. This closes the chapter: a memory is what an agent remembers, an artifact is what it produces, and references are how all of it links into one connected body of knowledge.

A reference is a markdown link to a stable id

A reference looks like an ordinary markdown link, but its target is a typed identifier rather than a URL — a kind and an id, such as a document or task target. That id is stable: it names the record itself, not its current title or path. So when someone renames a document or moves an artifact to a different folder, every link that points at it keeps working, because the link was never tied to the name in the first place. This is what lets knowledge get reorganized without leaving a trail of broken links behind it.

Targets fall into two groups, stored to match what they point at. Document and artifact references point at stable content items and are stored as content links. References to other workspace records — tasks, goals, members, and agents among them — are stored separately as entity references, because those records live outside the knowledge content hierarchy. The set of supported target kinds is open by design, so new kinds of records can become linkable without changing how references work. Today the writing surfaces that emit references are the markdown bodies of documents and artifacts.

References resolve to a name at render time

A reference is rendered, not frozen. When a body containing a reference is displayed, Task Machine looks the target up in the current workspace and shows its latest display name or path — so a link always reads as the record is named right now, not as it was named when the link was written. Each reference also stores a snapshot of the label it had at write time, which serves as a fallback.

That fallback is what keeps rendering safe when a target cannot be resolved. If the linked record has been deleted, if the person reading does not have permission to see it, or if it sits under a folder that has been archived, the reference does not error or expose an internal id — it falls back to plain text from the stored label. Permission is checked on every resolve, so references never become a way to discover records a member is not allowed to see, and a link into archived knowledge reads as inert text until that folder is recovered.

References power backlinks

Because references are stored as records, they can be read in both directions. Following a reference forward takes you from a body to the record it links to; reading them backward gives you backlinks — the set of records that point at a given document or artifact. A document can show which artifacts and tasks reference it, so you can see how a piece of knowledge is actually used across the workspace. Backlinks are filtered by permission the same way forward references are, so they only ever surface sources the current member is allowed to see.

To write a reference, you do not type an id by hand. Typing @ in any writing surface opens a single picker that searches everything you can access — people, agents, teams, tasks, goals, documents, artifacts, and skills — and inserts a stable link. The exact link syntax and the full set of target kinds are covered in the markdown reference.

This is where the knowledge chapter closes. With memories, artifacts, and references in place, an agent reads from a connected body of context and writes back into it. From here, the docs turn to making that work repeatable — see the workflow builder for turning a proven process into something that runs again.