Memory Features

Auto-memory, history injection, session persistence, and learning

Memory Features

PraisonAI agents support several memory features that make conversations smarter over time. Each feature is opt-in — disabled by default for zero overhead.

Diagram

Quick Comparison

Feature	What it does	Config
auto_save	Saves full conversation to disk	`auto_save="chat1"`
history	Injects past sessions into context	`history=True`
auto_memory	Extracts facts/preferences automatically	`auto_memory=True`
learn	Captures patterns and insights	`learn=True`

Auto-Save Sessions

Automatically saves the full conversation history to disk after each start() / run() call.

Simple

python

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory=MemoryConfig(auto_save="my_chat")
)

agent.start("Hello!")
# Session saved to ~/.praisonai/memory/sessions/my_chat.json

Preset

python

from praisonaiagents import Agent

# Use the "session" preset (auto_save + history)
agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory="session"
)

Diagram

History Injection

Automatically loads past session history into context so the agent remembers previous conversations.

Basic

python

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory=MemoryConfig(history=True)
)

# First run
agent.start("My name is Alice")

# Later run — agent remembers!
agent.start("What's my name?")
# → "Your name is Alice"

With Limit

python

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory=MemoryConfig(
        history=True,
        history_limit=20,  # Load last 20 messages
        session_id="user_123"  # Explicit session ID
    )
)

Preset

python

from praisonaiagents import Agent

# "history" preset — history=True, limit=10
agent = Agent(name="assistant", memory="history")

# "chat" preset — history=True, limit=20
agent = Agent(name="assistant", memory="chat")

Diagram

Where sessions live

Every auto-generated session is scoped to your workspace, so the same agent name in a different project starts fresh instead of leaking history.

Signal	Used as workspace identity
Inside a git repo	The repo’s root-commit SHA (stable across clones and paths).
Not in a git repo	The absolute path of your current directory.
Neither works (rare)	The literal string `global`.

The final on-disk id is:

history_<sha256("<workspace_id>:<agent_name>")[:8]>.json

Stored under ~/.praisonai/sessions/ (or wherever PRAISONAI_HOME points).

Diagram

Read the resolved identity from Python:

python

from praisonaiagents.session import workspace_id

print(workspace_id())
# → "git:8f5c1e…" or "dir:/Users/me/projects/my-app" or "global"

Opt out with PRAISONAI_GLOBAL_SESSIONS

bash

export PRAISONAI_GLOBAL_SESSIONS=true

Reverts to the pre-workspace behaviour: the id becomes history_<sha256("global:<name>")[:8]> and same-named agents in any project share one history file. Accepted values (case-insensitive): 1, true, yes.

Upgrading from name-only sessions

Existing history_<name-only>.json files are not adopted automatically when running in workspace scope — otherwise Project A’s history would leak into Project B. – To keep using an old file everywhere, set PRAISONAI_GLOBAL_SESSIONS=true. – To keep it in one specific project, rename it to the new workspace-scoped id (or set session_id="..." explicitly). – Otherwise, agents start fresh in each new workspace.

Explicit session_id still wins

Passing session_id="..." is unchanged — it always overrides the auto id and stays global, so use it for deliberate cross-project continuity.

Auto-Memory Extraction

Automatically extracts memorable facts (names, preferences, roles) from conversations and stores them in long-term memory.

Enable

python

from praisonaiagents import Agent, MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory=MemoryConfig(auto_memory=True)
)

agent.start("My name is John and I prefer Python")
# Auto-extracted: name=John, preference=Python

Preview-then-store

python

from praisonaiagents.memory import FileMemory, AutoMemory

base = FileMemory(user_id="user123")
auto = AutoMemory(base, enabled=True)

# Preview — extraction only, no state change
auto.process_interaction("I prefer dark mode.", store=False)

# Real store — writes because the preview did not consume dedup
auto.process_interaction("I prefer dark mode.", store=True)

How It Works

Diagram

Manual Memory Storage

You can also store memories manually using the store_memory() method.

python

from praisonaiagents import Agent

agent = Agent(name="assistant", memory=True)

# Store facts manually
agent.store_memory("User prefers dark mode", "long_term")
agent.store_memory("Current task: build a dashboard", "short_term")

# Context is auto-injected into system prompt
response = agent.start("What should I work on?")

Memory Presets

Use string shortcuts instead of MemoryConfig for common configurations.

Preset	Equivalent Config
`"file"`	`MemoryConfig(backend="file")`
`"sqlite"`	`MemoryConfig(backend="sqlite")`
`"chroma"`	`MemoryConfig(backend="chroma")`
`"history"`	`MemoryConfig(history=True, history_limit=10)`
`"session"`	`MemoryConfig(history=True, history_limit=10)`
`"chat"`	`MemoryConfig(history=True, history_limit=20)`
`"learn"`	`MemoryConfig(learn=True)`

python

from praisonaiagents import Agent

# These are equivalent:
agent1 = Agent(name="a", memory="history")
agent2 = Agent(name="a", memory=MemoryConfig(history=True))

Custom Memory Backend

Implement the AgentMemoryProtocol to create your own memory backend.

python

from praisonaiagents import Agent

class MyRedisMemory:
    """Custom memory backend."""

    def get_context(self, query=None):
        # Return stored context for system prompt
        return "User prefers Python"

    def save_session(self, name, conversation_history=None, metadata=None):
        # Persist session to your backend
        pass

agent = Agent(
    name="assistant",
    memory=MyRedisMemory()  # Pass custom instance
)

Episodic memory: dates and concurrency

FileMemory stores episodic memories in one file per day, so the date you pass must be a real calendar date.

python

from praisonaiagents.memory import FileMemory

memory = FileMemory(user_id="user123")
memory.add_episodic("Shipped the dashboard", date="2026-3-5")  # stored under 2026-03-05
memory.get_episodic(date="2026-03-05")                        # finds it

Strict format — date must parse as YYYY-MM-DD; anything else raises ValueError("date must be YYYY-MM-DD, got ..."). This applies to add_episodic, get_episodic and delete_episodic.
Normalised dates — "2026-3-5" becomes "2026-03-05", so a short-form write lands in the same file a padded read looks for.
Safe concurrent writes — each add_episodic read-modify-write runs under the store lock.

Architecture

Diagram

FileMemory persists to ~/.praisonai/memory/. Writes are atomic — see Storage → Durability.

Session Persistence

Resume conversations across restarts

Storage Backends

File, SQLite, ChromaDB, mem0, MongoDB, Dakera, in-memory

Advanced Memory

Long-term, short-term, entity memory

Graph Memory

Relationship-aware memory