Memory - PraisonAI

Memory lets agents remember past conversations, user preferences, and context across sessions.

A subset of Memory is now callable directly over MCP — see MCP Memory Tools.

Replaces the deprecated auto_save="name" kwarg — see Legacy Agent Parameters.

Grow memory autonomously

With self_improve="background" and memory=True, the same guarded post-turn review that autonomously grows skills can also autonomously persist durable facts and preferences via store_memory — off the hot path, with zero cost to reply latency and zero context pollution during the live turn. See Self-Improving Agents.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful personal assistant.",
    memory=True,  # memory is isolated per instance — pass user_id="…" to share/persist across runs
)

agent.start("My name is Alice and I prefer concise answers.")

The user shares preferences in chat; the agent recalls them in later sessions via the configured memory backend.

Breaking change: backend no longer accepts redis/postgres/valkey.MemoryConfig(backend="redis"), backend="postgres", and backend="valkey" now raise a ValueError instead of silently substituting a local file store. Earlier releases accepted these values but stored data locally — so any code that “worked” was already not reaching Redis/Postgres.Valid backends: file, sqlite, chroma, mem0, mongodb, dakera, in_memory.Two supported ways to use Redis / Postgres:

Recommended — pass a live db() store:

from praisonaiagents import Agent, MemoryConfig, db

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    memory=MemoryConfig(db=db(state_url="redis://localhost:6379/0")),
)

from praisonaiagents import db binds the callable factory directly. The namespaced from praisonaiagents.db import db form still works.

Advanced — register a custom adapter:

from praisonaiagents.memory.adapters import register_memory_adapter

register_memory_adapter("redis", MyRedisAdapter)
agent = Agent(memory=MemoryConfig(backend="redis"))  # now accepted

See Redis persistence for the full db(state_url=...) guide.

Quick Start

Level 1 — Bool (simplest)

Turn on memory with a single flag — the agent remembers across turns using the default file backend.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    memory=True,  # memory is isolated per instance — pass user_id="…" to share/persist across runs
)
agent.start("Remember that I work in software engineering.")

memory=True and memory="file" are truly zero-dependency — the agent skips importing the heavier Memory module on this path, so Agent(memory=True) starts as fast as an agent with no memory. Heavier backends (sqlite, chroma, mem0, mongodb, dakera, or learn=True) load their dependencies lazily and raise a friendly ImportError if the praisonaiagents[memory] extra isn’t installed.If a memory provider’s backend package is installed but initialisation fails (for example a SaaS backend like mem0 needs credentials or network), the agent now falls back to FileMemory with a warning instead of raising. This mirrors the existing “missing dependencies → FileMemory” contract, so Agent(...) construction never hard-crashes on a misconfigured backend.

Level 2 — String (pick a backend)

Pass a backend name to choose where memories are stored.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    memory="sqlite",
)
agent.start("Remember that I prefer concise answers.")

Level 3 — Config class (full control)

Use MemoryConfig to scope memory per user and auto-extract facts.

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    memory=MemoryConfig(
        backend="sqlite",
        user_id="alice",
        auto_memory=True,
    ),
)
agent.start("What do you know about my preferences?")

Level 4 — Config with continuous learning

Add LearnConfig to build a long-term persona alongside session memory.

from praisonaiagents import Agent, MemoryConfig, LearnConfig

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    memory=MemoryConfig(
        backend="sqlite",
        user_id="alice",
        learn=LearnConfig(persona=True, insights=True, mode="agentic"),
    ),
)
agent.start("I always want answers formatted as bullet points.")

How It Works

Phase	What happens
1. Store	Each conversation turn is saved to the memory backend
2. Retrieve	Relevant past context is recalled before responding
3. Respond	Agent answers with full historical context available

Retrieved memory reaches the system prompt under normal logging (WARNING/INFO). You no longer need verbose=5 / DEBUG logging or an explicit include_in_output=True for Agent(memory=True) to take effect during a chat — see Memory Troubleshooting.

