Envelope

Team memory

Every team has memory. It requires no configuration, no declaration in your team definition, and no UI to set up — it is on from the moment a team is installed.

What it is

Team memory is a persistent document store scoped to each install. Agents can write structured rows to it during a run and read those rows at the start of the next run. Memory accumulates across every run and persists indefinitely.

The primary use case: agents that run repeatedly over time can stop rediscovering the same information on every run. A research agent can log what sources it has already processed. A support agent can track ticket state across sessions. A competitor monitor can log what changes it has already reported so it only surfaces genuinely new ones.

How it works

On every agent run, three tools are injected automatically:

| Tool | What it does | |---|---| | document_write | Creates a new document (if none exists with that name) and appends rows to it | | document_read | Reads current rows from a named document, optionally filtered by status | | document_update | Updates specific rows in a document — used primarily to mark rows complete |

At run start, any documents with non-complete rows are injected into each agent's context as a <team_memory> block. Agents read this before doing any work.

When an agent calls document_update with status: "complete", that row is retired from future context injections. This is the primary mechanism for keeping memory lean — agents decide when a row has served its purpose.

Zero configuration

Nothing goes in your team definition for memory. No workspace block, no column declarations, no status values. The agent defines its own structure on the fly via document_write.

The simplest write call looks like:

{
  "tool": "document_write",
  "document": "source-log",
  "columns": ["url", "topic", "quality", "status"],
  "rows": [
    { "url": "arxiv.org/abs/2405.1234", "topic": "inference cost", "quality": "high", "status": "used" }
  ]
}

On the next run, that row appears in the <team_memory> block and the agent can skip reprocessing that URL.

Writing agent prompts that use memory

Memory is active on every install, but agents only use it if their prompts instruct them to. The tools are available automatically — the only missing piece is the instruction.

A good memory instruction in an agent prompt has three parts:

1. Read at the start. Tell the agent to check <team_memory> before doing any work and factor it in.

2. Write what should persist. Tell the agent what to record, what schema to use, and when to write (typically at the end of a run or when an action completes).

3. Retire what's done. Tell the agent when to call document_update with status: "complete" — this is what keeps the context from growing indefinitely.

Example for a research agent:

At the start of each run, read <team_memory>. If a source-log document exists,
skip any URLs that appear in it — do not reprocess sources you have already used.

After processing new sources, call document_write to add them to the source-log
document with columns: url, topic, quality, status. Set status to "used".

If a source was tried but produced nothing useful, write it with status "low-quality"
so future runs also skip it.

Example for a support agent tracking ticket state across sessions:

At the start of each run, read <team_memory>. If a ticket-state document exists,
use it to understand which tickets are already being handled and by which agent.

When you pick up a new ticket, write a row to ticket-state with columns:
ticket_id, customer, issue_summary, owner_agent, status. Set status to "active".

When a ticket is fully resolved, call document_update to set its status to "complete".
Completed tickets will not appear in future context.

You can update an agent's prompt from the workspace room thread by asking — the team assistant will propose specific schema and prompt wording that fits the team's purpose.

Asking about memory in the room thread

The workspace room thread has full visibility into what's stored in memory. You can ask:

  • "Do you have memory?" — confirms whether memory is active and whether agents are using it
  • "What's in memory?" — shows the current documents and rows in plain language
  • "What has the agent stored?" — same, phrased differently
  • "Add memory to my agents" — the assistant will propose a specific schema and prompt update based on what your team does, then apply it inline

If the team hasn't been updated to use memory, the assistant will tell you clearly: memory is on, but the agent prompts don't instruct agents to use the tools yet. It will offer to fix that.

Keeping memory lean

Memory is injected at run start up to a 12k character limit. A small number of rows per document is fine indefinitely. If a team accumulates many rows over many runs without retiring any, context can grow large.

Two practices prevent this:

Mark rows complete. When an agent finishes with a row — the ticket is resolved, the source has been cited, the change has been reported — it should call document_update with status: "complete". Completed rows are not injected into future runs.

Use meaningful status values. A row with status: "used" is just context. A row with status: "reported" signals a specific state. Agents can read selectively with document_read filtered by status, which reduces noise.

Multiple documents per install

An agent can write to multiple named documents. Use separate documents when the data has different structures or different lifecycles:

document_write("source-log", ...)      // URLs processed
document_write("decision-log", ...)    // editorial decisions made
document_write("open-questions", ...)  // unresolved threads to revisit

Each document is injected independently into the <team_memory> block. The limit applies across all documents combined.

Memory vs. workspace documents

These are different features with different purposes.

| | Team memory | Workspace documents | |---|---|---| | Declared in team definition | No — automatic | Yes — workspace[] block | | Schema | Agent-defined on the fly | Declared columns with types and ownership | | Human-facing | No — agent context only | Yes — visible in the Doc panel | | Human writes to it | No | Yes — direct cell editing | | Condition triggers | No | Yes — triggers on row status | | Best for | Agent-to-agent state across runs | Human+agent collaboration on a shared list |

Use workspace documents when humans and agents share a work queue. Use team memory when agents need to accumulate context that the operator doesn't need to see or edit.

Workspace documents guide →

‹ All guidesDocs ›