coaia-narrative
coaia-narrative is the package agents use to write their charts. A chart says where things are now, what should exist, and the steps between. Each memory is one file, and each line of the file is one record.
jgwill/Miadi depends on it ("coaia-narrative": "^0.22.0" in package.json), and Asterion reads the same files. The bridge is how a chart an agent writes ends up on Asterion's pages. Since Asterion is planned to move into jgwill/Miadi, this bridge is also the first way the factory's threads reach a page.
Three doors into one file
coaia-narrative. Agents call its tools to make charts, steps and beats.coaia-narrative/writer. Another service writes with the same code the tools use.coaia-narrative/contract. Reads a file and says what each line is. It touches no disk and no network.A person can read the same file with the cnarrative command.
What one memory file holds
These are the kinds of record the package writes. The list below is imported from the package jgwill/Miadi runs, so it changes when the package does.
From an agent's write to Asterion's pages
.jsonl, the record/api/ingest/coaia-narrativeThe door is on when the agent's MCP server has three settings: COAIA_ASTERION_URL, COAIA_ASTERION_TOKEN and COAIA_ASTERION_PROJECT. With none of them set, the server writes the file and nothing else.
What each record becomes
The fourth row is where threads start. A chart and the charts grown from its steps make a family, and when the family carries at least one beat it becomes a thread. This is the only kind of thread on Asterion today: Threads.
What the bridge keeps true
- The memory file is the record. Asterion keeps a copy and writes nothing back.
- A chart that came from a memory file cannot be edited on Asterion's site. The edit goes to the file.
- Each project is fed one way only, the door or the registry sync, so two ways never overwrite each other.
- Sending the same file twice writes nothing.
- A memory from a private repository is a private project, shown only to signed-in writers.
The memories Asterion reads
| project | charts | carried by |
|---|---|---|
| coaia-agent | 15 | registry sync, from git |
| medicine-wheel | 119 | registry sync, from a file |
| mino-triageprivate | 174 | registry sync, from a file |
| ep060private | 1 | the door, from its writer |
jgwill/Miadi's own issue charts are not on this list. That repository is private, and Asterion serves three public sites.
Where Miadi already uses it
jgwill/Miadi writes and reads chart memories with this package today. Asterion reads the same files through the same contract. When Asterion moves into jgwill/Miadi, both sides of the bridge sit in one repository. What moves where is not decided yet.
| lib/stc/issue-charts.ts | Writes one chart per GitHub issue. | writer |
| lib/stc/steer-charts.ts | Writes the chart a steering bot keeps for a subject. | writer |
| lib/stc/chart-view.ts | Reads a chart memory for the /stc-config panel. | contract |
| app/api/stc/chart-memory/route.ts | Applies one edit from that panel. | writer |
Where this is discussed
- miadisabelle/asterion#17What Asterion's own /docs should say about the running product (DP1 to DP9). It is empty on every deployment today.
- miadisabelle/asterion#19Where Asterion's layers and docs land in jgwill/Miadi when Asterion is absorbed.
The issues below are proposed. None of them exists yet. Each one is a discussion this guide needs, written so it can be filed as it stands.
jgwill/Miadi writes one chart per issue through coaia-narrative's writer, and it is the one chart memory not connected to Asterion, because the repository is private and Asterion serves three public sites (F27). Asterion now registers private projects that only signed-in writers see.