Turn on prefetch=True on MemoryConfig to have relevant long-term memories injected into the system prompt at the start of every turn — no explicit recall() call required.

Which Backend to Choose?

Configuration Options

Full list of options, types, and defaults — MemoryConfig

The most common options at a glance:

Option	Type	Default	Description
`backend`	`str`	`"file"`	Storage backend: `file`, `sqlite`, `chroma`, `mem0`, `mongodb`, `dakera`, `in_memory`. Aliases: `chromadb`/`rag` → `chroma`, `none` → `in_memory`.
`user_id`	`str \| None`	`None`	User identifier for scoped memory. Leaving it `None` now yields a per-instance `agent-<uuid>` id (not a shared `"default"`) — set it to share/persist across runs
`auto_memory`	`bool`	`False`	Auto-extract and store key facts
`learn`	`bool \| LearnConfig \| None`	`None`	Enable continuous learning
`history`	`bool`	`False`	Auto-inject session history into context
`prefetch`	`bool`	`False`	Opt-in: at turn start, recall long-term memories relevant to the user prompt and inject them into the system context
`prefetch_limit`	`int`	`5`	Max number of memories injected per turn
`prefetch_token_budget`	`int`	`512`	Estimated-token cap for the injected memory block (truncated with `…` if exceeded)

Turn on prefetch=True on MemoryConfig to have relevant long-term memories injected into the system prompt at the start of every turn — no explicit recall() call required. See Memory Prefetch for the full guide.

Combining `backend` and `config`

Pass a config= dict alongside backend= to hand provider-specific settings to the store — the outer backend= still decides which store is built.

from praisonaiagents import Agent
from praisonaiagents.config.feature_configs import MemoryConfig

agent = Agent(
    name="Assistant",
    instructions="Remember facts across turns.",
    memory=MemoryConfig(
        backend="sqlite",
        user_id="alice",
        config={"short_db": "./mem/short.db"},
    ),
)
agent.start("My favourite colour is teal.")

An explicit provider or backend key inside config= wins; otherwise the outer backend= fills in.

What you wrote	Backend actually used
`MemoryConfig(backend="sqlite")`	`sqlite`
`MemoryConfig(backend="sqlite", config={"short_db": "…"})`	`sqlite`
`MemoryConfig(backend="sqlite", config={"provider": "file"})`	`file` (inner wins)
`MemoryConfig(backend="sqlite", config={"backend": "file"})`	`file` (inner wins)
`MemoryConfig(backend="file")`	`file`

The config dict you pass in is never mutated — a provider key, if injected, is written to an internal copy. Safe to share the same dict across multiple agents.

Common Patterns

Pattern 1 — User-scoped memory

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    instructions="You are a personal assistant.",
    memory=MemoryConfig(user_id="user_alice", backend="sqlite"),
)
response = agent.start("What have I told you about my work preferences?")
print(response)

Pattern 2 — History injection for conversation continuity

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    instructions="You are a support agent.",
    memory=MemoryConfig(history=True, history_limit=5),
)
agent.start("Continue from where we left off.")

Default sessions are workspace-scoped — the same agent name in a different project is a different session. See Where sessions live for details and the PRAISONAI_GLOBAL_SESSIONS opt-out.

Pattern 3 — Recalled context at turn start

from praisonaiagents import Agent, MemoryConfig

writer = Agent(
    name="writer",
    instructions="Store user facts.",
    memory=MemoryConfig(backend="file", user_id="alice"),
)
writer.memory.remember("User prefers metric units and dark mode.")

reader = Agent(
    name="reader",
    instructions="Answer using recalled context.",
    memory=MemoryConfig(
        backend="file",
        user_id="alice",
        prefetch=True,          # inject long-term memories at turn start
        prefetch_limit=5,
        prefetch_token_budget=512,
    ),
)

