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

agent = Agent(
    name="FileBot",
    instructions="You are a helpful assistant.",
    memory=MemoryConfig(
        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, MemoryConfig

    agent = Agent(
        name="FileBot",
        memory=MemoryConfig(
            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()` |

<Note>
  Async JSON storage (`BaseJSONStorage.save_async`) serialises the data **first**, then writes a temp file and swaps it in with `os.replace` (PR [#5357](https://github.com/MervinPraison/PraisonAI/pull/5357)). A crash mid-write cannot truncate the JSON file — the previous good file stays intact.
</Note>

***

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


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