How to beginner · 3 min read

How to persist agent state across sessions

Quick answer

To persist agent state across sessions, save the agent's memory or context data to external storage like a file or database after each interaction. Reload this saved state when restarting the agent to maintain continuity using serialization formats such as JSON or pickle.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the openai Python SDK and set your API key as an environment variable.

Install SDK: pip install openai
Set environment variable in your shell:
export OPENAI_API_KEY='your_api_key'

bash

pip install openai

output

Collecting openai
  Downloading openai-1.x.x-py3-none-any.whl (xx kB)
Installing collected packages: openai
Successfully installed openai-1.x.x

Step by step

This example demonstrates saving and loading an agent's conversation memory to a JSON file to persist state across sessions.

python

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# File to store agent memory
MEMORY_FILE = "agent_memory.json"

# Load memory from file if exists
if os.path.exists(MEMORY_FILE):
    with open(MEMORY_FILE, "r") as f:
        memory = json.load(f)
else:
    memory = []  # start with empty conversation history

# Append new user message
user_message = {"role": "user", "content": "Hello, how are you?"}
memory.append(user_message)

# Call chat completion with full memory to maintain context
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=memory
)

assistant_message = response.choices[0].message
memory.append({"role": assistant_message.role, "content": assistant_message.content})

print("Assistant:", assistant_message.content)

# Save updated memory back to file
with open(MEMORY_FILE, "w") as f:
    json.dump(memory, f, indent=2)

output

Assistant: I'm doing well, thank you! How can I assist you today?

Common variations

You can persist state asynchronously or use databases like SQLite or Redis instead of JSON files for scalability. Also, different SDKs or frameworks may have built-in memory management utilities.

python

import os
import json
import asyncio
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

MEMORY_FILE = "agent_memory_async.json"

async def main():
    if os.path.exists(MEMORY_FILE):
        with open(MEMORY_FILE, "r") as f:
            memory = json.load(f)
    else:
        memory = []

    memory.append({"role": "user", "content": "Hello asynchronously!"})

    response = await client.chat.completions.acreate(
        model="gpt-4o-mini",
        messages=memory
    )

    assistant_message = response.choices[0].message
    memory.append({"role": assistant_message.role, "content": assistant_message.content})

    print("Assistant:", assistant_message.content)

    with open(MEMORY_FILE, "w") as f:
        json.dump(memory, f, indent=2)

asyncio.run(main())

output

Assistant: Hello asynchronously! How can I help you today?

Troubleshooting

Memory file not found: Ensure the file path is correct and writable.
Corrupted JSON: If loading fails, delete or fix the JSON file to avoid parse errors.
Context too long: Trim or summarize memory to fit model token limits.

✅

Key Takeaways

Persist agent state by saving conversation history externally after each interaction.
Reload saved memory on startup to maintain context across sessions.
Use JSON files for simple persistence or databases for scalable solutions.
Trim memory to respect model token limits and avoid errors.
Async SDK calls support the same persistence patterns for concurrency.

Verified 2026-04 · gpt-4o-mini

Verify ↗