Memory

Runs with the same session_id share a conversation. By the end of this page that conversation survives a restart, lives in the database you choose, and stays small however long it grows.

A conversation the agent remembers

Every agent has memory; with no memory_router, it is kept in the process:

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="assistant",
        system_instruction="You are a helpful assistant. Answer in plain text, briefly.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    )
    await agent.run("My project is called Atlas.", session_id="user_123")
    result = await agent.run("What is my project called?", session_id="user_123")
    print(result["response"])

    for message in await agent.get_session_history("user_123"):
        print(message["role"], "|", message["content"][:60])
    await agent.cleanup()

asyncio.run(main())

Atlas
user | My project is called Atlas.
assistant | Got it — your project is Atlas.
user | What is my project called?
assistant | Atlas

A different session_id starts with an empty history. Leave session_id out and each run gets a new one (it is in result["session_id"]).

Keep it across restarts

In memory, the history ends with the process. To keep it, give the agent a MemoryRouter backed by a database. SQLite needs no server:

pip install "omnicoreagent[postgres]"

The postgres extra installs SQLAlchemy, which the SQL backend uses for SQLite too. Save this as remember.py:

import asyncio
import os
import sys

os.environ.setdefault("DATABASE_URL", "sqlite:///./memory.db")

from omnicoreagent import MemoryRouter, OmniCoreAgent

async def main(message: str):
    agent = OmniCoreAgent(
        name="assistant",
        system_instruction="You are a helpful assistant. Answer in plain text, briefly.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        memory_router=MemoryRouter("sql"),
    )
    result = await agent.run(message, session_id="user_123")
    print(result["response"])
    await agent.cleanup()

asyncio.run(main(sys.argv[1]))

Run it twice — two separate processes:

python remember.py "My project is called Atlas and it ships on Friday."
python remember.py "When does my project ship, and what is it called?"

Got it — Atlas ships on Friday.
Your project is called Atlas, and it ships on Friday.

The second process had never seen the first message: it read it from memory.db. The model’s wording will differ on your run.

The backends

`MemoryRouter(...)`	Keeps history	Set	Install
`"in_memory"` (default)	In this process; gone when it ends	—	—
`"sql"`	In a SQL database: SQLite on one machine, PostgreSQL when processes share it	`DATABASE_URL`, e.g. `sqlite:///./memory.db` or `postgresql://user:pass@host/db`	`omnicoreagent[postgres]`
`"redis"`	In Redis	`REDIS_URL`, e.g. `redis://localhost:6379/0`	`omnicoreagent[redis]`
`"mongodb"`	In MongoDB	`MONGODB_URI`; optional `MONGODB_DB_NAME` (default `omnicoreagent`) and `MONGODB_COLLECTION` (default `messages`)	`omnicoreagent[mongodb]`

DATABASE_URL is a SQLAlchemy URL. The postgres extra brings SQLAlchemy and the PostgreSQL driver. SQLite needs it too, though Python has SQLite built in: every "sql" store goes through SQLAlchemy, and the postgres extra is the one that ships it. Another database SQLAlchemy supports needs its own driver installed. A router you create keeps its connections open until you close it. Build one per process and share it across agents; if you build one per request, close it when the request is done:

router = MemoryRouter("mongodb")
try:
    agent = OmniCoreAgent(..., memory_router=router)
    result = await agent.run("hello")
finally:
    await router.close()

The memory store also holds your runs. A run that pauses for an approval or a budget is saved in the memory store, and resumed from it. To pause in one process and resume in another, both need a store they can reach: sql, redis or mongodb (durable runs). Finished run records are removed after run_retention_days (30 by default).

Read, clear, switch

history = await agent.get_session_history("user_123")  # the active messages
await agent.clear_session_history("user_123")          # forget one session
await agent.clear_session_history()                    # forget every session of this agent
print(await agent.get_memory_store_type())              # "sql"
await agent.switch_memory_store("redis")                # use another backend from now on

History is kept per agent: two agents with different names sharing one store and one session_id each see only their own messages. Switching backends does not copy anything: the new store starts with what it already holds.

Long conversations: windows and summaries

A session’s full history is kept; memory_config decides how much of it each run is given. By default a run gets the last 10,000 messages, which in practice is the whole history; context_management then keeps each model call under its token budget (Context engineering). A long-lived session is better served by a window of its own. A smaller window, with the part that falls out of it summarized:

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="assistant",
        system_instruction="You are a helpful assistant. Answer in plain text, in one short sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={
            "memory_config": {
                "mode": "sliding_window",
                "value": 4,  # the run sees at most 4 messages of history
                "summary": {"enabled": True, "retention_policy": "keep"},
            }
        },
    )
    for message in [
        "My project is called Atlas.",
        "It ships on Friday.",
        "The team is Ada, Grace and Linus.",
        "Who is on the team, and what is the project called?",
    ]:
        result = await agent.run(message, session_id="user_123")
    print(result["response"])

    await asyncio.sleep(1)  # the summary is saved in the background
    for message in await agent.get_session_history("user_123"):
        print(message["role"], "|", message["content"][:90].replace("\n", " "))
    await agent.cleanup()

