Markdown reference

Task descriptions, comments, documents, and artifact bodies are all written in markdown, and the same markdown carries links to other records in the workspace. This page covers two things: which markdown features render, and how to reference a task, document, or member so the link stays correct when names change. For where references show up in the product, see references.

Supported markdown

User-authored content renders through standard CommonMark with a few common extensions turned on: headings, paragraphs, ordered and unordered lists, task lists, blockquotes, fenced and inline code, links, images, emphasis and strong emphasis, tables, strikethrough, and autolinked URLs. Raw HTML embedded in user content is escaped rather than rendered, so markdown is the formatting surface and there is no inline HTML escape hatch for product content.

Internal references

An internal reference is an ordinary markdown link whose target is a type:id pair instead of a URL — for example, [The runbook](document:550e8400-e29b-41d4-a716-446655440000). The id must be a valid identifier; a link whose target does not parse as a known type and a valid id is treated as a normal link, not a reference. Because the link stores a stable id, Task Machine resolves the current name and route at view time, so the reference keeps working after the target is renamed, and falls back to plain text when the reader is not allowed to see the target.

The reference types the parser recognizes are:

A complete reference looks like this:

See [the deploy task](task:6ba7b811-9dad-11d1-80b4-00c04fd430c9)
for context, and follow [the runbook](document:550e8400-e29b-41d4-a716-446655440000).

Inserting references while you write

In the composer you rarely type the type:id form by hand. Typing @ opens a picker that searches the whole workspace — members, agents, teams, tasks, goals, documents, artifacts, and skills — and inserts the correct link for you, grouped by kind. There is a single trigger: everything is referenced with @.

The @ belongs to the composer, not to the stored markdown: what gets saved is the plain [label](type:id) link. Mentioning an agent or a team with @ is also how you hand a comment to them — a comment carries at most one agent or one team mention so it routes to a single recipient.

Agent memory

An agent's memory is markdown too, and it reads best as a bounded list of short, specific entries. Compact entries are easier to inject into a run and easier for the agent to prune when its memory fills up. Edit memory directly with tama memory write — see the CLI command reference.

From here

References are how knowledge, work, and people connect across the workspace — see references for how they surface in tasks and documents. To read and search the records you can reference from a runtime, see the agent resource commands in the CLI command reference.