> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# History Injection

> Automatically inject session history into agent context for multi-turn conversations

> [!NOTE]
>
> 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](https://praison.ai/docs/docs/features/session-persistence#retention-policies) for how overflow is summarised and archived.

> [!NOTE]
>
> 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](https://github.com/MervinPraison/PraisonAI/pull/5695); earlier versions raised `AttributeError` on that shape. See [OpenAI → Transparent Responses API routing](https://praison.ai/docs/models/openai.md#transparent-responses-api-routing) for the full behaviour.

> [!NOTE]
>
> 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](https://github.com/MervinPraison/PraisonAI/pull/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](https://praison.ai/docs/models/openai.md#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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "History Injection"
        H1[📋 Prior Messages] --> B[🧠 Build Messages]
        B --> M[✅ LLM Request]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    class H1 input
    class B tool
    class M output
```

## Quick Start

**1. Simple Usage**

> [tab] Preset (Simple)
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # Enable history with defaults (last 10 messages)
> agent = Agent(
>     name="assistant",
>     instructions="Be helpful",
>     memory="history"
> )
> ```

> [tab] Chat Preset
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import Agent
>
> # Conversational preset (last 20 messages)
> agent = Agent(
>     name="assistant",
>     instructions="Be helpful",
>     memory="chat"
> )
> ```

> [tab] Custom Limit
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> 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)
> )
> ```

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

```python history theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable history via memory preset
agent = Agent(
    name="assistant",
    memory="history"  # Enables history with file backend
)
```

```python session theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Alias for history preset
agent = Agent(
    name="assistant",
    memory="session"  # Same as "history"
)
```

```python chat theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Conversational preset with higher limit
agent = Agent(
    name="assistant",
    memory="chat"  # history_limit=20
)
```

## MemoryConfig

For full control, use `MemoryConfig`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
    )
)
```

**MemoryConfig History Fields**

**history** `bool` (default: False)

Whether history injection is enabled

**history\_limit** `int` (default: 10)

Maximum number of messages to inject (most recent)

> [!NOTE]
>
> Default sessions are **workspace-scoped** — the same agent name in a different project is a different session. See [Where sessions live](https://praison.ai/docs/docs/memory/features#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:

> [tab] MemoryConfig (Recommended)
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> 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!
> ```

> [tab] Legacy (Deprecated)
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Session

    User->>Agent: start("What did we decide?")
    Agent->>Session: get_chat_history(session_id, limit)
    Session-->>Agent: Previous messages
    Agent->>Agent: _build_messages() with history
    Agent-->>User: Context-aware response
```

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

**2. Message Building**

When `_build_messages()` is called:

1. System prompt is added
2. **Session history is injected** (if enabled)
3. In-memory chat history is added
4. User prompt is added

**3. 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](https://praison.ai/docs/features/session-compaction-checkpoint.md).

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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](https://praison.ai/docs/docs/memory/session-resume#auto-derived-session-id-is-workspace-scoped).

## Best Practices

> [accordion] Set reasonable limits
>
> Use `memory="history"` (10 messages) to avoid token bloat. More history means more tokens and higher cost.

> [accordion] Use meaningful session IDs
>
> Always use session IDs like `user-{user_id}` for multi-user apps via `auto_save`.

> [accordion] Combine with auto\_save
>
> Use `auto_save` to persist conversations and `memory="history"` to reload them. Repeated turns persist incrementally.

> [accordion] 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 | ✅ | ✅ | ✅ |

> [!TIP]
>
> Use `memory="history"` for conversation continuity with reasonable context. Use `memory="chat"` for longer conversational context.

## Related

> [card] [Memory](https://praison.ai/docs/memory/overview.md)
>
> Full memory system with backends

> [card] [Sessions](https://praison.ai/docs/features/sessions.md)
>
> Session management and persistence


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.