Auto-checkpoint on Command:new

The ClawVault hook automatically creates checkpoints before OpenClaw resets sessions, ensuring no context is lost when users run the /new command.

How It Works

When a user runs /new in OpenClaw to reset their session:

1. Event Trigger: OpenClaw fires a command:new event
2. Hook Activation: ClawVault hook intercepts the event
3. State Capture: Current session state is saved to vault
4. Session Reset: OpenClaw proceeds with normal session reset
5. Recovery Ready: State is available for future recovery

What Gets Checkpointed

The auto-checkpoint captures essential session state:

Current Work Context

• What the agent was actively working on
• Key focus areas and priorities
• Current train of thought

Session Metadata

• Session ID and timestamp
• Agent identity and model
• Session duration and message count

Recovery Markers

• Checkpoint creation time
• Last significant activity
• Session health indicators

Example Flow

Before /new Command

User: /new

OpenClaw: [About to reset session...]
 ↓ fires command:new event
 
ClawVault Hook: 
 Detected session reset
 Creating auto-checkpoint
 Saved: "Working on clawvault docs, finishing commands section"
 Ready for reset
 
OpenClaw: [Session reset complete]

After Session Reset

The agent can recover using:

clawvault wake

Which shows:

 Wake Up Summary

Last Session:
 Ended: 2 minutes ago (auto-checkpoint)
 Working on: clawvault docs, finishing commands section 
 Duration: 45 minutes
 
Recent Context:
 - Completed repair-session.md documentation
 - In progress: template.md with examples
 - Next: OpenClaw integration docs

No context death detected 

Configuration

Auto-checkpoint runs automatically when the hook is installed — no configuration needed. The hook handler has a built-in 15-second timeout for subprocess calls.

To verify auto-checkpoint is working:

openclaw hooks list | grep clawvault
clawvault compat

Performance Characteristics

Auto-checkpoint is designed to be fast and non-intrusive:

• Typical Duration: 100-300ms
• Timeout Protection: 5 second max
• Failure Handling: Session reset continues even if checkpoint fails
• Background Processing: Non-blocking for user experience

Performance by Vault Size

Integration with Manual Checkpoints

Auto-checkpoint complements manual checkpoint usage:

Manual Checkpoints (During Work)

# Detailed checkpoints during heavy work
clawvault checkpoint --working-on "database refactor" \
 --focus "migration scripts" \
 --blocked "waiting for schema review"

Auto-checkpoints (Session Boundaries)

• Triggered automatically before /new
• Captures high-level session state
• Ensures nothing is completely lost

Recovery Strategy

1. Recent auto-checkpoint provides session boundary context
2. Manual checkpoints provide detailed work state
3. Combined recovery gives complete picture

Error Handling

The hook is designed to fail gracefully:

Checkpoint Creation Failures

• Timeout: Checkpoint abandoned after 5 seconds, session reset continues
• Vault Error: Error logged, session reset continues normally
• Permission Issue: Error logged, user notified on next wake

Recovery from Failures

# Check for checkpoint issues
clawvault doctor

# Manual recovery if auto-checkpoint failed
clawvault recover --verbose

Checkpoint Storage

Auto-checkpoints are stored in your vault's checkpoint system:

vault/
├── .clawvault/
│ ├── checkpoints/
│ │ ├── 2024-01-15T14:30:52.json (auto)
│ │ ├── 2024-01-15T14:45:12.json (manual)
│ │ └── 2024-01-15T15:02:33.json (auto)
│ └── last-checkpoint.json (latest)

Checkpoint Metadata

Each checkpoint includes:

{
 "type": "auto",
 "event": "command:new", 
 "timestamp": "2024-01-15T15:02:33Z",
 "session_id": "main/2024-01-15-143052",
 "duration_ms": 150,
 "context": {
 "working_on": "clawvault documentation",
 "focus": "OpenClaw integration guides",
 "last_activity": "2024-01-15T15:02:18Z"
 }
}

Troubleshooting

Auto-checkpoint Not Running

Symptoms:

• /new command doesn't create checkpoints
• No recovery context after session reset
• clawvault wake shows no recent checkpoints

Diagnosis:

# Check hook status
openclaw hooks list | grep clawvault

# Run compatibility check
clawvault compat

Solutions:

# Reinstall hook
clawhub install clawvault

# Check vault health
clawvault doctor

Missing Context After Reset

# Check recovery state
clawvault recover --verbose

# Manual checkpoint before important work
clawvault checkpoint --working-on "important task"

# Check vault health
clawvault doctor

Best Practices

Disable Auto-checkpoint

To disable auto-checkpoint, remove or rename the ClawVault hook:

# Remove hook entirely
rm -rf ~/.openclaw/hooks/clawvault

# Or just remove the handler
mv ~/.openclaw/hooks/clawvault/handler.js ~/.openclaw/hooks/clawvault/handler.js.disabled

You can still use manual checkpoints:

# Before running /new manually
clawvault checkpoint --working-on "current task"

Comparison with Manual Workflow

The hybrid approach uses auto-checkpoint as a safety net while manual checkpoints provide detailed context for important work.