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

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

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

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:

   # Token should already be in .claude/context-recall-config.env
   cat .claude/context-recall-config.env | grep JWT_TOKEN
   

2. Start the daemon:

   python .claude/hooks/periodic_context_save.py start
   

3. Verify it's running:

   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:

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

# 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

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

Output:

{
  "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:

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

cat .claude/periodic-save.log

Common issues:

• JWT token missing or invalid
• Python not in PATH
• Permissions issue with log file

Solution:

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

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

# 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