reader.start("What are my UI preferences?")

The agent sees a ## Recalled memories block in its system prompt before the first model call — no extra tool call needed.

Quick API — `remember`, `recall`, `forget`

Three verbs give you explicit control over long-term facts — store, look up, and delete. An agent with memory=True exposes its memory instance directly, so you can store and recall facts on demand.

from praisonaiagents import Agent

agent = Agent(
    name="Note Taker",
    instructions="Save and recall project facts on request.",
    memory=True,
)

# The agent's memory instance is available directly
agent.memory.remember("Sprint 42 ships on Friday")
matches = agent.memory.recall("When does sprint 42 ship?")

Use Memory() standalone in a plain script — no config, no agent required.

from praisonaiagents.memory import Memory

mem = Memory()  # no config needed — uses local SQLite
mem.remember("API rate limit is 1000 req/min")
for m in mem.recall("rate limit"):
    print(m["text"])
mem.forget(query="rate limit")

Prompt-ready context — `get_context`

get_context(query=...) returns retrieved memory as a single prompt-ready string for a given query — the same string Agent.get_memory_context() injects into the system prompt.

from praisonaiagents import Agent

agent = Agent(name="Assistant", instructions="Help the user.", memory=True)
agent.memory.remember("User is working on the climate dashboard project.")

ctx = agent.memory.get_context(query="What projects am I working on?")
print(ctx)

An empty or whitespace-only query intentionally returns "" — this avoids a LIKE "%%" scan that would pull in unrelated (and possibly other users’) records.

agent.memory.get_context(query="")   # -> ""  (nothing leaked)

Pass user_id="…" (or configure it on MemoryConfig) so user-scoped memories stay isolated when a single Memory instance is shared across users.

Parameters

Method	Parameter	Type	Default	Description
`Memory()`	`config`	`dict \| None`	`None`	Backend config. Optional — omit for the default local backend.
`Memory()`	`verbose`	`int`	`0`	Verbosity level.
`remember`	`content`	`str`	(required)	Fact to store in long-term memory.
`remember`	`metadata`	`dict \| None`	`None`	Keyword-only. Extra metadata stored with the record.
`remember` (returns)	—	`str`	—	The generated memory id.
`recall`	`query`	`str`	(required)	Search string.
`recall`	`limit`	`int`	`5`	Keyword-only. Max results returned.
`recall` (returns)	—	`list[dict]`	—	Matching records, each with at least a `text` field.
`forget`	`memory_id`	`str \| None`	`None`	Keyword-only. Delete by exact id. When no `memory_type` is passed, deletes from both tiers — short-term and long-term ids can collide because each tier has its own `AUTOINCREMENT` sequence, and the returned count reflects rows removed from both. Pass `memory_type="short_term"` or `"long_term"` via `delete_memory()` to scope the delete to a single tier.
`forget`	`query`	`str \| None`	`None`	Keyword-only. Delete long-term records matching this query.
`forget` (returns)	—	`int`	—	Count of records deleted across both tiers when `memory_id` is used without a tier.
`get_context`	`query`	`str \| None`	`None`	Search string. Empty/whitespace returns `""`.
`get_context`	`user_id`	`str \| None`	`None`	Keyword arg. Falls back to the configured `user_id`.
`get_context` (returns)	—	`str`	—	Prompt-ready context string (`""` when nothing matches).

remember() and recall() operate on long-term memory only, and forget(query=...) is scoped to long-term memory to match. forget() requires exactly one of memory_id or query — passing neither, both, or an empty query raises ValueError.

Cross-tier id collisions are normal. The SQLite adapter numbers short-term and long-term rows independently, so the Nth short-term row and the Nth long-term row share an id. forget(memory_id=id) now deletes from both tiers by design — previously it short-circuited on the first hit and could erase the wrong record while reporting success. If you need tier-scoped deletion, call agent.memory.delete_memory(memory_id, memory_type="long_term") (or "short_term").

