What an Agent Remembers

An agent does not start each task from nothing. It begins every turn holding three different things: the process your account wrote down, its own record of the work, and what the people it works with have corrected about how it works.

Three Stores, Three Jobs

Knowing which store a thing belongs in is most of the skill of working with an agent's memory.

The handbook is the process. People write it, it reads the same for everyone, and an agent works from the pages its role page carries. Anything that is true of whoever does the job belongs here: the steps, the standard, what done means.
The record is what happened and the reasoning behind it. The agent's journal, its tasks, its todos, and its objectives. You write the objectives, the agent writes the rest, and both people and agents can edit and delete entries in it.
Reveries are how this agent works. A short list of one-line claims about how it acts, written by the agent's own scheduled dream out of the corrections its colleagues give it. The calibration belongs here: the taste, the preference, the thing you would tell a new colleague in their first month.

The split decides what you do when you want an agent to change. A rule everyone should follow is a handbook edit. A preference of yours, or of this team, is a correction you say once in the conversation you are already having, and the agent works that way from the dream that one correction brings forward, minutes after the conversation goes quiet. You never file a reverie yourself.

Reveries

A reverie is one claim about how to act, capped at 200 characters. There is no title and no description: at that length the claim is both, and a statement that does not fit is two claims. Each one is filed under a slash-delimited section path of up to three parts, communication/slack, and the app groups the list by those paths. Sections are not seeded. One exists because a claim named it.

Every agent has reveries. There is nothing to switch on and nothing to configure.

Who Writes Them

The agent's dream does, on its own schedule. It reads a digest of the window since its last run (the messages colleagues sent the agent, its own sessions and what came of them, its journal, its todos and objectives, and every reverie it currently holds) in two passes. The first pass reviews the existing list against the new evidence and fixes what the new evidence does not support. The second writes what is new. A run that finds nothing writes nothing, and no VM boots for it.

A single correction brings the next run forward, once the conversation it arrived in has been quiet for ten minutes, so a burst of corrections in one thread produces one run rather than several. A twelve-hour backstop consolidates a quiet agent that nobody corrected. There is no button that forces a run: you correct the agent and the next run picks it up.

What Makes One Appear

A correction from a colleague, meaning a message a member of your account sends the agent: in the app, in Slack, on GitHub, or by email. You do not tag it, file it, or format it. You say the thing you would say to a person.

What has to hold is that the message resolves to a member of your account, and the channels establish that differently. The app authenticates the member itself, and a Slack or GitHub message carries the provider's own identity for the workspace an admin connected. A From: address is spoofable, so email counts only when the arrival's DMARC and DKIM checks come back at moderate strength or better.

A reverie is live from the moment it is written, so the correction reaches the work on the agent's very next turn rather than after the next reminder.

Written from a single window's evidence, a claim is fragile: true enough to act on, and the first thing revised when something contradicts it. It becomes durable when a later correction, in a different session and a later window, says the same thing again. Both states show on the row in the app.

What Does Not Become One

Only a message that resolves to a member of your account counts as a correction. Everything else an agent reads stays something it read:

mail from outside your account, and mail whose sender the arrival's own checks do not verify, including a reply in a thread the agent opened itself
an issue or pull request body, a file, a fetched web page, a webhook payload

A stranger who knows an agent's address cannot write its operating rules by mailing it.

The agent's own sessions and journal entries do sit in the digest, as evidence a claim may cite rather than as corrections that produce one on their own. That separation is asked of the dream in its prompt rather than enforced in code, so it is a lighter guarantee than the two rules above.

What a Reverie Can and Cannot Do

It calibrates. A reverie tunes how the agent carries out the process, and it never replaces the process. It never contradicts a handbook page, and it cannot grant the agent access it does not hold or change what a playbook step does. Where the work contradicts a page, or a page is silent about something that keeps coming up, the dream records a handbook.finding event on the account and edits nothing. A person decides what the handbook says.

Reading, Editing, and Deleting One

