Skip to content

A save of an organisation's, a team's or a profile's memory reaches the sessions already running in its scope at their next turn, on a pod because the plane tells the pod and on a laptop through the daemon's signed poll of me.memory every five minutes, with a line saying what changed and to which version; a child profile reads its chain's memory, the one that extends nothing first; a deleted profile's memory is deleted with it; the desktop app lists every instruction layer; troupe config pull fetches memory; and signing out drops memory.json

Decision 929 · accepted · 2026-10-23 · issue #55

A save reaches a running session at its next turn

One holder per session. Troupe.Session.PlaneMemory is a small process in the session's tree, under the log and above the agent, as Session.ClientTools is, so what it holds outlives an agent's restart. Its registry entry carries the documents the session was last given; put/2 replaces them, given/1 reads them without asking the process. Nothing else of the session's configuration moves: memory is the one part a save on the plane changes while the session runs.

Taken as a turn begins, never during one. Each agent compares the documents it read with what the session was given as its turn begins (take_memory, before the instruction files are read), by scope, name, version and hash. Where they differ it takes the new ones into its configuration, writes memory_changed with each change's versions from and to (Troupe.PlaneMemory.changes/2) and the sentence a client shows (The organisation's memory changed: the team design's memory is now version 6 (it was 5). Read from this turn on.), and the turn's instructions are read with them. So a turn's system prompt is the same on every call of it (Decision 798's hold), and the same versions given again say nothing. A subagent takes them at its own next turn; one started after has them from its parent's configuration, or takes them at its first turn where its parent had not yet.

What the session explains moves with it. Troupe.Session.resolved/1 lays the given documents over the layers the session started with, so config.get naming the session, troupe config --explain --session and context.get name the versions its next turn reads. That narrows Decision 918's "what it started with" for memory alone, and is why Decision 922's objection to reading the copy at every turn (a running session's instructions moving without config --explain saying so) no longer holds: the move is given, logged and explained, not read from a file behind the session's back.

On a pod, the plane tells the pod. A save (admin.memory.put that makes a version) calls Troupe.Plane.Memory.announce/1: every active team session with a pod in the document's scope (the organisation's: all; a team's: that team's; a profile's: that profile's and every profile that extends it, Extends.descendants/1) is sent session.memory, a notification to its pod with the session's id, its epoch and every document the session now reads (for_session/2). A notification, as a bundle's announcement is: a save never waits on the slowest pod, and a pod that missed it has the documents with the session's next activation, which carries them anyway. The worker takes it only for a session up there at the plane's epoch (running_at, as session.input), and refuses one it is not running. A session.activate for a session already up gives it the activation's documents the same way, so a re-activation is not a way for them to go stale.

On a laptop, a signed poll. The daemon dials the plane and nothing dials the daemon, so a push would need a standing connection the daemon has only while a session is offered (Decision 921). Instead Troupe.Gateway.Memory asks me.memory every five minutes while the daemon holds a plane token, besides at every identity.link that brings one (as before) and when a client hands it an answer (config.memory). The answer is checked against the key this machine pinned for the plane and kept as Decision 922 keeps it; a copy whose documents changed is given to every session running on the daemon, then announced as config.changed with scope memory and the changed documents as its keys, in that order, so a client that heard it and sends a turn finds the session already holds them. A copy that changed nothing says nothing. Five minutes: a save is an administrator's edit, rare and not urgent to the second, and one call of a few kilobytes per signed-in machine every five minutes costs the plane little. Not chosen: riding the relay connection, which exists only while a session is offered and would make memory depend on steering.

troupe config pull fetches memory

troupe config pull asks me.memory beside me.client_defaults and hands the answer, signature and all, to the daemon's new config.memory, which keeps it through the same writer. The command says which documents this machine now reads, each with its version, and that the sessions running here read it from their next turn when one changed. A plane from before memory gives none, and the pull is not a failure for it.

A child profile reads its chain's memory

As a profile's rules and bundle are composed from its chain (Decisions 908, 910 and 913), a session reads the memory of every profile in its chain, the one that extends nothing first and its own last (Memory.chain/1, from Extends.chain/1), after the organisation's and its team's. Nearer comes later and wins, as everywhere else in the instructions. Each is named as its own profile's (memory:profile/<name>), so the provenance says which profile wrote what. A chain that cannot be read (a profile in it gone) is the profile alone, as its rules are then. A save of a parent's document reaches the running sessions of every profile below it. The console's profile page shows, above the profile's own editor, each document it inherits, with the profile it is from, the version in force, who saved it and when, and where it is changed (admin.memory.get's inherited).

A deleted profile's memory goes with it

Fleet.delete_profile/1, the one place a profile row is deleted (an administrator's profile.delete, or a GitOps profile gone from the cluster), deletes the profile's memory documents, every version, in the same transaction (Memory.forget/1), so a profile made again under the name starts with none. The text is not kept for the audit: the audit never held it (Decision 922's memory.put rows name the version, size and hash, and who and when), and those rows stay, so the trail still says who saved what version of the deleted profile's memory and when; what the document said goes with the profile. Keeping the versions under the name was what made a new profile inherit an old one's words; keeping them under some other key would be a second store nobody reads. A team's needs nothing: its documents are keyed by the team's id, which a team made again does not share.

memory.json is dropped on sign-out

identity.sign_out for the plane the copy came from, and identity.unlink, delete memory.json whether or not the daemon held a token (one restarted since the sign-in holds none), give the sessions running here an empty list, which they read from their next turn, and announce it. The organisation's words are for its signed-in members; a machine whose person signed out is no longer one. The key pinned for the plane stays: it is trust in the plane, not the organisation's content, and the next sign-in is checked against it. organisation.json is left as it is: it holds defaults and limits, not words for agents, and dropping it is a different question.

Governs: apps/troupe_core/lib/troupe/session/plane_memory.ex, apps/troupe_core/lib/troupe/plane_memory.ex, apps/troupe_gateway/lib/troupe/gateway/memory.ex, apps/troupe_plane/lib/troupe/plane/memory.ex