agent.memory.get_all_memories() returns every stored short-term and long-term record (each with a public type field of "short_term" or "long_term"). When a memory adapter is configured, it now correctly delegates to the adapter — earlier releases returned [] for every provider.

Which memory API?

Interaction flow

Best Practices

Always set user_id when you want memory to persist or be shared

As of PraisonAI PR #3614, Agent(memory=True) without a user_id generates a fresh per-instance identifier (agent-<uuid>) and logs a warning. Memory is isolated per Agent object by default — safe, but not what you want if you re-create the agent between requests and expect it to remember the last conversation.Pass user_id="alice" (or "tenant-42", "project-climate", etc.) to opt into a shared / persistent store that survives across processes.As of PraisonAI #4203, this isolation now covers every backend — sqlite, chroma, mongodb, mem0, and learn derive per-agent default store paths and collection names from the same agent-<uuid> id, so two agents in one process no longer silently share one short_term.db / long_term.db / memory_store. Explicit user_id, short_db, long_db, rag_db_path, or collection_name still win. See Per-agent isolation across backends.

Use auto_memory for fact extraction

Enable auto_memory=True to have the agent automatically identify and store important facts from each conversation — names, preferences, decisions — without extra code.

Combine memory with learning

Set learn=True inside MemoryConfig to enable continuous learning alongside session memory. This gives agents both short-term context (memory) and long-term pattern recognition (learn).

Backend scaling path

Start with file, move to sqlite when you need durability, then mongodb (or chroma for vector search) when you deploy multiple agent instances that share memory. For Redis or Postgres, use memory=MemoryConfig(db=db(state_url="redis://...")) or db(database_url="postgresql://...") — see Redis persistence.

Choose remember/recall for facts, memory=True for conversation history

Agent(memory=True) auto-captures every conversation turn. remember() / recall() / forget() give you explicit control for fact storage — use them for structured knowledge you want to look up later. Both share the same long-term store when the agent’s memory instance is used.

Async safety

Task-callback memory writes (store_in_memory in Task.execute_callback) run on a worker thread on the async path. Parallel tasks batched into a single asyncio.gather(...) no longer stall the event loop on one slow embedding/DB write. The built-in in-memory adapter is thread-safe: concurrent async writes from multiple parallel tasks cannot produce duplicate ids or lose entries. No user-facing change: the async path automatically dispatches the write via asyncio.to_thread.

If you write a custom memory adapter that will be used from async task callbacks, make its mutating methods thread-safe — see Custom Memory Adapters. The full set of async guarantees lives on the Async Safety page.

Learn

Learn — continuous learning from conversations

Knowledge

Knowledge — add documents and URLs as agent knowledge

Memory Flush on Compaction

Preserve facts before compaction — save durable facts before older messages are dropped

Async Safety

Offloaded memory writes and the thread-safe in-memory adapter

​Grow memory autonomously

​Quick Start

​How It Works

​Which Backend to Choose?

​Configuration Options

​Combining backend and config

​Common Patterns

​Pattern 1 — User-scoped memory

​Pattern 2 — History injection for conversation continuity

​Pattern 3 — Recalled context at turn start

​Quick API — remember, recall, forget

​Prompt-ready context — get_context

​Parameters

​Which memory API?

​Interaction flow

​Best Practices

​Async safety

​Related

Learn

Knowledge

Memory Flush on Compaction

Async Safety

Grow memory autonomously

Quick Start

How It Works

Which Backend to Choose?

Configuration Options

Combining `backend` and `config`

Common Patterns

Pattern 1 — User-scoped memory

Pattern 2 — History injection for conversation continuity

Pattern 3 — Recalled context at turn start

Quick API — `remember`, `recall`, `forget`

Prompt-ready context — `get_context`

Parameters

Which memory API?

Interaction flow

Best Practices

Async safety

Related