Coco
Build agents

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

CheckpointerImportStoreUse it for
InMemorySavercoco_graph.checkpoint.memoryProcess memoryDevelopment, unit tests, and single-process sessions
SqliteSavercoco_graph.checkpoint.sqliteSQLiteLocal persistence, CLI tools, and lightweight services
AsyncSqliteSavercoco_graph.checkpoint.sqlite.aioSQLite, through aiosqliteAsync local persistence and single-node async apps
PostgresSavercoco_graph.checkpoint.postgresPostgreSQLProduction services with several workers
AsyncPostgresSavercoco_graph.checkpoint.postgres.aioPostgreSQL, asyncHigh-concurrency async services

On this page