Conversation History

#Overview

By default, Agent is stateless — each run() call starts a fresh context. ConversationHistory adds persistent multi-turn memory by carrying prior messages into each new call.

python

import asyncio
from daita import Agent, ConversationHistory
 
async def main():
    agent = Agent(name="assistant", llm_provider="openai", model="gpt-4o")
    history = ConversationHistory()           # session_id auto-generated as UUID
 
    await agent.run("My name is Alice.", history=history)
    response = await agent.run("What's my name?", history=history)
    print(response)        # "Your name is Alice."
    print(history.session_id)  # "3f2a1b4c-..." — store this to resume later
 
asyncio.run(main())

The agent stays stateless. State lives in ConversationHistory, not on the agent — the same agent instance can serve many sessions simultaneously.

#Configuration

python

history = ConversationHistory(
    session_id="alice",          # Optional — auto-generated UUID if omitted
    workspace="support_bot",     # Storage namespace (defaults to agent name)
    max_turns=20,                # Keep only the last 20 user+assistant pairs
    max_tokens=50_000,           # Drop oldest turns when token budget is exceeded
    auto_save=True,              # Persist to disk after every turn
    scope="project",             # "project" (default) or "global"
)

Parameter	Default	Description
`session_id`	auto UUID	Unique identifier for this conversation; auto-generated if not provided
`workspace`	agent name	Storage namespace; auto-derived from agent on first `run()`
`max_turns`	`None`	Sliding window — keeps the last N complete turns
`max_tokens`	`None`	Token budget; oldest turns are dropped when exceeded
`auto_save`	`False`	Save to disk automatically after each turn
`scope`	`"project"`	`"project"` stores under the nearest `daita-project.yaml`; `"global"` under `~/.daita/`

max_turns is applied first, then max_tokens. Recommended max_tokens values: 3_000 (GPT-4 8k), 50_000 (GPT-4o 128k), 100_000 (Claude 200k).

#Persistence

#Saving

python

# First turn — let the framework generate the session ID
history = ConversationHistory(auto_save=True)
response = await agent.run("Hello!", history=history)
 
session_id = history.session_id  # persist this in your DB, cookie, or client state

Or call save() manually instead of using auto_save:

python

path = await history.save()
print(path)  # .daita/sessions/support_bot/<uuid>.json

#Loading

python

# Later request — client sends session_id back
history = await ConversationHistory.load(
    session_id=session_id,   # the ID returned from the first turn
    workspace="support_bot",
)
 
# Returns an empty history (not an error) if the session file doesn't exist yet
response = await agent.run("What did we discuss?", history=history)

Sessions are stored at .daita/sessions/{workspace}/{session_id}.json relative to your daita-project.yaml, or ~/.daita/sessions/ when scope="global".

#Properties

python

history.turn_count    # Number of complete user+assistant turns stored
history.messages      # Read-only list of message dicts
history.session_path  # Resolved file path (None if workspace not yet set)

#Clearing a Session

python

history.clear()  # Resets in memory only — does not delete the file on disk

#Next Steps

Agent — Core agent configuration and execution
Memory Plugin — Semantic long-term memory across sessions