Package com.tnsai.state

package com.tnsai.state

State persistence and checkpointing for agent recovery.

This package provides mechanisms for saving and restoring agent state, enabling fault tolerance and recovery in long-running agent systems.

Checkpointing Architecture

 ┌─────────────────────────────────────────────────────────────┐
 │                      Checkpointer                            │
 │                     (Interface)                              │
 └──────────────────────────┬──────────────────────────────────┘
                            │
    ┌───────┬───────┬───────┼───────┬───────┬───────┐
    │       │       │       │       │       │       │
    ▼       ▼       ▼       ▼       ▼       ▼       ▼
 InMemory  File  SQLite  PostgreSQL MongoDB  Redis (Custom)
 

Available Implementations

Implementation	Use Case	Persistence
InMemoryCheckpointer	Development/Testing	No (volatile)
FileCheckpointer	Single-node, simple deployments	Yes (JSON files)
invalid reference SQLiteCheckpointer	Embedded, single-node	Yes (SQLite DB)
invalid reference PostgreSQLCheckpointer	Production, multi-node	Yes (PostgreSQL)
invalid reference MongoDBCheckpointer	Document-based, scalable	Yes (MongoDB)
RedisCheckpointer	Distributed, high-perf	Yes (tnsai-distributed-redis)

State Components

Component	Description	Persisted Data
Checkpoint	Point-in-time snapshot	Full agent state
ThreadState	Execution thread state	Messages, context
AgentState	Agent configuration	Beliefs, desires, etc.

Usage Example

 // Create checkpointer
 Checkpointer checkpointer = new InMemoryCheckpointer();

 // Save checkpoint
 Checkpoint checkpoint = Checkpoint.builder()
     .threadId("thread-123")
     .state(agentState)
     .build();
 checkpointer.save(checkpoint);

 // Restore checkpoint
 Optional<Checkpoint> restored = checkpointer.load("thread-123");
 if (restored.isPresent()) {
     agent.restore(restored.get());
 }

 // List checkpoints
 List<String> threads = checkpointer.listThreads();

 // Delete old checkpoints
 checkpointer.delete("thread-123");
 

Recovery Scenarios

• Process restart: Load latest checkpoint and resume
• Failure recovery: Rollback to last known good state
• Debugging: Inspect state at specific points
• Long conversations: Persist and resume later

Distributed Checkpointing

For distributed systems, see tnsai-distributed-redis which provides Redis-backed checkpointing with distributed locks.

See Also:

• Agent

Related Packages

Package	Description
com.tnsai	TnsAI Java SDK - A multi-agent framework with BDI architecture and Gaia methodology.

Class	Description
Checkpointer	Checkpointer interface - LangGraph-style state checkpointing.
Checkpointer.CheckpointTuple	Checkpoint tuple container.
Checkpointer.Write	Write operation.
FileCheckpointer	File-based Checkpointer with JSON serialization.
FileCheckpointer.Builder	Builder for FileCheckpointer.
InMemoryCheckpointer	In-Memory Checkpointer - For development/testing.
StateException	Exception thrown when state operations fail.