Memory

Give agents persistent memory across sessions with pluggable backends

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

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.

Quick Start

1. 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.")

2. 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.")

3. 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?")

4. 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

Which Backend to Choose?

graph TB
    Q{What's your setup?}
    Q -->|Prototype / single server| F[file backend\ndefault, zero deps]
    Q -->|Single server, persistent| S[sqlite backend]
    Q -->|Vector search / RAG| C2[chroma backend]
    Q -->|Multi-agent shared memory| M[mem0 or mongodb]
    Q -->|Self-hosted decay-weighted memory| D[dakera]
    Q -->|Redis / Postgres| DB[use db\(url=...\)]
    Q -->|Anthropic model with long context| C[claude_memory=True]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef backend fill:#6366F1,stroke:#7C90A0,color:#fff

    class Q decision
    class F,S,C2,M,D,DB,C backend

Configuration Options

The most common options at a glance:

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 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.

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.")

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,          # required on file; sqlite/chroma/mem0 prefetch automatically
        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

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

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.

Session auto-save writes now run on a worker thread on the async path too. Agent(memory=MemoryConfig(auto_save="…")) persists via asyncio.to_thread on astart, _adelegate_to_backend, and each iteration of run_autonomous_async, so concurrent async agents sharing the same session store no longer serialise on one another’s file-lock + JSON write (PR #5258). An internal lock also serialises the shared save index, so two async runs sharing one Agent never double-persist the same turns.

Related