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

# Checkpoints Module

> File-level checkpointing for tracking and restoring agent changes

# Checkpoints Module

The checkpoints module provides file-level checkpointing using a shadow git repository to track and restore file changes made by agents.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents
```

## Features

* **Automatic checkpointing** before file modifications
* **Rewind** to any previous checkpoint
* **Diff** between checkpoints
* **Restore** files and conversation state together

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointService

# Create checkpoint service
service = CheckpointService(
    workspace_dir="/path/to/project",
    storage_dir="~/.praisonai/checkpoints"
)

# Initialize shadow git
await service.initialize()

# Save a checkpoint
checkpoint_id = await service.save("Before refactoring")

# Restore to a checkpoint
await service.restore(checkpoint_id)
```

## Classes

### CheckpointService

Main service for managing checkpoints.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointService

service = CheckpointService(
    workspace_dir="/path/to/project",
    storage_dir="~/.praisonai/checkpoints"
)
```

#### Constructor

| Parameter       | Type  | Description                |
| --------------- | ----- | -------------------------- |
| `workspace_dir` | `str` | Directory to track         |
| `storage_dir`   | `str` | Where to store checkpoints |

#### Methods

| Method                   | Description                          |
| ------------------------ | ------------------------------------ |
| `initialize()`           | Initialize the shadow git repository |
| `save(message)`          | Save a checkpoint with a message     |
| `restore(checkpoint_id)` | Restore to a specific checkpoint     |
| `diff(from_id, to_id)`   | Get diff between two checkpoints     |
| `list()`                 | List all checkpoints                 |
| `get(checkpoint_id)`     | Get checkpoint details               |
| `delete(checkpoint_id)`  | Delete a checkpoint                  |

### Checkpoint

Represents a single checkpoint.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import Checkpoint

checkpoint = Checkpoint(
    id="abc123",
    message="Before refactoring",
    timestamp=datetime.now(),
    files_changed=["src/main.py", "src/utils.py"]
)
```

#### Attributes

| Attribute       | Type        | Description                 |
| --------------- | ----------- | --------------------------- |
| `id`            | `str`       | Unique checkpoint ID        |
| `message`       | `str`       | Checkpoint message          |
| `timestamp`     | `datetime`  | When checkpoint was created |
| `files_changed` | `list[str]` | List of changed files       |
| `metadata`      | `dict`      | Additional metadata         |

### CheckpointDiff

Diff between two checkpoints.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointDiff

diff = await service.diff(from_id, to_id)
print(diff.added_files)
print(diff.modified_files)
print(diff.deleted_files)
```

#### Attributes

| Attribute        | Type        | Description          |
| ---------------- | ----------- | -------------------- |
| `from_id`        | `str`       | Source checkpoint ID |
| `to_id`          | `str`       | Target checkpoint ID |
| `added_files`    | `list[str]` | Files added          |
| `modified_files` | `list[str]` | Files modified       |
| `deleted_files`  | `list[str]` | Files deleted        |
| `diff_content`   | `str`       | Full diff content    |

### CheckpointConfig

Configuration for checkpoint service.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointConfig

config = CheckpointConfig(
    auto_checkpoint=True,
    max_checkpoints=100,
    exclude_patterns=["*.log", "node_modules/*"]
)
```

#### Attributes

| Attribute          | Type        | Default | Description                    |
| ------------------ | ----------- | ------- | ------------------------------ |
| `auto_checkpoint`  | `bool`      | `True`  | Auto-checkpoint before changes |
| `max_checkpoints`  | `int`       | `100`   | Maximum checkpoints to keep    |
| `exclude_patterns` | `list[str]` | `[]`    | Patterns to exclude            |

### CheckpointEvent

Events emitted by the checkpoint service.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointEvent

# Available events
CheckpointEvent.CREATED    # Checkpoint created
CheckpointEvent.RESTORED   # Checkpoint restored
CheckpointEvent.DELETED    # Checkpoint deleted
```

## Usage Examples

### Basic Checkpointing

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointService

async def main():
    service = CheckpointService(workspace_dir="./my_project")
    await service.initialize()
    
    # Save checkpoint before making changes
    cp1 = await service.save("Initial state")
    
    # ... agent makes changes ...
    
    # Save another checkpoint
    cp2 = await service.save("After feature implementation")
    
    # View diff
    diff = await service.diff(cp1, cp2)
    print(f"Modified: {diff.modified_files}")
    
    # Restore if needed
    await service.restore(cp1)
```

### With Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.checkpoints import CheckpointService

service = CheckpointService(workspace_dir="./project")
await service.initialize()

agent = Agent(
    name="Developer",
    checkpoint_service=service  # Enable checkpointing
)

# Agent automatically creates checkpoints before file changes
result = agent.chat("Refactor the main.py file")

# List checkpoints
checkpoints = await service.list()
for cp in checkpoints:
    print(f"{cp.id}: {cp.message}")
```

### Automatic Checkpointing

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointService, CheckpointConfig

config = CheckpointConfig(
    auto_checkpoint=True,
    max_checkpoints=50
)

service = CheckpointService(
    workspace_dir="./project",
    config=config
)

# Checkpoints are automatically created before file modifications
```

### Excluding Files

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.checkpoints import CheckpointService, CheckpointConfig

config = CheckpointConfig(
    exclude_patterns=[
        "*.log",
        "*.tmp",
        "node_modules/*",
        "__pycache__/*",
        ".git/*"
    ]
)

service = CheckpointService(
    workspace_dir="./project",
    config=config
)
```

## Best Practices

1. **Initialize early** - Initialize checkpoint service before agent starts
2. **Meaningful messages** - Use descriptive checkpoint messages
3. **Exclude large files** - Exclude logs, dependencies, build artifacts
4. **Limit checkpoints** - Set max\_checkpoints to prevent disk bloat
5. **Regular cleanup** - Delete old checkpoints periodically

## Related

* [Agent](/docs/sdk/praisonaiagents/agent/agent) - Using checkpoints with agents
* [Session](/docs/sdk/praisonaiagents/session) - Session management