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

# Session Store

> Default JSON storage, hierarchical sessions, identity, and task-local context

Session stores persist chat history and metadata — swap the default JSON backend or use hierarchical forks without changing your agent code.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    memory={"session_id": "user-42-chat"},
)
agent.start("Remember I like tea.")
agent.start("What do I like?")  # History restored from ~/.praisonai/sessions/
```

The user chats across restarts; the session store persists history under `~/.praisonai/sessions/`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[Agent] --> P[SessionStoreProtocol]
    P --> D[DefaultSessionStore]
    P --> H[HierarchicalSessionStore]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef store fill:#189AB4,stroke:#7C90A0,color:#fff

    class A agent
    class P,D,H store
```

## How It Works

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

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Persist with session_id">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant",
        memory={"session_id": "user-42-chat"},
    )
    agent.start("Remember I like tea.")
    agent.start("What do I like?")
    ```

    Default files live at `~/.praisonai/sessions/{session_id}.json`.
  </Step>

  <Step title="Use the store directly">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonaiagents.session import get_default_session_store

    store = get_default_session_store()
    session_id = "user-42-chat"

    agent = Agent(name="Assistant", memory={"session_id": session_id})
    store.add_message(session_id, "assistant", agent.start("Summarise our chat"))
    ```
  </Step>
</Steps>

## Core Exports

| Export                                                             | Purpose                                                                                              |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `DefaultSessionStore`                                              | JSON-on-disk default backend                                                                         |
| `SessionMessage`, `SessionData`                                    | Typed message and session payloads                                                                   |
| `CompactionCheckpoint`                                             | Persisted compaction summary + resume anchor — see [Compaction Checkpoints](#compaction-checkpoints) |
| `get_default_session_store()`                                      | Process-wide store accessor                                                                          |
| `SessionStoreProtocol`                                             | Implement for Redis, Postgres, S3 — see [Session Protocol](/features/session-protocol)               |
| `HierarchicalSessionStore`, `get_hierarchical_session_store()`     | Forks, snapshots, parent-child — see [Session Hierarchy](/features/session-hierarchy)                |
| `IdentityResolverProtocol`, `FileIdentityResolver`                 | Map anonymous → known user IDs across sessions                                                       |
| `SessionContext`, `set_session_context()`, `get_session_context()` | Task-local session context for async flows                                                           |

## Compaction Checkpoints

When context compaction runs during a conversation, the store can persist the summary so a later resume replays the compacted working history (summary + retained tail) instead of the full raw transcript. See [Compacted Session Resume](/docs/features/session-compaction-checkpoint) for the end-to-end agent flow.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import CompactionCheckpoint
from praisonaiagents.session import DefaultSessionStore

store = DefaultSessionStore()
store.append_compaction_checkpoint("chat-42", "Earlier: we discussed X, Y, Z.")
history = store.get_working_history("chat-42")   # summary + tail
```

### Store Methods

| Method                                                                                                                | Description                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `append_compaction_checkpoint(session_id, summary, *, role="system", tokens_before=0, tokens_after=0, metadata=None)` | Persist a checkpoint anchored to the current end of the transcript. Returns `bool`; a blank/whitespace summary is a no-op returning `False`. |
| `get_working_history(session_id, max_messages=None)`                                                                  | Canonical read path — uses the checkpoint when present (summary + tail), falls back to raw chat history when not.                            |

### SessionData additions

`SessionData.last_compaction` holds the latest `CompactionCheckpoint` (or `None`). Two helpers support cheap resume:

| Member                                   | Description                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| `last_compaction`                        | `Optional[CompactionCheckpoint]` — the persisted checkpoint, serialised into the session JSON |
| `trim_messages(max_messages)`            | Trim the transcript head, shifting the checkpoint anchor so the retained tail stays aligned   |
| `get_working_history(max_messages=None)` | Reconstruct `[summary_message, *tail]`; falls back to `get_chat_history` with no checkpoint   |

<Note>
  `set_chat_history()` and `clear_session()` both clear `last_compaction` — replacing or clearing the transcript invalidates the anchor.
</Note>

## Task-Local Context

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.session import set_session_context, get_session_context

set_session_context(session_id="batch-job-1", user_id="operator")

ctx = get_session_context()
print(ctx.session_id)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Prefer session_id on Agent over manual store calls">
    Let `Agent(memory={"session_id": "..."})` handle persistence — use the store directly only for admin, migration, or custom backends.
  </Accordion>

  <Accordion title="Use hierarchical store for forks and snapshots">
    Switch to `get_hierarchical_session_store()` when you need branching conversations or revert — see [Session Hierarchy](/features/session-hierarchy).
  </Accordion>

  <Accordion title="Set task-local context in async workers">
    Call `set_session_context()` at the start of each async task so downstream code reads the correct session without threading IDs through every call.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Session Persistence" icon="floppy-disk" href="/docs/features/session-persistence">
    Agent-centric session\_id usage
  </Card>

  <Card title="Session Hierarchy" icon="sitemap" href="/docs/features/session-hierarchy">
    Forking and snapshots
  </Card>
</CardGroup>