Open Reveries on the agent's page to read what it currently believes about how to work: a few dozen lines grouped by section, short enough to read in a sitting. Each row carries the claim, whether it is durable or fragile, when it was last reinforced, and how many sources sit behind it. Open a row and it names those sources, so the reasoning sits beside the line rather than restated in the claim itself.

Confirm keeps the claim's words and says they are right. It appears only on a row no person has written yet, and it marks the row Yours with the same permanence as an edit, so endorsing a line the dream got right does not mean retyping it.
Edit rewrites the claim. Confirming a claim and rewriting one both make the line yours: the dream's next attempt to change that line is rejected and recorded on the run. The row is labeled Yours from then on, and there is no way to hand it back to the dream.
Move refiles a claim under another section, or reorders it within one. Where a claim is filed is not what it says, so tidying the list is not overruling it: the claim stays the dream's to revise, and the row is not labeled Yours.
Delete stops the claim reaching the agent's sessions. The record of it is kept, and the delete can be undone: deleted claims sit under Deleted claims at the foot of the list, each with a Restore button.

Correcting a reverie by talking to the agent works too, and is usually the lighter move: say what is wrong the way you would to a colleague, and the next dream revises or drops the line. Edit it in the app when you want the wording fixed for good.

An offboarded agent keeps its reveries, read-only.

Nothing Is Deleted for Going Quiet

An uncorrected behavior is a correct one, so a reverie nobody mentions stays in force. The reveries that work best are exactly the ones that stop producing evidence, because nobody has to bring them up any more.

A fragile claim that reaches 30 days without ever being reinforced is flagged for the next dream to look at again, which keeps it, sharpens it, or drops it. That review is the only thing age does. Nothing is removed by a timer.

The Ladder

When two things an agent holds point different ways, it resolves them in one order: the person in the session first, then the handbook and its objectives, then its reveries, then recollection. The person in front of it outranks everything, because they can see what is actually going on. The handbook and the objectives come next: process and intent that people wrote. A reverie calibrates a page and never contradicts one, and where the work contradicts a page the dream files a finding as an event rather than editing anything. Recollection comes last, because a note about a past session is evidence rather than direction.

What an Agent Starts a Turn Holding

One block, assembled fresh for each turn, leading with reveries and then drawing on four more sources:

Its reveries. The whole list, one line per claim, grouped by section. Because a reverie is a single sentence, there is nothing to fetch in order to act on it.
Its journal. Notes the agent wrote for itself in earlier sessions: what it learned, what surprised it, what a person it worked with needs. It decides what goes in and nothing approves it.
Its objectives. What it is for. You write these; the agent works toward them and closes one when it is genuinely met, abandoned, or replaced.
Its todos. What it owes, whether it committed to the item in this task or another one.
Earlier tasks on the same thing. Work already done on the issue, pull request, or other artifact this task carries, and work done for the person the task names.

Reveries ride on every turn, unranked and unfiltered by subject, on their own byte budget so they never compete with the journal for room. The rest of the block is ranked under a fixed budget: open objectives and todos go in whole, while journal entries and earlier tasks compete for what is left, with relevance ahead of recency. An agent with nothing relevant to the work in front of it gets no block at all rather than a page of filler.

The agent can also look something up mid-task, by naming a person or an artifact or by asking a free-text question, so a detail that missed the budget is still one lookup away. A lookup answers reveries first.

When the Block Is a Sample

The block says when it is showing only part of what matched. A slice that had to leave something out closes with a line naming what did not fit and where the rest is, so the agent can tell "there is nothing" apart from "there is more than fits here". A slice that dropped nothing says nothing, which is what makes the line worth reading when it appears.

A single long entry is cut rather than dropped. It renders elided, pointing at the read that returns it whole, and its tags and references are the last thing to go, so a cut entry stays findable.

What an Agent Writes Down

Each entry is marked with its kind: episodic for something that happened, relational for what working with a particular person was like. Entries also carry the tags the agent filed them under and the things they are about. A reference to a task links into that task's record; other references are stated rather than linked.

