Skip to main content
Memory in Timbal agents enables multi-turn conversations and context persistence across agent interactions. Agents automatically maintain conversation history without requiring additional configuration.

​
How Memory Works

Timbal implements memory through its tracing system, which captures conversation history during agent execution. When an agent runs, it automatically resolves memory from previous interactions to maintain conversational context.

​
Automatic Memory Resolution

During each agent execution:
  1. The agent checks for previous conversation context
  2. If found, it retrieves conversation history from the tracing data
  3. Previous messages are automatically included in the current conversation
  4. The agent processes the new input with full conversation context
This happens transparently - agents receive conversation memory without any code changes.

​
Storage Options

Memory storage depends on your deployment environment:
  • Timbal Platform: Conversation history is automatically persisted with high availability and cross-instance sharing
  • Local Development: Uses in-memory storage that’s fast but cleared on restart

​
Nested Agent Memory

When an agent is used as a tool of another agent, the child gets an isolated context — it does not inherit the parent’s conversation history. The parent only sees what the child returns as its tool result. That keeps specialist agents focused and prevents parent history from bloating every nested call.
To hand the child specific context, put it in the tool call (the parent’s prompt / args). To share state across turns of the parent, use the parent’s own memory via parent_id session chaining — see Rewind and Tracing.

​
Configuration

Memory is automatically configured based on your deployment:
  • Platform Deployment: No configuration needed
  • Self-Hosted: Uses in-memory storage by default, with platform integration available
Memory works automatically. For deeper understanding of the underlying mechanisms, see Tracing and Context.

​
Rewind

Timbal supports conversation branching, allowing you to rewind to any previous point and explore alternative conversation paths.

​
How Branching Works

Each agent interaction creates a unique run with its own context. You can branch from any previous run by referencing its run_id, creating independent conversation paths that diverge from that point.
This creates branching conversations:

​
Common Use Cases

  • A/B Testing: Compare different conversation strategies
  • Error Recovery: Return to a state before an error occurred
  • Debugging: Isolate specific conversation states for testing
  • Exploration: Test “what if” scenarios without affecting the main conversation
Each branch maintains independent memory from the branching point. Learn more about the underlying mechanisms in Context.

​
Keeping memory within the context window

For long-running conversations, memory can grow large enough to exceed the model’s context window. Timbal has two complementary layers:
  1. Tool result offloading — oversized tool results are spilled to a store when produced, so they never dominate every later LLM call. Lossless; the model pages content back via read_tool_result.
  2. Memory compaction — strategies (keep last N turns, shrink old tool results, LLM summarize) that fire when context utilization crosses memory_compaction_ratio (default 75%).
Most long-running agents want both: offloading prevents the bloat at the source; compaction handles everything else. See Memory Compaction for the full reference.