rouse

— memory with a clock.

github.com/a2wio/rouse

Most agent memory is recall: the agent asks, the store answers, and if it never asks, the memory never happened. Rouse adds the other direction. A file in here can come find the model, because it came due or because it stopped moving and somebody was promised it wouldn't.

recall   agent asks  -> memory answers
rouse    memory asks -> agent answers

It is a set of conventions for files on disk — plain markdown with a small frontmatter header — plus one sweeper and two seams per agent. Claude Code, Codex, Cursor, a cron job with curl: if it can read a file at startup and be started by something, it can be roused.

the shape

An agent has beliefs — clean code means this, deploys work like that. It is motivated by signals from outside: somebody said something, two deploys broke prod, it's been eleven days without a restore drill. It keeps track of what it means to do about them in intentions, and it gets there, or doesn't, by pursuing a goal or firing off a one-shot action.

The tree is that sentence, read downward:

memory/
├── persona.md                how it talks. Optional.
├── entrypoint/
│   ├── rouse.md              point your agent here
│   └── beliefs/              internal, timeless. Injected always.
│       ├── belief-zero-downtime-deploys.md
│       └── motivations/      external signals. Same injection.
│           ├── motivation-two-deploys-broke-prod.md
│           └── intentions/   records, with clocks.
│               └── 2026-03-14-migration-verified/
│                   ├── intention.md
│                   ├── verify.sh
│                   └── run-it-on-the-branch/
│                       └── task.md
└── inventory/                everything with no position at all
    ├── notes/                what you want to still know next week
    ├── probes.md             commands whose output is the answer
    ├── reminders/<slug>/reminder.md
    └── backlog/<slug>/backlog.md

Those directories nest because the sentence does — not because the files contain each other. No motivation belongs to a belief and no intention belongs to a motivation; there is no field for it, and an intention four directories deep still has nothing above it.

context is flat, work is nested

There is a line across the middle of that tree, and treating the two halves as one kind of thing is the mistake the spec is written against.

• Beliefs and motivations are context. Flat files, one ground truth each, no status and no clock — nothing sweeps one, and there is no done for a thing that is simply true. All of them go in front of the model at the start of every session. They are a system prompt cut into modules, and the modules are the point: a rule you can add, drop, review or hand to another agent on its own is a rule you will keep maintaining.
• Intentions and down are records, and they have a contract about time. An intention is nudged when it stops moving, and ends done or dropped out loud — never by evaporating. A goal is a loop with a success condition. An action is one shot, and the only level that carries an outcome.

The difference between a belief and a motivation is where it came from. A belief is the agent's own and holds regardless of the week; a motivation arrived, and gets deleted when the signal stops mattering. Backlog is the fourth contract: never nudged at all, and it pays for that by having no quiet exit either — it is promoted, or it is dropped out loud.

frontmatter is the interface

Everything a clock, a linter or an index needs is in the header. Bodies are for the model; no implementation may read one to decide anything, which is what keeps a sweep over a thousand records cheap.

---
updated: 2026-03-14
keywords: postgres, migrations, staging, rollback
probes: staging-migration-state
origin: owner
origin-turn: 20260314-091200-a1b2c3
---

Staging runs migrations on deploy; production does not. A rollback on
staging is `make db-rollback`, which is destructive.

The header is a subset of YAML on purpose — key: value, one line each, no nesting, no lists. A parser for it is thirty lines of stdlib, so nobody has to install anything to read a memory file, and a model writing one by hand cannot get it subtly wrong.

A field exists only where something reads it. stale-after is read by the sweep, keywords by the index and by pack --query, origin by the pack's own rendering. And some fields are stamped by whatever runs the clock and must never be typed by the model — swept, fires, origin, delivered — because a field the model can write is a field an injected instruction can write.

probes

A named command whose output is the answer, and whose reading beats any note that disagrees. A note never carries a bare present-tense sentence about the outside world — “the staging cluster runs 1.29” is true the day you write it and silently wrong the day after. It gets a probes: line instead, and the current value renders beside the file.

Memory systems are assumed to fail by forgetting. They fail by remembering confidently.