claudetools/.claude/PERIODIC_CONTEXT_SAVE.md

# Periodic Context Save

**Automatic context saving every 5 minutes of active work**

---

## Overview

The periodic context save daemon runs in the background and automatically saves your work context to the database every 5 minutes of active time. This ensures continuous context preservation even during long work sessions.

### Key Features

- ✅ **Active Time Tracking** - Only counts time when Claude is actively working
- ✅ **Ignores Idle Time** - Doesn't save when waiting for permissions or idle
- ✅ **Background Process** - Runs independently, doesn't interrupt work
- ✅ **Automatic Recovery** - Resumes tracking after restarts
- ✅ **Low Overhead** - Checks activity every 60 seconds

---

## How It Works

```
┌─────────────────────────────────────────────────────┐
│ Every 60 seconds:                                   │
│                                                      │
│ 1. Check if Claude Code is active                  │
│    - Recent file modifications?                     │
│    - Claude process running?                        │
│                                                      │
│ 2. If ACTIVE → Add 60s to timer                    │
│    If IDLE → Don't add time                        │
│                                                      │
│ 3. When timer reaches 300s (5 min):                │
│    - Save context to database                       │
│    - Reset timer to 0                               │
│    - Continue monitoring                            │
└─────────────────────────────────────────────────────┘
```

**Active time includes:**
- Writing code
- Running commands
- Making changes to files
- Interacting with Claude

**Idle time (not counted):**
- Waiting for user input
- Permission prompts
- No file changes or activity
- Claude process not running

---

## Usage

### Start the Daemon

```bash
python .claude/hooks/periodic_context_save.py start
```

Output:
```
Started periodic context save daemon (PID: 12345)
Logs: D:\ClaudeTools\.claude\periodic-save.log
```

### Check Status

```bash
python .claude/hooks/periodic_context_save.py status
```

Output:
```
Periodic context save daemon is running (PID: 12345)
Active time: 180s / 300s
Last save: 2026-01-17T19:05:23+00:00
```

### Stop the Daemon

```bash
python .claude/hooks/periodic_context_save.py stop
```

Output:
```
Stopped periodic context save daemon (PID: 12345)
```

---

## Installation

### One-Time Setup

1. **Ensure JWT token is configured:**
   ```bash
   # Token should already be in .claude/context-recall-config.env
   cat .claude/context-recall-config.env | grep JWT_TOKEN
   ```

2. **Start the daemon:**
   ```bash
   python .claude/hooks/periodic_context_save.py start
   ```

3. **Verify it's running:**
   ```bash
   python .claude/hooks/periodic_context_save.py status
   ```

### Auto-Start on Login (Optional)

**Windows - Task Scheduler:**

1. Open Task Scheduler
2. Create Basic Task:
   - Name: "Claude Periodic Context Save"
   - Trigger: At log on
   - Action: Start a program
   - Program: `python`
   - Arguments: `D:\ClaudeTools\.claude\hooks\periodic_context_save.py start`
   - Start in: `D:\ClaudeTools`

**Linux/Mac - systemd/launchd:**

Create a systemd service or launchd plist to start on login.

---

## What Gets Saved

Every 5 minutes of active time, the daemon saves:

```json
{
  "context_type": "session_summary",
  "title": "Periodic Save - 2026-01-17 14:30",
  "dense_summary": "Auto-saved context after 5 minutes of active work. Session in progress on project: claudetools-main",
  "relevance_score": 5.0,
  "tags": ["auto-save", "periodic", "active-session"]
}
```

**Benefits:**
- Never lose more than 5 minutes of work context
- Automatic recovery if session crashes
- Historical timeline of work sessions
- Can review what you were working on at specific times

---

## Monitoring

### View Logs

```bash
# View last 20 log lines
tail -20 .claude/periodic-save.log

# Follow logs in real-time
tail -f .claude/periodic-save.log
```

**Sample log output:**
```
[2026-01-17 14:25:00] Periodic context save daemon started
[2026-01-17 14:25:00] Will save context every 300s of active time
[2026-01-17 14:26:00] Active: 60s / 300s
[2026-01-17 14:27:00] Active: 120s / 300s
[2026-01-17 14:28:00] Claude Code inactive - not counting time
[2026-01-17 14:29:00] Active: 180s / 300s
[2026-01-17 14:30:00] Active: 240s / 300s
[2026-01-17 14:31:00] 300s of active time reached - saving context
[2026-01-17 14:31:01] ✓ Context saved successfully (ID: 1e2c3408-9146-4e98-b302-fe219280344c)
[2026-01-17 14:32:00] Active: 60s / 300s
```

