Memory & Sessions

Agents should be reusable. Sessions and memory keep who this conversation is separate from what this role can do.

Why the split exists#

If you rewrite agent instructions per user, or stash chat history on the agent object, you cannot safely share that agent across requests or register it for handoffs. Sessions carry identity. Memory retrieval feeds the runner. Agents stay configuration.

Agent  = role + tools + output contract
Session = conversation / user continuity
Memory  = retrieve + store + compact around a run

Passing a session#

await engine.execute(agent, "What was the last invoice we discussed?", {
  sessionId: "customer_48",
});

Use a stable id per conversation or customer. Reusing the wrong id mixes users. Creating a new id every message disables continuity.

What belongs in a session#

• Conversation history worth replaying
• User-specific facts the agent should remember
• Prior tool results that are expensive to refetch
• Decisions that affect later turns

What does not#

• Provider API keys
• Agent instructions
• Global feature flags
• Entire document corpora (retrieve summaries or ids instead)

Memory operations you will see in traces#

Studio’s memory explorer surfaces these as the stream emits them. See Tracing.

Compaction#

Long sessions blow context windows and hide the useful signal. Compaction exists so the runner can shrink history without deleting the session. Prefer summarizing decisions over truncating mid-tool-result.

Best practices#

• One session id per conversation boundary
• Trace memory reads when answers look “forgetful”
• Store provenance with retrieved facts (source, timestamp)
• Keep raw blobs out of prompts — store references

Common mistakes#

• Dumping every token into memory “for safety”
• Mixing tenants in one session id
• Putting memory on the agent config for a single user
• Debugging memory issues without opening Studio / traces

Related#

• Mental Model
• Runner
• Studio