History Injection

History injection is enabled via memory presets like memory="history" or memory=MemoryConfig(history=True).

Session history is preserved even across long conversations — see Retention Policies for how overflow is summarised and archived.

When history is replayed into an OpenAI model that uses the Responses API path (gpt-4o, gpt-4.1, gpt-5, o1/o3/o4, chatgpt-4o), assistant turns with tool_calls may carry content as a plain string, a list of text parts, None, or an empty list — all shapes are translated transparently. Multimodal list content with tool_calls was fixed in PraisonAI PR #5695; earlier versions raised AttributeError on that shape. See OpenAI → Transparent Responses API routing for the full behaviour.

On the same Responses API path, tool results whose tool_call_id has no matching assistant function_call in the same payload are dropped before the Responses request is built. This is the normal shape when history trimming removes the assistant turn but keeps its tool reply, or when a new user turn follows a tool round from an earlier session. Fixed in PraisonAI PR #5682; on earlier versions the Responses API rejected the payload with No tool call found for function call output with call_id … and the client silently fell back to Chat Completions. See OpenAI → Fallback is quieter now.

Overview

History injection automatically loads previous conversation messages from a session and includes them in the agent’s context. This enables:

Multi-turn conversations across sessions
Context continuity when users return
Persistent memory without complex setup

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="Continue our conversation with prior turns in context",
    memory="history",
)

agent.start("What did we decide yesterday?")

The user returns to a session; prior messages are injected before the model runs.

Quick Start

Simple Usage

Preset (Simple)
Chat Preset
Custom Limit

from praisonaiagents import Agent

# Enable history with defaults (last 10 messages)
agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory="history"
)

from praisonaiagents import Agent

# Conversational preset (last 20 messages)
agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory="chat"
)

from praisonaiagents import Agent
from praisonaiagents import MemoryConfig

# Custom history limit
agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory=MemoryConfig(history=True, history_limit=5)
)

With Configuration

Switch presets (memory=“chat”) or use a MemoryConfig for token limits and injection rules — see the remaining tabs.

Memory Presets

Enable history via memory presets:

Preset	History Limit	Description
`memory="history"`	10 messages	Standard history injection
`memory="session"`	10 messages	Alias for “history”
`memory="chat"`	20 messages	Conversational (more context)

# Enable history via memory preset
agent = Agent(
    name="assistant",
    memory="history"  # Enables history with file backend
)

# Alias for history preset
agent = Agent(
    name="assistant",
    memory="session"  # Same as "history"
)

# Conversational preset with higher limit
agent = Agent(
    name="assistant",
    memory="chat"  # history_limit=20
)

MemoryConfig

For full control, use MemoryConfig:

from praisonaiagents import Agent
from praisonaiagents import MemoryConfig

agent = Agent(
    name="assistant",
    instructions="Be helpful",
    memory=MemoryConfig(
        history=True,       # Enable history injection
        history_limit=15    # Last 15 messages
    )
)

Show MemoryConfig History Fields

bool

default:"False"

Whether history injection is enabled

int

default:"10"

Maximum number of messages to inject (most recent)

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.

With auto_save

When using auto_save, the session ID is automatically used for history:

MemoryConfig (Recommended)
Legacy (Deprecated)

from praisonaiagents import Agent
from praisonaiagents import MemoryConfig

agent = Agent(
    name="assistant",
    memory=MemoryConfig(auto_save="my-session", history=True)
)

agent.start("Hello!")

# Later, same session continues
agent2 = Agent(
    name="assistant",
    memory=MemoryConfig(auto_save="my-session", history=True)
)
agent2.start("What did I say before?")  # Has context!

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    auto_save="my-session",  # Deprecated standalone param
    memory="history"
)

How It Works

The user sends a message; the agent loads prior turns from the session store and prepends them to the messages array before calling the model.

Agent Initialization

History settings are resolved from memory parameter:

memory="history" → enabled with limit=10
memory="chat" → enabled with limit=20
memory=MemoryConfig(history=True, history_limit=N) → custom limit

Message Building

When _build_messages() is called:

System prompt is added
Session history is injected (if enabled)
In-memory chat history is added
User prompt is added

Session Store

History is loaded from the session store using get_working_history(session_id, max_messages=limit) when the store supports it — this replays a compacted summary + retained tail if a compaction checkpoint exists. Stores that implement only get_chat_history fall back to raw history automatically. See Compacted Session Resume.

Per-turn persistence is exact. When memory="history" (or MemoryConfig(history=True)) is combined with auto_save, each agent turn persists exactly the user message and the assistant response — no duplicates, even on repeated save_state() calls. Fixed in PraisonAI PR #1897.

Auto-derived session ids are workspace-scoped. When history is enabled without an explicit session_id, the id now folds in a workspace identity so same-named agents in different projects don’t share history. Opt out with PRAISONAI_GLOBAL_SESSIONS=true. See Session Resume.

Best Practices

Set reasonable limits

Use memory="history" (10 messages) to avoid token bloat. More history means more tokens and higher cost.

Use meaningful session IDs

Always use session IDs like user-{user_id} for multi-user apps via auto_save.

Combine with auto_save

Use auto_save to persist conversations and memory="history" to reload them. Repeated turns persist incrementally.

Monitor token usage

Monitor token usage when enabling history to ensure costs stay reasonable.

Comparison

Feature	`memory=True`	`memory="history"`	`memory="chat"`
Enables memory backend	✅	✅	✅
Injects session history	❌	✅ (10 msgs)	✅ (20 msgs)
Long-term memory	✅	✅	✅

Use memory="history" for conversation continuity with reasonable context. Use memory="chat" for longer conversational context.

Memory

Full memory system with backends

Sessions

Session management and persistence

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Overview

Quick Start

Memory Presets

MemoryConfig

With auto_save

How It Works

Best Practices

Comparison

Memory

Sessions

​Overview

​Quick Start

​Memory Presets

​MemoryConfig

​With auto_save

​How It Works

​Best Practices

​Comparison

​Related

Memory

Sessions

Overview

Quick Start

Memory Presets

MemoryConfig

With auto_save

How It Works

Best Practices

Comparison

Related