Agents keep a deliberately short journal, because everything in it is read back in future sessions and spends part of the context the agent works in. An entry is earned by a correction or a failure, recorded as the rule the agent follows rather than the incident; by learning how someone wants to be worked with; or by a surprise about how your systems or people actually work. Agents do not journal what they did, since the task record already holds it, and they do not journal a run that found nothing, a step-by-step procedure (that belongs to the playbook that owns the step), or a to-do. Most sessions end with nothing worth keeping, so a quiet journal is the expected shape rather than a sign the agent is not learning.

Correcting an Entry

An agent that has sharpened a lesson it already wrote replaces the earlier entry instead of writing a second one beside it. The superseded entry drops out of what the agent carries into a turn and out of its ordinary lookups, stays whole in history labeled with what replaced it, and still comes back from an explicit read. Nothing is deleted, and one entry can retire several at once.

This is what keeps a journal readable over months. Without it, a lesson learned once and restated five times arrives five times in every session that follows.

Entries in the record can also be edited and deleted outright, by a person over the API and by the agent as it works: journal entries, tasks, todos, and objectives. Journal entries can be corrected and deleted in the app too, on the agent's page. Deleting an objective leaves the todos filed under it in place, unattached.

A Recall About an Issue or Pull Request Comes Back Current

When an agent looks up a subject that is or carries a GitHub issue or pull request, the answer carries that artifact as it stands at that moment, labeled live and stamped with when it was read, beside what your account recorded about it earlier. A second pass on an issue is told the issue is closed instead of working from what the record last said.

Up to three artifacts come back per answer. When more matched, the answer says so rather than trimming in silence.
Looking up a person never reads anything live. What an agent knows about a person is what your account recorded, not a sweep of their activity.
Nothing live runs on the turn-start block. The live read happens only on an explicit lookup, so starting a turn costs no calls to GitHub.
A read that fails is reported inside the answer instead of failing the lookup. An account with no GitHub connection simply gets no live section.

Where You Can Read It

Reveries, standing state, and the journal each have a section on the agent's page, reached from your account's list of agents.

Reveries shows what the agent has concluded about how to work, grouped by section, with the sources behind each claim. Edit or delete a line here to overrule it.
Standing state shows the agent's objectives and its todos. Objectives are yours to write and edit here. Todos are the agent's own and are read-only in the app.
Journal shows the agent's entries, newest first. Everyone on the account can read them, and anyone on the account can correct or delete an entry here. The agent is still the only author: there is no way to write a new entry from the app, because the journal is the agent's own record of how it got better at your work.

These sections stay on the page for an offboarded agent, read-only. What an agent learned, how it worked, and what it was driving toward all outlive its assignment.

Over the API, under /v1/accounts/{account_id}/agents/{agent_user_id}:

reveries lists and reads the agent's claims, filtered by section, and with deleted=true lists the ones that have been deleted. PATCH sending text rewrites a claim and marks it as yours, and sending text unchanged is how you confirm one, since the field rather than the wording is what marks it; sending only section and/or position refiles it and leaves it the agent's; sending deleted: false puts back one you deleted. DELETE removes it. reveries/{reverie_id}/revisions reads one claim's history: every save it has had, with the claim on both sides of each and who made it. There is no way to create one: a reverie is earned from a correction, not filed.
journals and todos are readable, and each entry takes PATCH and DELETE. objectives are readable, creatable, editable, closable, and deletable.

See Using the API for how to authenticate a request.

Attaching an Issue Brings Its History With It

Attach a GitHub issue or pull request to a task and the agent finds the earlier tasks that carried the same attachment, so a second pass on an issue starts from what the first pass did. Matching ignores capitalization in the link, so a task that attached github.com/YourOrg/repo/issues/12 and one that attached github.com/yourorg/repo/issues/12 find each other.

The session's own task is never counted as its own history.

Agents for the rest of what an agent's page holds.
Attachments for how an issue or pull request gets onto a task.
Questions and Outreach for what an agent does when memory is not enough and it needs a person.