asyncio.run(main())

The team is Ada, Grace, and Linus, and the project is Atlas.
user | [CONVERSATION SUMMARY] The conversation established the project’s basic details and timeli
assistant | Noted — the team is Ada, Grace, and Linus.
user | Who is on the team, and what is the project called?
assistant | The team is Ada, Grace, and Linus, and the project is Atlas.

The project’s name had left the window by the last question, and the agent still knew it: the older messages became one [CONVERSATION SUMMARY] message. How it works: when a run loads a session whose history is larger than the window, the older messages are summarized by the agent’s own model (one extra model call), the summary takes one slot of the window, and the most recent messages fill the rest. A tool call and its result are kept together. Without summary, the older messages are simply left out of the run.

`memory_config` key	Values	What it does
`mode`	`"sliding_window"` (default), `"token_budget"`	Count the window in messages, or in tokens
`value`	a number; default `10000`	The most messages (`sliding_window`) or tokens (`token_budget`) of history a run is given
`summary.enabled`	`False` (default), `True`	Summarize what falls out of the window instead of dropping it
`summary.retention_policy`	`"keep"` (default), `"delete"`	After summarizing: keep the originals in the store, marked inactive, or delete them

memory_config is merged with the defaults one level deep: a key you leave out keeps its default, so {"value": 50} still counts in messages. A summary you give replaces the default summary as a whole, and a key left out of it takes the summarizer’s own default (retention_policy falls back to "keep"). Within one run, the context is kept under the model’s limit separately, by context_management (context engineering).

Options

Where	Option	Default	What it does
constructor	`memory_router`	`MemoryRouter("in_memory")`	Where history and run records are kept
`agent_config`	`memory_config`	`sliding_window`, `10000`, no summary	How much history a run is given
`agent_config`	`run_retention_days`	`30`	Days finished run records are kept; `None` keeps them all
`run(...)`	`session_id`	a new one per run	Which conversation the run continues

The full lists: agent settings and the OmniCoreAgent reference.

When things go wrong

The agent logs to the omnicoreagent logger and prints nothing on its own. To see warnings, turn logging on:

import logging

logging.basicConfig(level=logging.WARNING)

ValueError: MemoryRouter(...) needs DATABASE_URL

The URL variable was not set when the MemoryRouter was created. Building the router raises rather than keeping history in process memory, where a restart would lose it:

ValueError: MemoryRouter("sql") needs DATABASE_URL (e.g. sqlite:///./memory.db). Set it, or use MemoryRouter("in_memory") for a store that lasts only as long as this process.

"redis" without REDIS_URL and "mongodb" without MONGODB_URI raise the same way. Set the variable before building the router.

ImportError: SQL database memory requires optional dependency 'sqlalchemy'

ImportError: SQL database memory requires optional dependency 'sqlalchemy'. Install it with: pip install 'omnicoreagent[postgres]'

Install the extra the message names. Redis and MongoDB name theirs the same way.

ValueError: Invalid memory store type

ValueError: Invalid memory store type: postgres. Use one of: in_memory, sql, redis, mongodb

PostgreSQL, MySQL and SQLite are all "sql"; the URL picks the database.

Invalid memory mode

Raised when the agent starts, from a memory_config with an unknown mode:

ValueError: Invalid memory mode: window. Must be one of {'sliding_window', 'token_budget'}.

Use sliding_window or token_budget. A partial memory_config is merged with the defaults, so a key you leave out, such as value, keeps its default.

Durable runs

Pause a run, resume it later — in another process — from the memory store.

Context engineering

Keeping one run’s context under the model’s limit.

Workspace files

The agent’s files: notes, plans, generated work.

Serve it

Sessions over REST and SSE.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Memory

Memory

A conversation the agent remembers

Keep it across restarts

The backends

Read, clear, switch

Long conversations: windows and summaries

Options

When things go wrong

Next

Durable runs

Context engineering

Workspace files

Serve it

​Memory

​A conversation the agent remembers

​Keep it across restarts

​The backends

​Read, clear, switch

​Long conversations: windows and summaries

​Options

​When things go wrong

​Next

Durable runs

Context engineering

Workspace files

Serve it

Memory

A conversation the agent remembers

Keep it across restarts

The backends

Read, clear, switch

Long conversations: windows and summaries

Options

When things go wrong

Next