Memories

Agents get better at recurring work by remembering what happened last time, and a memory is where that learning lives. This chapter is about the knowledge an agent works with: what it remembers, what it produces, and how all of it links together. Memory comes first because it is the most personal piece — a single agent's running notes, scoped to one workspace, that it carries into every task it picks up.

An agent's memory is one bounded markdown list

A memory is a single markdown list owned by one agent inside one workspace. There is exactly one per agent: not a file tree, not a vector store, just a short list of durable notes the agent keeps about the work it does. It holds the things that make the next task faster or safer — the example that was accepted as the standard, the draft that was rejected and why, the reviewer's approval conditions, the checklist that has to pass before a job is done, the failure mode that keeps recurring.

Keeping memory to one bounded list is deliberate. The point is reusable knowledge, not a transcript, so an agent spends its entries on facts that stay true across tasks and prunes the rest. Memory is not where secrets live and not where one-off task chatter belongs; that distinction is what keeps the list worth reading.

Memory is injected into the agent's context by default

Every time an agent picks up a job, its memory is rendered into the instructions it runs with, so it does not have to rediscover what it already learned. Alongside the saved notes, Task Machine includes static guidance on which kinds of notes are worth keeping — canonical and rejected examples, standards, checklists, playbooks, known failure modes — so the agent maintains its list well rather than filling it with noise. Reading memory this way marks when the agent last leaned on it, which gives anyone governing the agent a sense of how live that memory still is.

Because memory is reused on every task, it is the natural home for the standards and decisions you reach with an agent over time. As you correct an agent in review and it records why, the next run starts from that correction instead of repeating the mistake.

Memory is the agent's own running notes, but it is not the only context a job starts with. When an agent picks up work, Task Machine also pulls in the documents and artifacts most relevant to that job — ranked against the task or trigger text and filtered to what the agent is allowed to see and to the project the work belongs to — so the agent reads from the workspace's knowledge as well as its own. Where memory is what the agent learned, this relevant-knowledge context is what the workspace already knows, and the two arrive together. The connected body that retrieval draws from is covered in Artifacts and References.

The list stays within a limit so it stays useful

A memory cannot grow without bound. Each agent has an entry limit set on its agent profile, and every entry has a per-entry character cap. When a write would push the list past its entry limit or make a single entry too long, Task Machine rejects the write and tells the agent what overflowed, so it deletes, merges, or rewrites entries instead of silently dropping knowledge. A new agent uses a sensible default limit until you tune it. The limit is what forces the list to stay a curated set of durable notes rather than an ever-growing log.

So you are not surprised when an agent hits that wall mid-task, the memory surfaces how full it is before the agent must overwrite anything. The entry count carries a hygiene indicator: it reads normally with room to spare, turns to a warning with an alert icon as the list nears its limit, and reads as full when there is no room left. Both the memory list and a memory's detail show the state, with a line telling you to prune or edit entries before the agent is forced to overwrite weaker notes. The indicator is the cue to tidy a memory on your terms rather than leave the agent to drop something useful when the next write overflows.

When a list does get cluttered, you do not have to prune it by hand. A tidy memory action asks the agent's model to propose a consolidated version — duplicates merged, contradictions resolved in favour of the most recent note, stale one-offs dropped — and presents it for review as what it would add, remove, and keep. Nothing changes until you accept: accepting saves the consolidation as the new version, and discarding leaves the current memory untouched. The proposal is produced by a managed model, so it does not need the agent's own runtime, and because it is only ever a suggestion a person approves, memory edits stay human-in-the-loop. An agent can ask for the same tidy-up from the machine it runs on with tama memory tidy, but the version it proposes still waits for a human to accept or discard it.

Writes are versioned the same way documents and artifacts are: the list itself is a stable record, and each saved version is kept immutably with the membership that wrote it, so the history of an agent's learning can be read back and restored. A consolidation is just another version — proposed, then accepted by a person — so a tidy-up never loses the trail of what the agent knew before.

Who can read and change a memory

A memory belongs to its agent, and the agent can read, rewrite, and clear its own list as it works. People reach an agent's memory through workspace governance: a member with permission to read agents can see what an agent remembers, and a member with permission to manage agents can edit or clear it. This is how you audit or correct an agent's accumulated knowledge without being the agent.

From the machine where an agent runs, the tama CLI exposes the same operations for inspection and repair — tama memory show, tama memory write, tama memory tidy, and tama memory clear, each addressed to a specific agent. The full command set is in the CLI command reference.

From here, memory is what an agent keeps for itself; the next surface is what it produces for everyone else. See Artifacts for the versioned records agents and workflows create as they work.