# Periodic Context Save - Quick Start

**Auto-save context every 5 minutes of active work**

---

## [OK] System Tested and Working

The periodic context save system has been tested and is working correctly. It:
- [OK] Detects Claude Code activity
- [OK] Tracks active work time (not idle time)
- [OK] Saves context to database every 5 minutes
- [OK] Currently has 2 contexts saved

---

## Setup (One-Time)

### Option 1: Automatic Setup (Recommended)

Run this PowerShell command as Administrator:

```powershell
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:**
     - [OK] Allow task to run on batteries
     - [OK] Start task if connection is not available
     - [OK] Run task as soon as possible after missed start

---

## Verify It's Working

### Check Status

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

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

**Expected output:**
```json
{
  "active_seconds": 120,
  "last_save": "2026-01-17T19:00:32+00:00",
  "last_check": "2026-01-17T19:02:15+00:00"
}
```

### Check Database

```bash
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:

```json
{
  "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

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

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

### Check Task Scheduler

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

---

## Troubleshooting

### Not Saving Contexts

**Check if task is running:**
```powershell
Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" | Get-ScheduledTaskInfo
```

**Check logs for errors:**
```bash
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:
```bash
# 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`:

```python
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

```powershell
# 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

[OK] **System is installed and working**
[OK] **2 contexts already saved to database**
[OK] **Ready to set up Task Scheduler for automatic saves**

---

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

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

---

**Created:** 2026-01-17
**Tested:** [OK] Working
**Database:** 172.16.3.30:3306/claudetools