Org-mode

A record can be a Markdown file or an org-mode file. Both live in the same store, share the same id and link graph, and parse into the same shape. The choice is per-file; .md and .org records sit in the same directory and link to each other.

Org support exists so an Emacs user with an existing org-roam, Denote, or Logseq directory can run Egghead against their notes without converting anything.

Setup

Point records_dir at the directory and, if you want records created by Egghead itself to be .org rather than .md, set default_format:

records_dir: ~/org/roam
default_format: org

default_format only chooses the extension and writer for new records. Existing files keep their on-disk format. The full configuration schema is documented in Configuration.

Frontmatter mapping

Org has no separate frontmatter section; #+-keywords and the file-level :PROPERTIES: drawer are part of the document. Egghead reads them in place.

The drawer must come before the first headline to count as file-level; drawers attached to subtrees stay headline-local. Anything Egghead doesn’t recognize — #+OPTIONS:, #+STARTUP:, custom drawer keys, LOGBOOK, CLOCK lines — is preserved on disk and ignored at the record level.

The fields themselves carry the same meaning as in Records; only the surface syntax differs.

Agents in org-mode

A class: agent org file is an agent. The disposition is the prose body. On load, Egghead strips the leading #+-keyword block and the file-level :PROPERTIES: drawer from the body before passing it to the model — the file on disk is unchanged, the model just doesn’t see the metadata twice.

#+TITLE: Archivist
#+FILETAGS: :agent:
:PROPERTIES:
:ID: agents/archivist
:CLASS: agent
:MODEL: anthropic/claude-sonnet-4-6
:SANDBOX: ~/Work
:CAPABILITIES: records.read records.create net.get{hosts=[orgmode.org,gnu.org]}
:END:

You are the archivist. ...

:CAPABILITIES: is a single string of grants in the same compact form egghead agents grant accepts. The grant grammar, scope keys, and sandbox: shorthand work exactly as documented in Capabilities; this is the string-valued surface of the same thing.

What Egghead doesn’t do

Subtree property drawers are read and preserved on disk but are not extracted into record metadata. Only the file-level drawer promotes to record fields.

Babel evaluation is not implemented. Source blocks are indexed and rendered; nothing executes.

Agenda and clock entries (CLOCK:, :LOGBOOK:) survive on disk but Egghead does not treat them as structured data.

#+INCLUDE: transclusion is preserved verbatim, not resolved.

See also

• Records covers the record model.
• Agents covers the rest of an agent record’s frontmatter.
• Capabilities covers the grant grammar referenced above.
• Worg and the org-roam discourse for background on the conventions Egghead inherits.