claudetools/PERIODIC_SAVE_QUICK_START.md

Periodic Context Save - Quick Start

Auto-save context every 5 minutes of active work

---

✅ System Tested and Working

The periodic context save system has been tested and is working correctly. It:

• ✅ Detects Claude Code activity
• ✅ Tracks active work time (not idle time)
• ✅ Saves context to database every 5 minutes
• ✅ Currently has 2 contexts saved

---

Setup (One-Time)

Option 1: Automatic Setup (Recommended)

Run this PowerShell command as Administrator:

powershell -ExecutionPolicy Bypass -File D:\ClaudeTools\.claude\hooks\setup_periodic_save.ps1

This creates a Windows Task Scheduler task that runs every minute.

Option 2: Manual Setup

1. Open Task Scheduler (taskschd.msc)
2. Create Basic Task:
   • Name: ClaudeTools - Periodic Context Save
   • Trigger: Daily, repeat every 1 minute
   • Action: Start a program
     • Program: python
     • Arguments: D:\ClaudeTools\.claude\hooks\periodic_save_check.py
     • Start in: D:\ClaudeTools
   • Settings:
     • ✅ Allow task to run on batteries
     • ✅ Start task if connection is not available
     • ✅ Run task as soon as possible after missed start

---

Verify It's Working

Check Status

# View recent logs
tail -10 .claude/periodic-save.log

# Check current state
cat .claude/.periodic-save-state.json | python -m json.tool

Expected output:

{
  "active_seconds": 120,
  "last_save": "2026-01-17T19:00:32+00:00",
  "last_check": "2026-01-17T19:02:15+00:00"
}

Check Database

curl -s "http://172.16.3.30:8001/api/conversation-contexts?limit=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  | python -m json.tool

Look for contexts with title starting with "Periodic Save -"

---

How It Works

Every 1 minute:
├─ Task Scheduler runs periodic_save_check.py
├─ Script checks: Is Claude Code active?
│  ├─ YES → Add 60s to timer
│  └─ NO  → Don't add time (idle)
├─ Check: Has timer reached 300s (5 min)?
│  ├─ YES → Save context to DB, reset timer
│  └─ NO  → Continue
└─ Update state file

Active time = File changes + Claude running + Recent activity Idle time = No changes + Waiting for input + Permissions prompts

---

What Gets Saved

Every 5 minutes of active work:

{
  "context_type": "session_summary",
  "title": "Periodic Save - 2026-01-17 12:00",
  "dense_summary": "Auto-saved context after 5 minutes of active work...",
  "relevance_score": 5.0,
  "tags": ["auto-save", "periodic", "active-session"]
}

---

Monitor Activity

View Logs in Real-Time

# Windows (PowerShell)
Get-Content .claude\periodic-save.log -Tail 20 -Wait

# Git Bash
tail -f .claude/periodic-save.log

Check Task Scheduler

Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save"

---

Troubleshooting

Not Saving Contexts

Check if task is running:

Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" | Get-ScheduledTaskInfo

Check logs for errors:

tail -20 .claude/periodic-save.log

Common issues:

• JWT token expired (regenerate with python create_jwt_token.py)
• Python not in PATH (add Python to system PATH)
• API not accessible (check curl http://172.16.3.30:8001/health)

Activity Not Detected

The script looks for:

• Recent file modifications (within 2 minutes)
• Claude/Node/Code processes running
• Activity in project directories

If it's not detecting activity, check:

# Is Python finding recent file changes?
python -c "from pathlib import Path; import time; print([f.name for f in Path('.').rglob('*') if f.is_file() and f.stat().st_mtime > time.time()-120][:5])"

---

Configuration

Change Save Interval

Edit .claude/hooks/periodic_save_check.py:

SAVE_INTERVAL_SECONDS = 300  # Change to desired interval

# Common values:
# 300  = 5 minutes
# 600  = 10 minutes
# 900  = 15 minutes
# 1800 = 30 minutes

Change Check Frequency

Modify Task Scheduler trigger to run every 30 seconds or 2 minutes instead of 1 minute.

---

Uninstall

# Remove Task Scheduler task
Unregister-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" -Confirm:$false

# Optional: Remove files
Remove-Item .claude\hooks\periodic_save_check.py
Remove-Item .claude\.periodic-save-state.json
Remove-Item .claude\periodic-save.log

---

Integration

Works alongside existing hooks:

Hook	When	What It Saves
user-prompt-submit	Before each message	Recalls context
task-complete	After task done	Detailed summary
periodic_save_check	Every 5 min active	Quick checkpoint

Result: Never lose more than 5 minutes of context!

---

Current Status

✅ System is installed and working ✅ 2 contexts already saved to database ✅ Ready to set up Task Scheduler for automatic saves

---

Next Step: Run the PowerShell setup script to enable automatic periodic saves:

powershell -ExecutionPolicy Bypass -File D:\ClaudeTools\.claude\hooks\setup_periodic_save.ps1

---

Created: 2026-01-17 Tested: ✅ Working Database: 172.16.3.30:3306/claudetools