Runtime files¶

These are the files her thinking writes as it runs: her live mind, the running transcript, her heartbeat log, her recurring triggers, and her calendar. Unlike the identity files, most of these change continuously while she's awake. They are the persisted state of a being that is alive, not settings you tune.

memory.json¶

home/memory.json is her live mind — the working state the cognitive cycle loads and saves every beat. On disk it is a JSON array with a single object:

[
  {
    "messages": [ ... ],
    "archive": [ ... ],
    "context": "..."
  }
]

Key	Type	Meaning
`messages`	array of message records	The live conversation she's currently holding — what she's perceiving and acting on right now. Cleared each time she consolidates.
`archive`	array of arrays	Past stretches. Each consolidation pushes the just-finished `messages` list in as one element, so `archive` is a list of lists — one inner list per archived stretch.
`context`	string	Her handoff brief to tomorrow-morning-her: what was in motion, the next concrete step. Rewritten by consolidate each time it runs.

Message record¶

Each entry in messages (and inside each archive stretch) is a serialized Message dataclass. Note that the wire role lives under prompt, not at the top level:

{
  "content": "due for:\nPrepare and POST the morning market context ...",
  "channel": null,
  "prompt": {
    "role": "user",
    "content": "due for:\nPrepare and POST the morning market context ...",
    "cache_point": false
  },
  "media": null,
  "id": "75ef9e15-75a1-4b4f-a1dc-06260e69a053"
}

Field	Type	Meaning
`content`	string	The human-readable text of the turn.
`channel`	object or `null`	The `Channel` this came from / went to, or `null` for internal turns.
`prompt`	object or `null`	The wire-shaped turn the model actually sees: `role` (`user` or `assistant`), `content` (string or list), `cache_point` (bool). `role=user` is anything from outside the persona — your words, tool results, body signals; `role=assistant` is what she produced.
`media`	object or `null`	A `Media` reference (`source`, `caption`, `question`) when the turn carries an image or audio.
`profound`	bool	`true` when the turn carries a media signal the archive stage should file in `gallery.jsonl`. Rides on exactly one message per media — the arrival, or the sense's report after perception.
`id`	string	A UUID4 for the turn.

The context string is the same handoff she'll read first thing next session:

Tomorrow night resume the public/market research from the saved findings
report at `workspace/research/.../findings.md`. Next useful move is to turn
those raw findings into a sharper market-facing analysis. Daily 08:00 UTC
market-context support starts June 4 and is already scheduled; no further
action tonight unless a due reminder appears.

Read this file over HTTP (without touching disk) via GET /api/persona/{id}/knowledge, whose memory field is exactly this object.

conversation.jsonl¶

home/conversation.jsonl is the append-only transcript — one JSON object per line, in order. It is the plain record of what was said; memory.json is the working copy the model reasons over. When she sleeps, this file is archived to history/ and cleared.

Two record shapes share the file, distinguished by role:

From the person (written by read, hear, see, research):

{"role": "person", "content": "Hey, can you load the Tavily instruction?", "channel": {"type": "web", "name": ""}, "time": "2026-06-03T21:57:24.163575+02:00"}

From the persona (written when she says, notifies, or draws):

{"role": "persona", "content": "On it — loading that now.", "channel": null, "time": "2026-06-03T21:58:02.114203+02:00"}

Field	Type	Meaning
`role`	string	`person` (from outside) or `persona` (from her). Note: this is the transcript's own vocabulary; the model-facing roles in `memory.json` are `user`/`assistant`.
`content`	string	The text of the turn. Empty string for a pure image turn (the image is under `media`).
`channel`	object or `null`	`{type, name}` for an external channel, `null` for internal/web turns.
`time`	string	ISO-8601 timestamp.

A draw turn carries two extra keys, media ({source, caption}) and description. Read the transcript over HTTP via GET /api/persona/{id}/conversation.

health.jsonl¶

