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

# JSON File Persistence

> Zero-config file persistence for development and lightweight applications

JSON file persistence saves agent sessions as human-readable files — no database required.

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

agent = Agent(
    name="FileBot",
    instructions="You are a helpful assistant.",
    session_id="my-session",
)
agent.start("Hello — this conversation is saved to JSON files")
```

The user chats locally; JSON files persist the session without installing a database.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[🤖 Agent] --> Store[📄 Session Store]
    Store --> Files[💾 JSON Files]
    Files --> Disk[🗂️ ~/.praisonai/sessions]

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

    class Agent agent
    class Store store
    class Files,Disk disk
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Set `session_id` — PraisonAI persists to JSON automatically:

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

    agent = Agent(
        name="FileBot",
        session_id="dev-session",
    )
    agent.start("Remember I prefer British English")
    ```
  </Step>

  <Step title="With Configuration">
    Custom session directory or the conversation JSON store:

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

    # Agent sessions — custom directory
    store = DefaultSessionStore(session_dir="./my_sessions")

    # Full conversation API — praisonai package
    conv_store = create_conversation_store("json", path="./data/conversations")
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant Store as DefaultSessionStore
    participant File as session.json

    Agent->>Store: add_message
    Store->>File: atomic write + file lock
    Agent->>Store: get_chat_history
    Store->>File: reload under lock
    File-->>Agent: conversation history
```

| Store                   | Location                 | Use case                         |
| ----------------------- | ------------------------ | -------------------------------- |
| `DefaultSessionStore`   | `~/.praisonai/sessions/` | Agent `session_id` (zero config) |
| `JSONConversationStore` | Configurable path        | Full conversation API via `db()` |

***

## Compaction Checkpoint Key

When context compaction persists a checkpoint, the session JSON gains an optional top-level `last_compaction` object. It is omitted entirely when no checkpoint exists, so older session files load unchanged.

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "session_id": "user-42-chat",
  "messages": [ ... ],
  "last_compaction": {
    "summary": "Earlier: we discussed X, Y, Z.",
    "message_index": 40,
    "role": "system",
    "tokens_before": 8100,
    "tokens_after": 1200,
    "timestamp": 1751894400.0,
    "metadata": {}
  }
}
```

| Field           | Type             | Default       | Meaning                                                                     |
| --------------- | ---------------- | ------------- | --------------------------------------------------------------------------- |
| `summary`       | `str`            | *(required)*  | The condensed history the compactor produced                                |
| `message_index` | `int`            | `0`           | Transcript length at compaction time; anything after this index is the tail |
| `role`          | `str`            | `"system"`    | Role used when replaying the summary as an LLM message                      |
| `tokens_before` | `int`            | `0`           | Token count before compaction (observability)                               |
| `tokens_after`  | `int`            | `0`           | Token count after compaction (observability)                                |
| `timestamp`     | `float`          | `time.time()` | When the checkpoint was written                                             |
| `metadata`      | `Dict[str, Any]` | `{}`          | Free-form extension slot                                                    |

See [Compacted Session Resume](/docs/features/session-compaction-checkpoint) for how the key is produced and consumed.

***

## Configuration Options

### DefaultSessionStore

| Option         | Type    | Default                  | Description                       |
| -------------- | ------- | ------------------------ | --------------------------------- |
| `session_dir`  | `str`   | `~/.praisonai/sessions/` | Directory for session JSON files  |
| `max_messages` | `int`   | `100`                    | Maximum messages kept per session |
| `lock_timeout` | `float` | `5.0`                    | File lock timeout in seconds      |

### JSONConversationStore

| Option   | Type   | Default                       | Description              |
| -------- | ------ | ----------------------------- | ------------------------ |
| `path`   | `str`  | `"./praisonai_conversations"` | Directory for JSON files |
| `pretty` | `bool` | `True`                        | Pretty-print JSON output |

<Note>
  On macOS, Linux, and Windows, `DefaultSessionStore` uses file locking for multi-process safety. On platforms without `fcntl`, a one-time warning is logged and single-process usage remains safe.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use session_id for quick dev">
    No `db=` needed — set `session_id` and conversations persist to `~/.praisonai/sessions/` automatically.
  </Accordion>

  <Accordion title="Set a custom session_dir for projects">
    Point `DefaultSessionStore(session_dir=...)` at a project folder to keep sessions alongside your code.
  </Accordion>

  <Accordion title="Upgrade when data grows">
    JSON suits development and small deployments. Move to SQLite or PostgreSQL when you need querying or multi-instance scaling.
  </Accordion>

  <Accordion title="Back up the sessions directory">
    Copy the session folder regularly — each session is a single readable `.json` file.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="SQLite Persistence" icon="database" href="/docs/features/persistence-sqlite">
    Upgrade to SQLite for SQL queries and better concurrency
  </Card>

  <Card title="Database Persistence" icon="database" href="/docs/features/persistence">
    Compare all persistence backends
  </Card>
</CardGroup>