Conversations
Give an agent memory across turns with a checkpointer and a thread_id, in memory, in SQLite, or in PostgreSQL, and purge a thread.
Keep a conversation in memory, in SQLite, or in PostgreSQL.
Attach a checkpointer when you create the agent, and pass a thread_id in each call's config. A later call on the same thread sees the earlier messages.
Prerequisites: The framework and the agent from the Quickstart. The examples reuse its lookup_order_status tool.
In memory
InMemorySaver keeps threads for the life of one process. Use it for development and tests.
from coco.agents import create_agent
from coco_graph.checkpoint.memory import InMemorySaver
memory = InMemorySaver()
agent = create_agent(
model="openai:gpt-4o",
tools=[lookup_order_status],
checkpointer=memory,
)
thread_config = {"configurable": {"thread_id": "user-thread-1"}}
agent.invoke(
{"messages": [{"role": "user", "content": "Hi, my order is ORD-101."}]},
config=thread_config,
)
result = agent.invoke(
{"messages": [{"role": "user", "content": "What order ID did I just mention?"}]},
config=thread_config,
)
print(result["messages"][-1].content)The second answer names ORD-101, because the second call read the first call's messages from the checkpointer.
In SQLite
SqliteSaver writes each step of a thread to a file, so a later process continues the conversation. It needs the sqlite extra.
from coco_graph.checkpoint.sqlite import SqliteSaver
with SqliteSaver.from_conn_string("agent_checkpoints.sqlite") as checkpointer:
agent = create_agent(
model="openai:gpt-4o",
tools=[lookup_order_status],
checkpointer=checkpointer,
)
config = {"configurable": {"thread_id": "persistent-session-1"}}
res = agent.invoke(
{"messages": [{"role": "user", "content": "Check ORD-101"}]},
config=config,
)Keep in mind: SqliteSaver is synchronous. For agent.ainvoke(), use AsyncSqliteSaver from coco_graph.checkpoint.sqlite.aio.
In PostgreSQL
PostgresSaver suits production services with several workers. It needs the postgres extra.
from coco_graph.checkpoint.postgres import PostgresSaver
DB_URI = "postgresql://postgres:postgres@localhost:5432/coco?sslmode=disable"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
# Call setup() once to initialize checkpoint tables and migrations
checkpointer.setup()
agent = create_agent(
model="openai:gpt-4o",
tools=[lookup_order_status],
checkpointer=checkpointer,
)
config = {"configurable": {"thread_id": "prod-session-100"}}
res = agent.invoke(
{"messages": [{"role": "user", "content": "Check ORD-101"}]},
config=config,
)Call setup(), or await saver.setup() for AsyncPostgresSaver, once at startup or during a deployment migration, before any graph runs. It creates and migrates checkpoint_migrations, checkpoints, checkpoint_blobs and checkpoint_writes.
Pool connections
In production, give PostgresSaver a connection pool:
from psycopg_pool import ConnectionPool
from psycopg.rows import dict_row
from coco_graph.checkpoint.postgres import PostgresSaver
pool = ConnectionPool(
conninfo=DB_URI,
max_size=20,
kwargs={"autocommit": True, "prepare_threshold": 0, "row_factory": dict_row},
)
saver = PostgresSaver(pool)
saver.setup()Delete a thread
delete_thread permanently removes every checkpoint, blob and pending write for a thread_id, for example to meet a data deletion request. Every checkpointer has it:
saver.delete_thread("thread-id-to-purge")With an async checkpointer, call await async_saver.adelete_thread("thread-id-to-purge") inside your async code.
Choose a checkpointer
| Checkpointer | Import | Store | Use it for |
|---|---|---|---|
InMemorySaver | coco_graph.checkpoint.memory | Process memory | Development, unit tests, and single-process sessions |
SqliteSaver | coco_graph.checkpoint.sqlite | SQLite | Local persistence, CLI tools, and lightweight services |
AsyncSqliteSaver | coco_graph.checkpoint.sqlite.aio | SQLite, through aiosqlite | Async local persistence and single-node async apps |
PostgresSaver | coco_graph.checkpoint.postgres | PostgreSQL | Production services with several workers |
AsyncPostgresSaver | coco_graph.checkpoint.postgres.aio | PostgreSQL, async | High-concurrency async services |