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.
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.
Quick Start
- Simple Usage
Set
session_id— PraisonAI persists to JSON automatically:python from praisonaiagents import Agent, MemoryConfig agent = Agent( name="FileBot", memory=MemoryConfig( session_id="dev-session", )) agent.start("Remember I prefer British English") - With Configuration
Custom session directory or the conversation JSON store:
python 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
| 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.
{
"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 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 |
Best Practices
Use session_id for quick dev
No db= needed — set session_id and conversations persist to ~/.praisonai/sessions/ automatically.
Set a custom session_dir for projects
Point DefaultSessionStore(session_dir=...) at a project folder to keep sessions alongside your code.
Upgrade when data grows
JSON suits development and small deployments. Move to SQLite or PostgreSQL when you need querying or multi-instance scaling.
Back up the sessions directory
Copy the session folder regularly — each session is a single readable .json file.