Skip to main content
JSON file persistence saves agent sessions as human-readable files — no database required. 
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.

​
Quick Start

1

Simple Usage

Set session_id — PraisonAI persists to JSON automatically:
from praisonaiagents import Agent

agent = Agent(
    name="FileBot",
    session_id="dev-session",
)
agent.start("Remember I prefer British English")
2

With Configuration

Custom session directory or the conversation JSON store:
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")

​
How It Works

StoreLocationUse case
DefaultSessionStore~/.praisonai/sessions/Agent session_id (zero config)
JSONConversationStoreConfigurable pathFull 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. 
{
  "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": {}
  }
}
FieldTypeDefaultMeaning
summarystr(required)The condensed history the compactor produced
message_indexint0Transcript length at compaction time; anything after this index is the tail
rolestr"system"Role used when replaying the summary as an LLM message
tokens_beforeint0Token count before compaction (observability)
tokens_afterint0Token count after compaction (observability)
timestampfloattime.time()When the checkpoint was written
metadataDict[str, Any]{}Free-form extension slot
See Compacted Session Resume for how the key is produced and consumed.

​
Configuration Options

​
DefaultSessionStore

OptionTypeDefaultDescription
session_dirstr~/.praisonai/sessions/Directory for session JSON files
max_messagesint100Maximum messages kept per session
lock_timeoutfloat5.0File lock timeout in seconds

​
JSONConversationStore

OptionTypeDefaultDescription
pathstr"./praisonai_conversations"Directory for JSON files
prettyboolTruePretty-print JSON output
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.

​
Best Practices

No db= needed — set session_id and conversations persist to ~/.praisonai/sessions/ automatically.
Point DefaultSessionStore(session_dir=...) at a project folder to keep sessions alongside your code.
JSON suits development and small deployments. Move to SQLite or PostgreSQL when you need querying or multi-instance scaling.
Copy the session folder regularly — each session is a single readable .json file.

SQLite Persistence

Upgrade to SQLite for SQL queries and better concurrency

Database Persistence

Compare all persistence backends