feat: Major directory reorganization and cleanup

Reorganized project structure for better maintainability and reduced
disk usage by 95.9% (11 GB -> 451 MB).

Directory Reorganization (85% reduction in root files):
- Created docs/ with subdirectories (deployment, testing, database, etc.)
- Created infrastructure/vpn-configs/ for VPN scripts
- Moved 90+ files from root to organized locations
- Archived obsolete documentation (context system, offline mode, zombie debugging)
- Moved all test files to tests/ directory
- Root directory: 119 files -> 18 files

Disk Cleanup (10.55 GB recovered):
- Deleted Rust build artifacts: 9.6 GB (target/ directories)
- Deleted Python virtual environments: 161 MB (venv/ directories)
- Deleted Python cache: 50 KB (__pycache__/)

New Structure:
- docs/ - All documentation organized by category
- docs/archives/ - Obsolete but preserved documentation
- infrastructure/ - VPN configs and SSH setup
- tests/ - All test files consolidated
- logs/ - Ready for future logs

Benefits:
- Cleaner root directory (18 vs 119 files)
- Logical organization of documentation
- 95.9% disk space reduction
- Faster navigation and discovery
- Better portability (build artifacts excluded)

Build artifacts can be regenerated:
- Rust: cargo build --release (5-15 min per project)
- Python: pip install -r requirements.txt (2-3 min)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-01-18 20:42:28 -07:00
parent 89e5118306
commit 06f7617718
96 changed files with 54 additions and 2639 deletions

View File

@@ -0,0 +1,236 @@
# 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
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
```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
**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
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