Memory¶
Memory is what an agent starts from before you say anything: what your organisation wrote for every agent, what you keep for yourself, and what earlier agents learned about the repository. Each is read into every session it applies to, at its next turn after a change.
The levels¶
Signed in to a Troupe plane, a session reads these, in this order. Where two disagree the later one wins, so the narrower comes later:
- The organisation's, every session's.
- A team's, that team's sessions and its members' machines.
- A worker profile's, the sessions on that profile's pods, the profiles it extends first.
- Your own, every session you run, on every machine and on the plane's pods.
- The repository's: its instruction files and the project brief
(Instruction files and onboarding), and your own
<config>/AGENTS.mdjust before them.
The first three are your organisation's word. An administrator writes them in the console (Memory, or the profile's page), and a session reads them as instructions that apply as written. Your own comes after them: it is how you like to work. The organisation's instructions still come first, except on a topic you wrote about yourself (below).
Entries and topics¶
Each document is Markdown, and each ## Topic section of it is one entry: the heading
is its topic, the lines under it are what it says. Text before the first heading is the
entry called General. Topics are compared by their words, so ## Tone, ## tone and
## TONE are one topic.
On a topic, the closest level wins. Where two levels both have an entry on a topic, a
session reads only the closer one's, which says in one line what it replaces: your own over
a worker profile's, a profile's over a team's, a team's over your organisation's. So if your
organisation's memory has ## Tone and so does yours, your sessions follow yours on tone,
and your organisation's tone section is not in their prompt at all. Topics only one level
has are read as they are, the organisation's first. General is no topic: it is never
replaced. Two teams of yours on the same topic both stay, on your own machine, which reads
all of your teams'.
instructions_loaded says which sections a turn left out and whose replaced them (each
document's replaced), and the desktop app's In effect for you lists, for one of your
teams, the winner on each topic with what it replaces struck through.
Forgetting an entry removes its section and saves the document as a new version: new sessions stop starting with it, and the sessions already running keep it until they next sleep and wake, or until their next turn reads the new version. Nothing is soft-deleted: the old version keeps the text, as every version does, and a rollback brings it back.
Used in n sessions, beside an entry, counts the sessions whose last turn read a version of the document that held it since it came in. It is approximate: the plane keeps one row per session, the version its last turn read (and a week of a machine's), so a session whose turns all came before the entry, or one silent for a week, is not counted.
Each document on the plane holds at most 8192 bytes, about two thousand tokens. Each save is a new version, kept with who saved it; the audit records each save's version, size and hash, never its text.
Your own memory¶
Your own memory is one document on the plane that follows you between machines. The plane's platform administrators may read it, in the console's Memory, and each time one does the audit trail records who read it and which version; a team admin cannot, and no administrator can change it. It is kept under your account, so it stays yours when the identity provider renames you, and it is deleted, every version, when you are removed.
You change it in three places, each saving over the version you started from, so a save made elsewhere meanwhile is said rather than overwritten:
troupe memoryprints it;troupe memory --editopens it in your editor (VISUAL, thenEDITOR) and saves what you leave there;troupe memory --clearempties it. Inside the terminal client,/memoryis the same page as the desktop app's Memory, entry by entry (below).- The desktop app: Memory in the rail (below), read from the plane the app is signed in to, or through this computer's daemon and its sign-in when the app is not. A session's Instructions pane lists it as Your memory and opens Memory for it.
- The console, under Your own on Memory: a change is previewed line by line before it is saved.
A save reaches the sessions running on the machine that saved it, and on the plane's pods, at their next turn, with a line saying your memory changed; your other machines read it within five minutes.
In the desktop app, Memory reads each level as entries, as the plane answers them
(above), each with who last changed it, when, and in how many sessions it was used. In
effect for you shows what a new session in one of your teams starts knowing, as the plane
works it out (memory.in_effect): on each topic the closest level's entry, with what it
replaces struck through. Who can change which level is your role on the plane:
| You are | You can change |
|---|---|
| a member | Only you |
| a team admin | Only you, and the level of each team you administer |
| a platform admin | Only you, and Everyone at your organisation |
YOU CAN CHANGE at the top lists yours. On each of them Add a memory, Edit and Forget save the level as entries over the version you read; a topic the level has already is refused, and one a lower level has is said to be replaced for whoever the level reaches (topics compare as the plane compares them, case and spacing aside). The line under the form says where it saves to and which new sessions start with it, and on a team's or the organisation's level, as the plane previews it, how many running sessions it reaches at their next turn. A level saved elsewhere since shows your edit beside the version saved, with a reload. The other levels are marked READ, with who can change them: the organisation's its platform admins, a team's its team admins. The plane decides at every save, so a role taken away since is refused in its own words. Only you also has a Versions drawer: it lists every version, sets any two side by side, rolls back to one, shows who wrote each line, and says whether this computer's copy is current and what each session running here read. An entry an agent adds while it is open appears in it.
Signed in, the app reads and saves your memory on the plane itself, as the console does, whether or not this computer's daemon is running; where one is, the app asks it where its copy stands after each read, which has it fetch the new version for the sessions running here. Not signed in (the plane not answering, say), it all goes through the daemon, as the person it is signed in as; with no daemon either, the view says which of the two is missing. Under Local only it asks the plane nothing and says what this computer holds.
In the terminal, /memory is what every new session of yours starts knowing, entry by
entry: each ## Topic of a level's memory. In effect shows, for one of your teams (t
picks another), the closest level's entry on each topic and what it replaces: yours over
your team's, your team's over the organisation's. ◉ Everyone at your organisation, ◎
each of your teams and ○ Only you list each level's; one you cannot change here says
· read, and says who can. Enter reads an entry whole. On a level you can change (Only
you; a team's you administer; the organisation's if you are a platform admin), a adds
one, its topic typed on the page and its words in your editor (VISUAL, then EDITOR) or,
with neither set, in a box here (Ctrl-S saves); e edits one and f forgets one after a
confirm line. A topic the level has already is refused, and one a lower level has is said
to be replaced. The line under says where it saves to and, on a team's or the
organisation's, how many running sessions it reaches. A save names the version it was made
on: one saved elsewhere first is shown beside yours, and l reloads it. On Only you, h
lists the versions (Space marks one, Enter shows two side by side, r saves an old
one again), b who wrote each line, s where this machine's copy stands. A save, an
agent's entry or one from another machine is on the page when it arrives. Under Local only
every level is read from this machine's copy and nothing is changed. /memory facts is the
repository brief's facts, as before. Who last changed each entry and in how many sessions
it was used are the desktop app's.
Which version a session ran under¶
A session's log says, as each turn's instructions are read, which version of each document
the turn ran under (the instructions_loaded event's memory, each document's level, name,
version and hash), and memory_changed says when a later turn read a newer one.
A session on the plane's pods asks the plane, as each turn begins, whether it holds the versions in force, and reads the new ones first if it does not. A session on your machine reads the copy your daemon keeps, which it asks the plane for every five minutes. Each of those asks tells the plane which version each session's last turn ran under, by version and hash and never the text, so your organisation's administrators can see on Memory which running sessions are behind a save.
troupe memory --status prints which versions this machine holds, whether the plane has the
same in force (it asks, and keeps the answer), and which each session running here read at
its last turn: the place to start when a session seems not to follow what was saved.
What an agent may write¶
An agent may add to your own memory and to the repository's, and propose to your team's or the organisation's:
rememberwrites a fact about the repository by default, as it always has.rememberwithlevel: "me"adds one entry to your own memory: a sentence or two, folded onto one line, as- <entry>at the end of the section on thetopicit names (## Noteswhere it names none), making the section where you have none. It never changes or removes a word you wrote; only you do. Sections under a date, from agents before topics, stay as they were. The session's transcript shows the call and what it wrote. Ask an agent to remember something about how you work, and it may use it.rememberwithlevel: "team"orlevel: "organisation"proposes one entry, which is in nobody's memory until an administrator who may change that level accepts it; the session is told either way. The platform setting Agents may propose memory switches proposals off everywhere, and a worker profile'smemoryProposals: falsefor the sessions on its pods; either way the proposal is refused with a sentence naming which, and the agent can keep the fact in the repository or in your own memory instead.- The organisation's, a team's and a profile's memory are otherwise read-only to every agent, and a profile's has no level an agent may propose to.
When your own memory is full, remember says so and names troupe memory --edit: make room
there and ask again. With no plane signed in on this machine, remember to your own memory
is refused with a sentence, and the agent can keep the fact in the repository instead. So is
it in a session a client in Local only runs (the desktop app's switch, or local_only:
true for troupe): the daemon sends nothing of that session to the plane. The desktop app
in Local only does not edit your memory either.
Who wrote each line¶
troupe memory --blame prints your own memory a line at a time with who wrote each: the
version it came in and who saved it, or, for an agent's entry, the agent and the session it
came from. In the console, Who wrote each line under a document does the same for the
organisation's, a team's and a profile's, beside each line. It is worked out from the
versions and the audit, which keep nothing more for it: blame, not history, and the versions
list is the history.