### View State

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

Output:
```json
{
  "active_seconds": 180,
  "last_update": "2026-01-17T19:28:00+00:00",
  "last_save": "2026-01-17T19:26:00+00:00"
}
```

---

## Configuration

Edit the script to customize:

```python
# In periodic_context_save.py

SAVE_INTERVAL_SECONDS = 300  # Change to 600 for 10 minutes
CHECK_INTERVAL_SECONDS = 60  # How often to check activity
```

**Common configurations:**
- Every 5 minutes: `SAVE_INTERVAL_SECONDS = 300`
- Every 10 minutes: `SAVE_INTERVAL_SECONDS = 600`
- Every 15 minutes: `SAVE_INTERVAL_SECONDS = 900`

---

## Troubleshooting

### Daemon won't start

**Check logs:**
```bash
cat .claude/periodic-save.log
```

**Common issues:**
- JWT token missing or invalid
- Python not in PATH
- Permissions issue with log file

**Solution:**
```bash
# Verify JWT token exists
grep JWT_TOKEN .claude/context-recall-config.env

# Test Python
python --version

# Check permissions
ls -la .claude/
```

### Contexts not being saved

**Check:**
1. Daemon is running: `python .claude/hooks/periodic_context_save.py status`
2. JWT token is valid: Token expires after 30 days
3. API is accessible: `curl http://172.16.3.30:8001/health`
4. View logs for errors: `tail .claude/periodic-save.log`

**If JWT token expired:**
```bash
# Generate new token
python create_jwt_token.py

# Update config
# Copy new JWT_TOKEN to .claude/context-recall-config.env

# Restart daemon
python .claude/hooks/periodic_context_save.py stop
python .claude/hooks/periodic_context_save.py start
```

### Activity not being detected

The daemon uses these heuristics:
- File modifications in project directory (within last 2 minutes)
- Claude process running (on Windows)

**Improve detection:**
Modify `is_claude_active()` function to add:
- Check for recent git commits
- Monitor specific files
- Check for recent bash history

---

## Integration with Other Hooks

The periodic save works alongside existing hooks:

| Hook | Trigger | What It Saves |
|------|---------|---------------|
| **user-prompt-submit** | Before each message | Recalls context from DB |
| **task-complete** | After task completes | Rich context with decisions |
| **periodic-context-save** | Every 5min active | Quick checkpoint save |

**Result:**
- Comprehensive context coverage
- Never lose more than 5 minutes of work
- Detailed context when tasks complete
- Continuous backup of active sessions

---

## Performance Impact

**Resource Usage:**
- **CPU:** < 0.1% (checks once per minute)
- **Memory:** ~30 MB (Python process)
- **Disk:** ~2 KB per save (~25 KB/hour)
- **Network:** Minimal (single API call every 5 min)

**Impact on Claude Code:**
- None - runs as separate process
- Doesn't block or interrupt work
- No user-facing delays

---

## Uninstall

To remove periodic context save:

```bash
# Stop daemon
python .claude/hooks/periodic_context_save.py stop

# Remove files (optional)
rm .claude/hooks/periodic_context_save.py
rm .claude/.periodic-save.pid
rm .claude/.periodic-save-state.json
rm .claude/periodic-save.log

# Remove from auto-start (if configured)
# Windows: Delete from Task Scheduler
# Linux: Remove systemd service
```

---

## FAQ

**Q: Does it save when I'm idle?**
A: No - only counts active work time (file changes, Claude activity).

**Q: What if the API is down?**
A: Contexts queue locally and sync when API is restored (offline mode).

**Q: Can I change the interval?**
A: Yes - edit `SAVE_INTERVAL_SECONDS` in the script.

**Q: Does it work offline?**
A: Yes - uses the same offline queue as other hooks (v2).

**Q: How do I know it's working?**
A: Check logs: `tail .claude/periodic-save.log`

**Q: Can I run multiple instances?**
A: No - PID file prevents multiple daemons.

---

**Created:** 2026-01-17
**Version:** 1.0
**Status:** Ready for use