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

<Info>
  History injection is enabled via memory presets like `memory="history"` or `memory=MemoryConfig(history=True)`.
</Info>

Session history is preserved even across long conversations — see [Retention Policies](/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](/docs/models/openai#transparent-responses-api-routing) for the full behaviour.
</Note>

<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](/docs/models/openai#fallback-is-quieter-now).
</Note>

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

<Steps>
  <Step title="Simple Usage">
    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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)
        )
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="With Configuration">
    Switch presets (memory="chat") or use a MemoryConfig for token limits and injection rules — see the remaining tabs.
  </Step>
</Steps>

## 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) |

<CodeGroup>
  ```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
  )
  ```
</CodeGroup>

## 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
    )
)
```

<Expandable title="MemoryConfig History Fields">
  <ParamField path="history" type="bool" default="False">
    Whether history injection is enabled
  </ParamField>

  <ParamField path="history_limit" type="int" default="10">
    Maximum number of messages to inject (most recent)
  </ParamField>
</Expandable>

<Note>
  Default sessions are **workspace-scoped** — the same agent name in a different project is a different session. See [Where sessions live](/docs/docs/memory/features#where-sessions-live) for details and the `PRAISONAI_GLOBAL_SESSIONS` opt-out.
</Note>

## With auto\_save

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

<Tabs>
  <Tab title="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>

  <Tab title="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"
    )
    ```
  </Tab>
</Tabs>

## 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
```

<Steps>
  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="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](/docs/features/session-compaction-checkpoint).
  </Step>
</Steps>

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

<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](/docs/docs/memory/session-resume#auto-derived-session-id-is-workspace-scoped).
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Set reasonable limits">
    Use `memory="history"` (10 messages) to avoid token bloat. More history means more tokens and higher cost.
  </Accordion>

  <Accordion title="Use meaningful session IDs">
    Always use session IDs like `user-{user_id}` for multi-user apps via `auto_save`.
  </Accordion>

  <Accordion title="Combine with auto_save">
    Use `auto_save` to persist conversations and `memory="history"` to reload them. Repeated turns persist incrementally.
  </Accordion>

  <Accordion title="Monitor token usage">
    Monitor token usage when enabling history to ensure costs stay reasonable.
  </Accordion>
</AccordionGroup>

## 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.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Memory" href="/docs/memory/overview" icon="brain">
    Full memory system with backends
  </Card>

  <Card title="Sessions" href="/docs/features/sessions" icon="clock">
    Session management and persistence
  </Card>
</CardGroup>


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