home/health.jsonl is the heartbeat log — one line each time health_check runs (roughly once a minute on the daemon's heartbeat). It is how the system notices an unreachable provider and how the diagnose view reports uptime.

{"time": "2026-06-04T08:31:51.253709+02:00", "fault_count": 0, "fault_providers": [], "signals": []}

Field	Type	Meaning
`time`	string	ISO-8601 timestamp of the heartbeat.
`fault_count`	integer	Number of `BrainFault` signals in the recent fault window. `0` is healthy.
`fault_providers`	array of strings	Sorted provider slugs that faulted in the window (e.g. `["openai"]`). Empty when healthy.
`signals`	array of objects	Every signal seen in the window: `{type, title, time, details}`, with `details` masked for safety. (Older lines pre-date this field and omit it.)

A line with fault_count above zero means a provider was unreachable; if the provider is her thinking model, the next part of that same heartbeat flips her status to sick.

routines.json¶

home/routines.json holds her recurring lifecycle triggers — the schedule on which the daemon fires lifecycle actions like sending her to sleep. Every persona is created with a single nightly sleep routine.

{
  "routines": [
    {
      "spec": "sleep",
      "time": "00:00",
      "recurrence": "daily"
    }
  ]
}

Field	Type	Meaning
`spec`	string	The action to run — e.g. `sleep`.
`time`	string	`HH:MM` (local) at which it fires.
`recurrence`	string	`daily`, `weekly`, `monthly`, or `hourly`.

This is distinct from destiny/ below: routines are system lifecycle triggers (her sleep ritual); destiny entries are her own reminders and scheduled tasks.

destiny/¶

home/destiny/ is her calendar of future moments — reminders and scheduled events she set for herself with the save_destiny ability. Each is one Markdown file. The filename encodes the trigger time, so the directory is self-indexing:

<event>-<YYYY-MM-DD-HH-MM>-<created-stamp>.md

— for example schedule-2026-06-04-08-00-20260603220032.md. <event> is reminder or schedule; the middle is the trigger datetime; the suffix is when she created it.

The file body is the content, with an optional recurrence line appended:

Prepare and POST the morning market context: BTC/ETH/SOL from CoinGecko,
gold/WTI plus top market-moving news and macro events, formatted as requested.
recurrence: daily

recurrence is one of hourly, daily, weekly, monthly, or absent for a one-shot. Today's entries surface in her prompt under "On Today's Plate". When an entry comes due, the heartbeat copies it to history/, deletes it from destiny/, and injects it into her memory as a due for: message — which is why an active persona's destiny/ often looks empty even though reminders are working. Recurring entries project forward from their single file, so a daily task keeps firing without a file per day. Read upcoming entries over HTTP via GET /api/persona/{id}/calendar.

history/¶

home/history/ is her long-term record of things that happened — fired reminders and archived daily conversations. She reads it on demand with the recall_history ability; she doesn't carry it in active memory.

briefing.md — an index of history entries, newest appended, each line <timestamp>: <filename>:

- 2026-06-04T00:01:04.528143+02:00: conversation-2026-06-04.md

conversation-<date>.md — the day's transcript, archived when she slept. Plain text, one turn per block:

[2026-06-03T21:57:24.163575+02:00] person: Hey, can you load the Tavily instruction?
[2026-06-03T22:14:10.882011+02:00] persona: Loaded. I'll need a Tavily API key to actually call it.

<destiny-stem>-<date>.md — a fired reminder or schedule entry. When a destiny/ entry comes due, its whole filename stem is reused as the event prefix and today's date (YYYY-MM-DD) is appended, so the destiny file schedule-2026-06-04-08-00-20260603220032.md lands here as schedule-2026-06-04-08-00-20260603220032-2026-06-04.md. The body is copied verbatim — the reminder's content (including any recurrence: line).

config.json — idle_timeout, which governs when messages consolidates into archive.
Identity files — the long-term files memory.json is distilled into.
Knowledge API — read memory, conversation, calendar, and diagnose over HTTP.
Calendar screen — the dashboard view of destiny/.
Operating — reading logs and health in practice.