On-disk layout

Everything relative to Twig root (<documents>/twig). Same shape phone, laptop mirror, backup zip. Portable. Boring. Good.

Tree

twig/
  agents/
    <agentId>/
      agent.md
      memory/
        facts.md
        notes/
      skills/
        <slug>/SKILL.md
      macros/
        <slug>.json
      scripts/
        <slug>.ts          # companion only
      conversations/
        <conversationId>.ndjson
      dreams/
        <iso-timestamp>.md
      .twig/
        manifest.json
        journal.ndjson
        versions/
  workspaces/
    <workspaceId>/
      …user files…
      .twig/
        …
  blobs/
    <ab>/
      <sha256>
  db/
    twig.db

Paths that matter

Path	Meaning
`agents/<id>/`	Agent home (private)
`workspaces/<id>/`	User workspace
`blobs/<2-char>/<sha256>`	Attachment
`db/twig.db`	Derived SQLite
`.twig/journal.ndjson`	Mutation journal
`.twig/versions/<sha>`	Old file body
`conversations/<id>.ndjson`	Chat log, one msg per line
`dreams/<iso>.md`	Dream report humans can read

Journals

One NDJSON line per entry. Append only. Never rewrite. Never compact in place.

Ops: write, delete, move, mkdir, blob, grant, revoke.

Torn final line after crash = normal. Skip it. Torn line in middle = something outside Twig smashed the file. Keep parseable entries. Report garbage. Still open workspace.

Path safety

normalizeRelativePath = choke point:

reject absolute, .., backslash, NUL
return clean POSIX-relative path

Agents never write .twig/ themselves. Reserved. Tools read ok. Write = system only.

Tree

Paths that matter

Journals

Path safety

On this page