Memory

Memory enables multi-turn conversations by loading history from a previous run’s trace. Sequential calls in the same task can chain automatically. Across HTTP requests, processes, or explicitly separate tasks, pass parent_id to continue the intended conversation and use a tracing provider that can retrieve that prior run.

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:

The agent checks for previous conversation context
If found, it retrieves conversation history from the tracing data
Previous messages are automatically included in the current conversation
The agent processes the new input with full conversation context

When the run is linked to a prior run, history resolution happens automatically. An unrelated request does not acquire a conversation merely because it invokes the same Agent object.

Storage Options

Memory storage depends on your deployment environment:

Platform tracing: Stores runs remotely so an authorized continuation can retrieve them across processes.
In-memory tracing: The local default; history disappears on process restart.
JSONL or SQLite tracing: Local persistence options for applications that configure them.

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.

from timbal import Agent

billing_agent = Agent(
    name="billing_agent",
    model="anthropic/claude-haiku-4-5",
    max_tokens=4096,
    # Fresh context per call — only the tool prompt from the parent, not the full chat
)

support_agent = Agent(
    name="support_agent",
    model="anthropic/claude-sonnet-4-6",
    max_tokens=4096,
    tools=[billing_agent],  # add more specialist agents as needed
)

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

Configure the tracing provider for your deployment and keep run IDs with the conversation. The server also supports explicit continuation:

from timbal import Agent

agent = Agent(name="example", model="openai/gpt-4o-mini")

first = await agent(prompt="My name is David").collect()
second = await agent(parent_id=first.run_id, prompt="What's my name?").collect()

Run IDs identify continuation points; the host must authorize access to the conversation before accepting a client-supplied parent_id. See Tracing and Context for storage and context behavior.

Interrupted turns

A turn can end early: a voice barge-in cancels it, a timeout expires, or it fails. The next turn continues from what that turn reached:

Cut after the agent assembled its memory (while the model was running, or mid-reply): the earlier turns, the interrupted prompt, and the part of the reply that was produced. Voice sessions trim that reply to what the caller actually heard.
Cut before (while resolving the system prompt or loading the previous turn): the turn stores no memory. The next turn rebuilds it from the turn before plus the interrupted prompt, so it sees the same conversation as if the turn had been cut a moment later. Up to 8 consecutive turns like that are followed back.

This holds on every built-in provider, with or without the platform trace cache. Rebuilding relies on the provider returning the run a trace continued from (Trace.parent_id); a custom provider that does not set it continues from the interrupted prompt alone. When the run a turn continues from cannot be loaded at all (never stored, deleted, or unreachable), the turn continues without that conversation. It logs an error and counts memory:parent_missing in the run’s usage, so lost conversations can be monitored.

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.

from timbal import Agent
from timbal.state import RunContext, set_run_context

agent = Agent(name="example", model="openai/gpt-4o-mini")

# Main conversation
step1 = await agent(prompt="Hello").collect()
step2 = await agent(prompt="My name is David").collect() 
step3 = await agent(prompt="What's my name?").collect()
# Output: "Your name is David"

# Branch from step 1 (before name was shared)
context = RunContext(parent_id=step1.run_id)
set_run_context(context)

branch = await agent(prompt="What's my name?").collect()
# Output: "I don't know your name"

This creates branching conversations:

"Hello"
├── "My name is David" → "What's my name?" → "David"
└── "What's my name?" → "I don't know"

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:

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_offloaded.
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.

Getting started

Core Concepts

Agents

Voice Agents

Workflows

Human in the Loop

Evals

Deployment

How Memory Works

Automatic Memory Resolution

Storage Options

Nested Agent Memory

Configuration

Interrupted turns

Rewind

How Branching Works

Common Use Cases

Keeping memory within the context window

​How Memory Works

​Automatic Memory Resolution

​Storage Options

​Nested Agent Memory

​Configuration

​Interrupted turns

​Rewind

​How Branching Works

​Common Use Cases

​Keeping memory within the context window

How Memory Works

Automatic Memory Resolution

Storage Options

Nested Agent Memory

Configuration

Interrupted turns

Rewind

How Branching Works

Common Use Cases

Keeping memory within the context window