The .andon/ directory format
.andon/ at a repository’s root is what the repository remembers: conventions, decisions, traps and how-tos, longer
notes, and the plans of its projects. It is committed beside the code, so every clone, tool and Andon instance reads the
same files. This page is the file format. The schemas are in packages/shared/src/andon-directory.ts.
Layout
.andon/ README.md what this directory is (a fixed text) settings.json the team's automation settings (repo-settings.md) memory/<kind>/<ULID>-<slug>.md one memory entry a file knowledge/<topic>.md a longer note on one topic, edited in place knowledge/<area>/<topic>.md the same, grouped by area plans/<project-slug>/plan.md a project's goal, approach and decisions plans/<project-slug>/groups/<ULID>-<slug>.md a PR group's plan, written when the group starts buildingNothing else. No index files, counters or generated files: Andon builds its index from the files. A file that isn’t one
of these isn’t Andon’s, and Andon ignores it. settings.json has its own page.
Names
<ULID>: 26 Crockford base32 characters, the first0to7(01JBQ3Y4Z5A6B7C8D9E0F1G2H3). It sorts by time, and two branches never pick the same one. It is the entry’s identity.<slug>: lowercase letters and digits joined by-, at most 40 characters, made from the title. It is for people; any slug works.<kind>:conventions,decisions,gotchas,how-to,glossaryorpeople.<topic>,<area>,<project-slug>: one segment each, with the slug’s grammar.
The README
Andon writes .andon/README.md the first time it writes anything else there, and never rewrites it. It says what the
directory is, that entries are never edited in place, and where plans go.
The pointer in CLAUDE.md and AGENTS.md
When it imports memory or writes a plan, Andon adds three lines between <!-- andon:start --> and
<!-- andon:end --> to a repository’s CLAUDE.md or AGENTS.md: what .andon/ is, that its entries are the repository’s memory, and that andon memory show prints them.
It replaces only the text between the markers.
Front matter
Every file is Markdown that starts with front matter between --- lines. The front matter is flat YAML:
key: value,key: "quoted value",key: [a, b], or a- itemlist under a barekey:#after a space starts a comment, so quote a value that holds one- no nesting, anchors or multi-line values: prose goes in the body
Dates are YYYY-MM-DD or an ISO date-time. An unknown key makes the file invalid.
A memory entry
memory/<kind>/<ULID>-<slug>.md
| Field | Value |
|---|---|
id |
The ULID, the same as in the file name. |
kind |
The same as the folder. |
status |
proposed, accepted or retired. |
title |
One line, up to 120 characters. |
tags |
Up to 12: lowercase letters and digits, with - or . inside (db, board.cards). |
paths |
Up to 20 globs relative to the repository, .gitignore style (apps/board/**, *.test.ts). |
source |
Where it came from: run, review, reply, comment, person or import, then what it points at (review PR 212, run WEB-12). |
confidence |
0 to 1. A person’s own entry is 1; a run’s proposal starts lower. |
supersedes |
The id of the entry this one replaces, or none. |
created |
When it was written. |
history |
Only on a compacted entry: the ids folded into it. |
sources |
Only on a merged entry: the other entries’ sources. |
The body is one paragraph a run can act on: the convention, why, and what to do. Keep it under about 300 tokens (1,200
characters); longer belongs in a knowledge note that the entry points at. A people entry names a person by their
Andon handle; an email address is refused in any entry.
A knowledge note
knowledge/<topic>.md or knowledge/<area>/<topic>.md
| Field | Value |
|---|---|
title |
One line, up to 120 characters. |
tags |
As for an entry. |
paths |
As for an entry. |
updated |
When it last changed. |
The body is up to about 1,500 tokens. Split a bigger note into two topics, or an area.
A project plan
plans/<project-slug>/plan.md
| Field | Value |
|---|---|
title |
One line, up to 120 characters. |
status |
active (the default), done or canceled. |
updated |
When it last changed. |
The body is the project’s goal, approach and the decisions taken on the way, up to about 1,500 tokens.
A group plan
plans/<project-slug>/groups/<ULID>-<slug>.md
| Field | Value |
|---|---|
id |
The ULID, the same as in the file name. |
title |
One line, up to 120 characters. |
branch |
The group’s branch, or none until it has one. |
cards |
The cards it builds, by key or id (up to 50). |
updated |
When it last changed. |
The body is why the cards ship together, up to about 800 tokens.
Changing what’s there
- A memory entry is never edited in place. To change one, add a new file whose
supersedesnames the old id. To remove one, add a file withstatus: retiredandsupersedes. Andon reads each chain through its newest file. - Only an accepted or retired entry replaces what it names. A proposed one is listed beside the entry it would replace until a review accepts it.
- Two branches that supersede the same entry leave two heads: both are read, newest first, until a third entry supersedes both.
- A
supersedesthat names a missing id is reported, and the entry still counts. - Knowledge notes and plans are edited in place. A group plan isn’t edited after its group merges.
Runs propose entries with the remember and knowledge MCP tools; a proposal rides the run’s pull
request.
An example entry
.andon/memory/gotchas/01JBQ3Y4Z5A6B7C8D9E0F1G2H3-a-schema-change-is-two-files.md:
---id: 01JBQ3Y4Z5A6B7C8D9E0F1G2H3kind: gotchasstatus: acceptedtitle: A schema change is one filetags: [db, migrations]paths: [db/migrations/**]source: review PR 212confidence: 0.9supersedes: nonecreated: 2026-11-02---
Every schema change is one new file under `db/migrations/`, named by the UTC time, then `pnpm db:check`. Editing anapplied file fails `db:check` and is sent back.Check and read it
andon memory show [path]prints the live set from a checkout’s files: accepted entries with their chains resolved. No board needed. See theandoncommand.- In Andon’s own repository,
pnpm check:andon-dirchecks every file under.andon/for secrets, and every entry and note against this format.
