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

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

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

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

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.

---

Related

SQLite Persistence

Upgrade to SQLite for SQL queries and better concurrency

Database Persistence

Compare all persistence backends