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:
@@ -0,0 +1,219 @@
|
||||
# Periodic Save Task - Invisible Mode Setup
|
||||
|
||||
## Problem Solved
|
||||
The `periodic_save_check.py` Task Scheduler task was showing a flashing console window every minute. This has been fixed by configuring the task to run completely invisibly.
|
||||
|
||||
---
|
||||
|
||||
## What Changed
|
||||
|
||||
### 1. Updated Setup Script
|
||||
**File:** `D:\ClaudeTools\.claude\hooks\setup_periodic_save.ps1`
|
||||
|
||||
**Changes:**
|
||||
- Uses `pythonw.exe` instead of `python.exe` (no console window)
|
||||
- Added `-Hidden` flag to task settings
|
||||
- Changed LogonType from `Interactive` to `S4U` (Service-For-User = background)
|
||||
- Added verification instructions in output
|
||||
|
||||
### 2. Created Update Script
|
||||
**File:** `D:\ClaudeTools\.claude\hooks\update_to_invisible.ps1`
|
||||
|
||||
**Purpose:**
|
||||
- Quick one-command update for existing tasks
|
||||
- Preserves existing triggers and settings
|
||||
- Validates pythonw.exe exists
|
||||
- Shows verification output
|
||||
|
||||
### 3. Created Documentation
|
||||
**File:** `D:\ClaudeTools\.claude\PERIODIC_SAVE_INVISIBLE_SETUP.md`
|
||||
|
||||
**Contents:**
|
||||
- Automatic setup instructions
|
||||
- Manual update procedures (PowerShell and GUI)
|
||||
- Verification steps
|
||||
- Troubleshooting guide
|
||||
|
||||
---
|
||||
|
||||
## How to Fix Your Current Task
|
||||
|
||||
### Option 1: Automatic (Recommended)
|
||||
|
||||
Run the update script:
|
||||
|
||||
```powershell
|
||||
# From PowerShell in D:\ClaudeTools
|
||||
.\.claude\hooks\update_to_invisible.ps1
|
||||
```
|
||||
|
||||
This will:
|
||||
- Find pythonw.exe automatically
|
||||
- Update the task to use pythonw.exe
|
||||
- Set the task to run hidden
|
||||
- Verify all settings are correct
|
||||
|
||||
### Option 2: Recreate Task
|
||||
|
||||
Re-run the setup script (removes old task and creates new one):
|
||||
|
||||
```powershell
|
||||
# From PowerShell in D:\ClaudeTools
|
||||
.\.claude\hooks\setup_periodic_save.ps1
|
||||
```
|
||||
|
||||
### Option 3: Manual (GUI)
|
||||
|
||||
1. Open Task Scheduler (Win + R → `taskschd.msc`)
|
||||
2. Find "ClaudeTools - Periodic Context Save"
|
||||
3. Right-click → Properties
|
||||
4. **Actions tab:** Change `python.exe` to `pythonw.exe`
|
||||
5. **General tab:** Check "Hidden" checkbox
|
||||
6. Click OK
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
After updating, verify the task is configured correctly:
|
||||
|
||||
```powershell
|
||||
# Quick verification
|
||||
Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" |
|
||||
Select-Object -ExpandProperty Actions |
|
||||
Select-Object Execute
|
||||
|
||||
# Should show: ...pythonw.exe (NOT python.exe)
|
||||
|
||||
# Check hidden setting
|
||||
Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" |
|
||||
Select-Object -ExpandProperty Settings |
|
||||
Select-Object Hidden
|
||||
|
||||
# Should show: Hidden: True
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### pythonw.exe vs python.exe
|
||||
|
||||
| Executable | Console Window | Use Case |
|
||||
|------------|---------------|----------|
|
||||
| `python.exe` | Shows console | Interactive scripts, debugging |
|
||||
| `pythonw.exe` | No console | Background tasks, GUI apps |
|
||||
|
||||
### Task Scheduler Settings
|
||||
|
||||
| Setting | Old Value | New Value | Purpose |
|
||||
|---------|-----------|-----------|---------|
|
||||
| Executable | python.exe | pythonw.exe | No console window |
|
||||
| Hidden | False | True | Hide from task list |
|
||||
| LogonType | Interactive | S4U | Run in background |
|
||||
|
||||
### What is S4U (Service-For-User)?
|
||||
|
||||
- Runs tasks in background session
|
||||
- No interactive window
|
||||
- Doesn't require user to be logged in
|
||||
- Ideal for background automation
|
||||
|
||||
---
|
||||
|
||||
## Files Modified/Created
|
||||
|
||||
### Modified
|
||||
- `D:\ClaudeTools\.claude\hooks\setup_periodic_save.ps1`
|
||||
- Lines 9-18: Auto-detect pythonw.exe path
|
||||
- Line 29: Use pythonw.exe instead of python.exe
|
||||
- Line 43: Added `-Hidden` flag
|
||||
- Line 46: Changed LogonType to S4U
|
||||
- Lines 59-64: Updated output messages
|
||||
|
||||
### Created
|
||||
- `D:\ClaudeTools\.claude\hooks\update_to_invisible.ps1`
|
||||
- Quick update script for existing tasks
|
||||
|
||||
- `D:\ClaudeTools\.claude\PERIODIC_SAVE_INVISIBLE_SETUP.md`
|
||||
- Complete setup and troubleshooting guide
|
||||
|
||||
- `D:\ClaudeTools\INVISIBLE_PERIODIC_SAVE_SUMMARY.md`
|
||||
- This file - quick reference summary
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
After updating, the task will run every minute but you should see:
|
||||
- ✓ No console window flashing
|
||||
- ✓ No visible task execution
|
||||
- ✓ Logs still being written to `D:\ClaudeTools\.claude\periodic-save.log`
|
||||
|
||||
Check logs to verify it's working:
|
||||
|
||||
```powershell
|
||||
Get-Content D:\ClaudeTools\.claude\periodic-save.log -Tail 20
|
||||
```
|
||||
|
||||
You should see log entries appearing every minute (when Claude is active) without any visible window.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Still seeing console window?
|
||||
|
||||
**Check executable:**
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" |
|
||||
Select-Object -ExpandProperty Actions
|
||||
```
|
||||
- If shows `python.exe` - update didn't work, try manual update
|
||||
- If shows `pythonw.exe` - should be invisible (check hidden setting)
|
||||
|
||||
**Check hidden setting:**
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" |
|
||||
Select-Object -ExpandProperty Settings |
|
||||
Select-Object Hidden
|
||||
```
|
||||
- Should show `Hidden: True`
|
||||
- If False, run update script again
|
||||
|
||||
**Check LogonType:**
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ClaudeTools - Periodic Context Save" |
|
||||
Select-Object -ExpandProperty Principal
|
||||
```
|
||||
- Should show `LogonType: S4U`
|
||||
- If Interactive, run update script again
|
||||
|
||||
### pythonw.exe not found?
|
||||
|
||||
```powershell
|
||||
# Check Python installation
|
||||
Get-Command python | Select-Object -ExpandProperty Source
|
||||
|
||||
# Check if pythonw.exe exists in same directory
|
||||
$PythonPath = (Get-Command python).Source
|
||||
$PythonDir = Split-Path $PythonPath -Parent
|
||||
Test-Path (Join-Path $PythonDir "pythonw.exe")
|
||||
```
|
||||
|
||||
If False, reinstall Python. pythonw.exe should always come with Python on Windows.
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
**Task Name:** ClaudeTools - Periodic Context Save
|
||||
**Frequency:** Every 1 minute
|
||||
**Action:** Check activity, save context every 5 minutes of active work
|
||||
**Visibility:** Hidden (no console window)
|
||||
**Logs:** `D:\ClaudeTools\.claude\periodic-save.log`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Updated Files:** 1 modified, 3 created
|
||||
728
docs/archives/offline-mode-removed/OFFLINE_MODE_COMPLETE.md
Normal file
728
docs/archives/offline-mode-removed/OFFLINE_MODE_COMPLETE.md
Normal file
@@ -0,0 +1,728 @@
|
||||
# Offline Mode Implementation - Complete ✅
|
||||
|
||||
**Date:** 2026-01-17
|
||||
**Status:** COMPLETE
|
||||
**Version:** 2.0 (Offline-Capable Context Recall)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
ClaudeTools Context Recall System has been successfully upgraded to support **full offline operation** with automatic synchronization. The system now gracefully handles network outages, server maintenance, and connectivity issues without data loss.
|
||||
|
||||
---
|
||||
|
||||
## What Was Accomplished
|
||||
|
||||
### ✅ Complete Offline Support
|
||||
|
||||
**Before (V1):**
|
||||
- Context recall only worked when API was available
|
||||
- Contexts were silently lost when API failed
|
||||
- No fallback mechanism
|
||||
- No data resilience
|
||||
|
||||
**After (V2):**
|
||||
- **Offline Reading:** Falls back to local cache when API unavailable
|
||||
- **Offline Writing:** Queues contexts locally when API unavailable
|
||||
- **Automatic Sync:** Background synchronization when API restored
|
||||
- **Zero Data Loss:** All contexts preserved and eventually uploaded
|
||||
|
||||
### ✅ Infrastructure Created
|
||||
|
||||
**New Directories:**
|
||||
```
|
||||
.claude/
|
||||
├── context-cache/ # Downloaded contexts for offline reading
|
||||
│ └── [project-id]/
|
||||
│ ├── latest.json # Most recent contexts from API
|
||||
│ └── last_updated # Cache timestamp
|
||||
└── context-queue/ # Pending contexts to upload
|
||||
├── pending/ # Contexts waiting to upload
|
||||
├── uploaded/ # Successfully synced (auto-cleaned)
|
||||
└── failed/ # Failed uploads (manual review needed)
|
||||
```
|
||||
|
||||
**Git Protection:**
|
||||
```gitignore
|
||||
# Added to .gitignore
|
||||
.claude/context-cache/
|
||||
.claude/context-queue/
|
||||
```
|
||||
|
||||
### ✅ Enhanced Hooks (V2)
|
||||
|
||||
**1. user-prompt-submit (v2)**
|
||||
- Tries API with 3-second timeout
|
||||
- Falls back to local cache if API unavailable
|
||||
- Shows clear "Offline Mode" warning
|
||||
- Updates cache on successful API fetch
|
||||
- **Location:** `.claude/hooks/user-prompt-submit`
|
||||
|
||||
**2. task-complete (v2)**
|
||||
- Tries API save with 5-second timeout
|
||||
- Queues locally if API unavailable
|
||||
- Triggers background sync (opportunistic)
|
||||
- Shows clear warning when queuing
|
||||
- **Location:** `.claude/hooks/task-complete`
|
||||
|
||||
**3. sync-contexts (new)**
|
||||
- Uploads queued contexts to API
|
||||
- Moves successful uploads to `uploaded/`
|
||||
- Moves failed uploads to `failed/`
|
||||
- Auto-cleans old uploaded contexts
|
||||
- Can run manually or automatically
|
||||
- **Location:** `.claude/hooks/sync-contexts`
|
||||
|
||||
### ✅ Documentation Created
|
||||
|
||||
1. **`.claude/OFFLINE_MODE.md`** (481 lines)
|
||||
- Complete architecture documentation
|
||||
- How it works (online, offline, sync modes)
|
||||
- Directory structure explanation
|
||||
- Usage guide with examples
|
||||
- Migration from V1 to V2
|
||||
- Troubleshooting guide
|
||||
- Performance & security considerations
|
||||
- FAQ section
|
||||
|
||||
2. **`OFFLINE_MODE_TEST_PROCEDURE.md`** (517 lines)
|
||||
- 5-phase test plan
|
||||
- Step-by-step instructions
|
||||
- Expected outputs documented
|
||||
- Results template
|
||||
- Quick reference commands
|
||||
- Troubleshooting section
|
||||
|
||||
3. **`OFFLINE_MODE_VERIFICATION.md`** (520+ lines)
|
||||
- Component verification checklist
|
||||
- Before/after comparison
|
||||
- User experience examples
|
||||
- Security & privacy analysis
|
||||
- Readiness confirmation
|
||||
|
||||
4. **`scripts/upgrade-to-offline-mode.sh`** (170 lines)
|
||||
- Automated upgrade from V1 to V2
|
||||
- Backs up existing hooks
|
||||
- Creates directory structure
|
||||
- Updates .gitignore
|
||||
- Verifies installation
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Online Mode (Normal Operation)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ User sends message to Claude Code │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ user-prompt-submit hook executes │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 1. Fetch context from API (http://172.16.3.30:8001) │
|
||||
│ 2. Save response to cache (.claude/context-cache/) │
|
||||
│ 3. Update timestamp (last_updated) │
|
||||
│ 4. Inject context into conversation │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Claude processes request with context │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Task completes │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ task-complete hook executes │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 1. POST context to API │
|
||||
│ 2. Receive success (HTTP 200/201) │
|
||||
│ 3. Display: "✓ Context saved to database" │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Offline Mode (API Unavailable)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ User sends message to Claude Code │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ user-prompt-submit hook executes │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 1. Try API fetch → TIMEOUT after 3 seconds │
|
||||
│ 2. Fall back to local cache │
|
||||
│ 3. Read: .claude/context-cache/[project]/latest.json │
|
||||
│ 4. Inject cached context with warning │
|
||||
│ "⚠️ Offline Mode - Using cached context" │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Claude processes with cached context │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Task completes │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ task-complete hook executes │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 1. Try POST to API → TIMEOUT after 5 seconds │
|
||||
│ 2. Queue locally to pending/ │
|
||||
│ 3. Save: pending/[project]_[timestamp]_context.json │
|
||||
│ 4. Display: "⚠ Context queued locally" │
|
||||
│ 5. Trigger background sync (opportunistic) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Sync Mode (API Restored)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ API becomes available again │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Next user interaction OR manual sync command │
|
||||
└────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ sync-contexts script executes (background) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 1. Scan .claude/context-queue/pending/*.json │
|
||||
│ 2. For each queued context: │
|
||||
│ - POST to API with JWT auth │
|
||||
│ - On success: move to uploaded/ │
|
||||
│ - On failure: move to failed/ │
|
||||
│ 3. Clean up uploaded/ (keep last 100) │
|
||||
│ 4. Display sync summary │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Experience
|
||||
|
||||
### Scenario 1: Working Online
|
||||
|
||||
```
|
||||
You: "Add a new feature to the API"
|
||||
|
||||
[Hook fetches context from API in < 1 second]
|
||||
[Context injected - Claude remembers previous work]
|
||||
|
||||
Claude: "I'll add that feature. I see from our previous session
|
||||
that we're using FastAPI with SQLAlchemy 2.0..."
|
||||
|
||||
[Task completes]
|
||||
[Hook saves context to API]
|
||||
Message: "✓ Context saved to database"
|
||||
```
|
||||
|
||||
### Scenario 2: Working Offline
|
||||
|
||||
```
|
||||
You: "Continue working on the API"
|
||||
|
||||
[API unavailable - hook uses cache]
|
||||
Message: "⚠️ Offline Mode - Using cached context (API unavailable)"
|
||||
|
||||
Claude: "I'll continue the work. Based on cached context from
|
||||
2 hours ago, we were implementing the authentication
|
||||
endpoints..."
|
||||
|
||||
[Task completes]
|
||||
[Hook queues context locally]
|
||||
Message: "⚠ Context queued locally (API unavailable) - will sync when online"
|
||||
|
||||
[Later, when API restored]
|
||||
[Background sync automatically uploads queued context]
|
||||
Message: "✓ Synced 1 context(s)"
|
||||
```
|
||||
|
||||
### Scenario 3: First Run (No Cache)
|
||||
|
||||
```
|
||||
You: "Help me with this project"
|
||||
|
||||
[No cache exists yet, hook exits silently]
|
||||
|
||||
Claude: "I'd be happy to help! Tell me more about your project..."
|
||||
|
||||
[Task completes]
|
||||
[Hook saves context to API - cache created]
|
||||
Message: "✓ Context saved to database"
|
||||
|
||||
[Next time, context will be available]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
### 1. Intelligent Fallback
|
||||
|
||||
- **3-second API timeout** for context fetch (user-prompt-submit)
|
||||
- **5-second API timeout** for context save (task-complete)
|
||||
- **Immediate fallback** to local cache/queue
|
||||
- **No blocking** - user never waits for failed API calls
|
||||
|
||||
### 2. Zero Data Loss
|
||||
|
||||
- **Cache persists** until replaced by newer API fetch
|
||||
- **Queue persists** until successfully uploaded
|
||||
- **Failed uploads** moved to `failed/` for manual review
|
||||
- **Automatic retry** on next sync attempt
|
||||
|
||||
### 3. Transparent Operation
|
||||
|
||||
- **Clear warnings** when using cache ("Offline Mode")
|
||||
- **Clear warnings** when queuing ("will sync when online")
|
||||
- **Success messages** when online ("Context saved to database")
|
||||
- **Sync summaries** showing upload results
|
||||
|
||||
### 4. Automatic Maintenance
|
||||
|
||||
- **Background sync** triggered on next user interaction
|
||||
- **Auto-cleanup** of uploaded contexts (keeps last 100)
|
||||
- **Cache refresh** on every successful API call
|
||||
- **No manual intervention** required
|
||||
|
||||
---
|
||||
|
||||
## Testing Status
|
||||
|
||||
### ✅ Component Verification Complete
|
||||
|
||||
All components have been installed and verified:
|
||||
|
||||
1. ✅ **V2 Hooks Installed**
|
||||
- user-prompt-submit (v2 with offline support)
|
||||
- task-complete (v2 with offline support)
|
||||
- sync-contexts (new sync script)
|
||||
|
||||
2. ✅ **Directory Structure Created**
|
||||
- .claude/context-cache/ (for offline reading)
|
||||
- .claude/context-queue/pending/ (for queued saves)
|
||||
- .claude/context-queue/uploaded/ (successful syncs)
|
||||
- .claude/context-queue/failed/ (failed syncs)
|
||||
|
||||
3. ✅ **Configuration Updated**
|
||||
- API URL: http://172.16.3.30:8001 (centralized)
|
||||
- .gitignore: cache and queue excluded
|
||||
|
||||
4. ✅ **API Health Verified**
|
||||
- API online and healthy
|
||||
- Database connected
|
||||
- Endpoints accessible
|
||||
|
||||
### 📋 Live Testing Procedure Available
|
||||
|
||||
Complete test procedure documented in `OFFLINE_MODE_TEST_PROCEDURE.md`:
|
||||
|
||||
**Test Phases:**
|
||||
1. Phase 1: Baseline (online mode verification)
|
||||
2. Phase 2: Offline mode (cache fallback test)
|
||||
3. Phase 3: Context queuing (save fallback test)
|
||||
4. Phase 4: Automatic sync (restore and upload test)
|
||||
5. Phase 5: Cache refresh (force refresh test)
|
||||
|
||||
**To run tests:**
|
||||
```bash
|
||||
# Review test procedure
|
||||
cat OFFLINE_MODE_TEST_PROCEDURE.md
|
||||
|
||||
# When ready, follow phase-by-phase instructions
|
||||
# (Requires SSH access to stop/start API)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Normal Operation (No Action Required)
|
||||
|
||||
The system works automatically - no commands needed:
|
||||
|
||||
1. **Open Claude Code** in any ClaudeTools directory
|
||||
2. **Send messages** - context recalled automatically
|
||||
3. **Complete tasks** - context saved automatically
|
||||
4. **Work offline** - system falls back gracefully
|
||||
5. **Go back online** - system syncs automatically
|
||||
|
||||
### Manual Commands (Optional)
|
||||
|
||||
**Force sync queued contexts:**
|
||||
```bash
|
||||
bash .claude/hooks/sync-contexts
|
||||
```
|
||||
|
||||
**View cached context:**
|
||||
```bash
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
cat .claude/context-cache/$PROJECT_ID/latest.json | python -m json.tool
|
||||
```
|
||||
|
||||
**Check queue status:**
|
||||
```bash
|
||||
ls -la .claude/context-queue/pending/ # Waiting to upload
|
||||
ls -la .claude/context-queue/uploaded/ # Successfully synced
|
||||
ls -la .claude/context-queue/failed/ # Need review
|
||||
```
|
||||
|
||||
**Clear cache (force refresh):**
|
||||
```bash
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
rm -rf .claude/context-cache/$PROJECT_ID
|
||||
# Next message will fetch fresh context from API
|
||||
```
|
||||
|
||||
**Manual sync with output:**
|
||||
```bash
|
||||
bash .claude/hooks/sync-contexts
|
||||
|
||||
# Example output:
|
||||
# ===================================
|
||||
# Syncing Queued Contexts
|
||||
# ===================================
|
||||
# Found 2 pending context(s)
|
||||
#
|
||||
# Processing: claudetools_20260117_140122_context.json
|
||||
# ✓ Uploaded successfully
|
||||
# Processing: claudetools_20260117_141533_state.json
|
||||
# ✓ Uploaded successfully
|
||||
#
|
||||
# ===================================
|
||||
# Sync Complete
|
||||
# ===================================
|
||||
# Successful: 2
|
||||
# Failed: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Benefits
|
||||
|
||||
### 1. Data Resilience
|
||||
|
||||
**Problem Solved:**
|
||||
- Network outages no longer cause data loss
|
||||
- Server maintenance doesn't interrupt work
|
||||
- Connectivity issues handled gracefully
|
||||
|
||||
**How:**
|
||||
- Local cache preserves last known state
|
||||
- Local queue preserves unsaved changes
|
||||
- Automatic sync when restored
|
||||
|
||||
### 2. Improved User Experience
|
||||
|
||||
**Problem Solved:**
|
||||
- Silent failures confused users
|
||||
- No feedback when offline
|
||||
- Lost work when API down
|
||||
|
||||
**How:**
|
||||
- Clear "Offline Mode" warnings
|
||||
- Status messages for all operations
|
||||
- Transparent fallback behavior
|
||||
|
||||
### 3. Centralized Architecture Compatible
|
||||
|
||||
**Problem Solved:**
|
||||
- Centralized API requires network
|
||||
- Single point of failure
|
||||
- No local redundancy
|
||||
|
||||
**How:**
|
||||
- Local cache provides redundancy
|
||||
- Queue enables async operation
|
||||
- Works with or without network
|
||||
|
||||
### 4. Zero Configuration
|
||||
|
||||
**Problem Solved:**
|
||||
- Complex setup procedures
|
||||
- Manual intervention needed
|
||||
- User doesn't understand system
|
||||
|
||||
**How:**
|
||||
- Automatic detection of offline state
|
||||
- Automatic fallback and sync
|
||||
- Transparent operation
|
||||
|
||||
---
|
||||
|
||||
## Security & Privacy
|
||||
|
||||
### What's Cached Locally
|
||||
|
||||
**Safe to Cache:**
|
||||
- ✅ Context summaries (compressed, not full transcripts)
|
||||
- ✅ Titles and tags
|
||||
- ✅ Relevance scores
|
||||
- ✅ Project IDs (hashes)
|
||||
- ✅ Timestamps
|
||||
|
||||
**Never Cached:**
|
||||
- ❌ JWT tokens (in separate config file)
|
||||
- ❌ Database credentials
|
||||
- ❌ User passwords
|
||||
- ❌ Full conversation transcripts
|
||||
- ❌ Sensitive credential data
|
||||
|
||||
### Git Protection
|
||||
|
||||
```gitignore
|
||||
# Automatically added to .gitignore
|
||||
.claude/context-cache/ # Local cache - don't commit
|
||||
.claude/context-queue/ # Local queue - don't commit
|
||||
```
|
||||
|
||||
**Result:** No accidental commits of local data
|
||||
|
||||
### File Permissions
|
||||
|
||||
- Directories created with user-only access
|
||||
- No group or world readable permissions
|
||||
- Only current user can access cache/queue
|
||||
|
||||
### Cleanup
|
||||
|
||||
- **Uploaded queue:** Auto-cleaned (keeps last 100)
|
||||
- **Cache:** Replaced on each API fetch
|
||||
- **Failed:** Manual review available
|
||||
|
||||
---
|
||||
|
||||
## What Changed in Your System
|
||||
|
||||
### Before This Session
|
||||
|
||||
**System:**
|
||||
- V1 hooks (API-only, no fallback)
|
||||
- No local storage
|
||||
- Silent failures
|
||||
- Data loss when offline
|
||||
|
||||
**User Experience:**
|
||||
- "Where did my context go?"
|
||||
- "Why doesn't Claude remember?"
|
||||
- "The API was down, I lost everything"
|
||||
|
||||
### After This Session
|
||||
|
||||
**System:**
|
||||
- V2 hooks (offline-capable)
|
||||
- Local cache and queue
|
||||
- Clear warnings and status
|
||||
- Zero data loss
|
||||
|
||||
**User Experience:**
|
||||
- "Working offline - using cached context"
|
||||
- "Context queued - will sync later"
|
||||
- "Everything synced automatically"
|
||||
|
||||
---
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
### Created (New Files)
|
||||
|
||||
1. `.claude/hooks/sync-contexts` - Sync script
|
||||
2. `.claude/OFFLINE_MODE.md` - Architecture docs
|
||||
3. `OFFLINE_MODE_TEST_PROCEDURE.md` - Test guide
|
||||
4. `OFFLINE_MODE_VERIFICATION.md` - Verification report
|
||||
5. `OFFLINE_MODE_COMPLETE.md` - This summary
|
||||
6. `scripts/upgrade-to-offline-mode.sh` - Upgrade script
|
||||
7. `.claude/context-cache/` - Cache directory (empty)
|
||||
8. `.claude/context-queue/` - Queue directories (empty)
|
||||
|
||||
### Modified (Updated Files)
|
||||
|
||||
1. `.claude/hooks/user-prompt-submit` - Upgraded to v2
|
||||
2. `.claude/hooks/task-complete` - Upgraded to v2
|
||||
3. `.gitignore` - Added cache and queue exclusions
|
||||
|
||||
### Backed Up (Previous Versions)
|
||||
|
||||
The upgrade script creates backups automatically:
|
||||
- `.claude/hooks/backup_[timestamp]/user-prompt-submit` (v1)
|
||||
- `.claude/hooks/backup_[timestamp]/task-complete` (v1)
|
||||
|
||||
---
|
||||
|
||||
## Performance Impact
|
||||
|
||||
### Storage
|
||||
|
||||
- **Cache per project:** ~10-50 KB
|
||||
- **Queue per context:** ~1-2 KB
|
||||
- **Total impact:** Negligible (< 1 MB typical)
|
||||
|
||||
### Speed
|
||||
|
||||
- **Cache read:** < 100ms (instant)
|
||||
- **Queue write:** < 100ms (instant)
|
||||
- **Sync per context:** ~0.5 seconds
|
||||
- **Background sync:** Non-blocking
|
||||
|
||||
### Network
|
||||
|
||||
- **API timeout (read):** 3 seconds max
|
||||
- **API timeout (write):** 5 seconds max
|
||||
- **Sync traffic:** Minimal (POST requests only)
|
||||
|
||||
**Result:** No noticeable performance impact
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### System is Ready for Production Use
|
||||
|
||||
**No action required** - the system is fully operational:
|
||||
|
||||
1. ✅ All components installed
|
||||
2. ✅ All hooks upgraded to v2
|
||||
3. ✅ All documentation complete
|
||||
4. ✅ API verified healthy
|
||||
5. ✅ Configuration correct
|
||||
|
||||
### Optional: Live Testing
|
||||
|
||||
If you want to verify offline mode works:
|
||||
|
||||
1. Review test procedure:
|
||||
```bash
|
||||
cat OFFLINE_MODE_TEST_PROCEDURE.md
|
||||
```
|
||||
|
||||
2. Run Phase 1 (Baseline):
|
||||
- Use Claude Code normally
|
||||
- Verify cache created
|
||||
|
||||
3. Run Phase 2-4 (Offline Test):
|
||||
- Stop API: `ssh guru@172.16.3.30 sudo systemctl stop claudetools-api`
|
||||
- Use Claude Code (verify cache fallback)
|
||||
- Restart API: `ssh guru@172.16.3.30 sudo systemctl start claudetools-api`
|
||||
- Verify sync
|
||||
|
||||
### Optional: Setup Other Machines
|
||||
|
||||
When setting up ClaudeTools on another machine:
|
||||
|
||||
```bash
|
||||
# Clone repo
|
||||
git clone [repo-url] D:\ClaudeTools
|
||||
cd D:\ClaudeTools
|
||||
|
||||
# Run 30-second setup
|
||||
bash scripts/setup-new-machine.sh
|
||||
|
||||
# Done! Offline support included automatically
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support & Troubleshooting
|
||||
|
||||
### Quick Diagnostics
|
||||
|
||||
**Check system status:**
|
||||
```bash
|
||||
# Verify v2 hooks installed
|
||||
head -3 .claude/hooks/user-prompt-submit # Should show "v2 - with offline support"
|
||||
|
||||
# Check API health
|
||||
curl -s http://172.16.3.30:8001/health # Should show {"status":"healthy"}
|
||||
|
||||
# Check cache exists
|
||||
ls -la .claude/context-cache/
|
||||
|
||||
# Check queue
|
||||
ls -la .claude/context-queue/pending/
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue:** Offline mode not activating
|
||||
```bash
|
||||
# Verify v2 hooks installed
|
||||
grep "v2 - with offline support" .claude/hooks/user-prompt-submit
|
||||
# If not found, run: bash scripts/upgrade-to-offline-mode.sh
|
||||
```
|
||||
|
||||
**Issue:** Contexts not syncing
|
||||
```bash
|
||||
# Check JWT token exists
|
||||
grep JWT_TOKEN .claude/context-recall-config.env
|
||||
|
||||
# Run manual sync
|
||||
bash .claude/hooks/sync-contexts
|
||||
```
|
||||
|
||||
**Issue:** Cache is stale
|
||||
```bash
|
||||
# Clear cache to force refresh
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
rm -rf .claude/context-cache/$PROJECT_ID
|
||||
# Next Claude Code message will fetch fresh
|
||||
```
|
||||
|
||||
### Documentation References
|
||||
|
||||
- **Architecture:** `.claude/OFFLINE_MODE.md`
|
||||
- **Testing:** `OFFLINE_MODE_TEST_PROCEDURE.md`
|
||||
- **Verification:** `OFFLINE_MODE_VERIFICATION.md`
|
||||
- **Setup:** `scripts/upgrade-to-offline-mode.sh`
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
### ✅ Mission Accomplished
|
||||
|
||||
Your request has been fully completed:
|
||||
|
||||
> "Verify all the local code to make sure it complies with the new setup for dynamic storage and retrieval of context and all other data. Also verify it has a fallback to local storage with a complete sync once database is functional."
|
||||
|
||||
**Completed:**
|
||||
1. ✅ Verified local code complies with centralized API setup
|
||||
2. ✅ Implemented complete fallback to local storage (cache + queue)
|
||||
3. ✅ Implemented complete sync mechanism (automatic + manual)
|
||||
4. ✅ Verified all components installed and ready
|
||||
5. ✅ Created comprehensive documentation
|
||||
|
||||
### 🎯 Results
|
||||
|
||||
**ClaudeTools Context Recall System v2.0:**
|
||||
- **Status:** Production Ready
|
||||
- **Offline Support:** Fully Implemented
|
||||
- **Data Loss:** Zero
|
||||
- **User Action Required:** None
|
||||
- **Documentation:** Complete
|
||||
|
||||
The system now provides **enterprise-grade reliability** with automatic offline fallback and seamless synchronization. Context is never lost, even during network outages or server maintenance.
|
||||
|
||||
---
|
||||
|
||||
**Implementation Date:** 2026-01-17
|
||||
**System Version:** 2.0 (Offline-Capable)
|
||||
**Status:** ✅ COMPLETE AND OPERATIONAL
|
||||
@@ -0,0 +1,445 @@
|
||||
# Offline Mode Test Procedure
|
||||
|
||||
**Version:** 2.0
|
||||
**Date:** 2026-01-17
|
||||
**System Status:** ✅ All Components Installed and Ready
|
||||
|
||||
---
|
||||
|
||||
## Pre-Test Verification (COMPLETED)
|
||||
|
||||
### ✅ Infrastructure Check
|
||||
```bash
|
||||
# Verified directories exist
|
||||
ls -la .claude/context-cache/ # ✅ Exists
|
||||
ls -la .claude/context-queue/ # ✅ Exists (pending, uploaded, failed)
|
||||
|
||||
# Verified v2 hooks installed
|
||||
head -3 .claude/hooks/user-prompt-submit # ✅ v2 with offline support
|
||||
head -3 .claude/hooks/task-complete # ✅ v2 with offline support
|
||||
head -3 .claude/hooks/sync-contexts # ✅ Sync script ready
|
||||
|
||||
# Verified configuration
|
||||
grep CLAUDE_API_URL .claude/context-recall-config.env
|
||||
# ✅ Output: CLAUDE_API_URL=http://172.16.3.30:8001
|
||||
|
||||
# Verified gitignore
|
||||
grep context-cache .gitignore # ✅ Present
|
||||
grep context-queue .gitignore # ✅ Present
|
||||
```
|
||||
|
||||
### ✅ Current System Status
|
||||
- **API:** http://172.16.3.30:8001 (ONLINE)
|
||||
- **Database:** 172.16.3.30:3306 (ONLINE)
|
||||
- **Health Check:** {"status":"healthy","database":"connected"}
|
||||
- **Hooks:** V2 (offline-capable)
|
||||
- **Storage:** Ready
|
||||
|
||||
---
|
||||
|
||||
## Test Procedure
|
||||
|
||||
### Phase 1: Baseline Test (Online Mode)
|
||||
|
||||
**Purpose:** Verify normal operation before testing offline
|
||||
|
||||
```bash
|
||||
# 1. Open Claude Code in D:\ClaudeTools
|
||||
cd D:\ClaudeTools
|
||||
|
||||
# 2. Send a test message to Claude
|
||||
# Expected output should include:
|
||||
# <!-- Context Recall: Retrieved X relevant context(s) from API -->
|
||||
# ## 📚 Previous Context
|
||||
|
||||
# 3. Check that context was cached
|
||||
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null || git config --get remote.origin.url | md5sum | cut -d' ' -f1)
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
# Expected: latest.json and last_updated files
|
||||
|
||||
# 4. Verify cache contents
|
||||
cat .claude/context-cache/$PROJECT_ID/latest.json | python -m json.tool
|
||||
# Expected: Array of context objects with titles, summaries, scores
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Context retrieved from API
|
||||
- ✅ Cache file created with timestamp
|
||||
- ✅ Context injected into conversation
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Offline Mode Test (Cache Fallback)
|
||||
|
||||
**Purpose:** Verify system uses cached context when API unavailable
|
||||
|
||||
```bash
|
||||
# 1. SSH to RMM server
|
||||
ssh guru@172.16.3.30
|
||||
|
||||
# 2. Stop the API service
|
||||
sudo systemctl stop claudetools-api
|
||||
|
||||
# 3. Verify API is stopped
|
||||
sudo systemctl status claudetools-api --no-pager
|
||||
# Expected: Active: inactive (dead)
|
||||
|
||||
# 4. Exit SSH
|
||||
exit
|
||||
|
||||
# 5. Back on Windows - test context recall
|
||||
# Open Claude Code and send a message
|
||||
|
||||
# Expected output:
|
||||
# <!-- Context Recall: Retrieved X relevant context(s) from LOCAL CACHE (offline mode) -->
|
||||
# ## 📚 Previous Context
|
||||
# ⚠️ **Offline Mode** - Using cached context (API unavailable)
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Hook detects API unavailable
|
||||
- ✅ Falls back to cached context
|
||||
- ✅ Clear "Offline Mode" warning displayed
|
||||
- ✅ Conversation continues with cached context
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Context Queuing Test (Save Fallback)
|
||||
|
||||
**Purpose:** Verify contexts queue locally when API unavailable
|
||||
|
||||
```bash
|
||||
# 1. API should still be stopped from Phase 2
|
||||
|
||||
# 2. Complete a task in Claude Code
|
||||
# (This triggers task-complete hook)
|
||||
|
||||
# Expected stderr output:
|
||||
# ⚠ Context queued locally (API unavailable) - will sync when online
|
||||
|
||||
# 3. Check queue directory
|
||||
ls -la .claude/context-queue/pending/
|
||||
# Expected: One or more .json files with timestamp names
|
||||
# Example: claudetools_20260117_143022_context.json
|
||||
|
||||
# 4. View queued context
|
||||
cat .claude/context-queue/pending/*.json | python -m json.tool
|
||||
# Expected: JSON with project_id, context_type, title, dense_summary, etc.
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Context save attempt fails gracefully
|
||||
- ✅ Context queued in pending/ directory
|
||||
- ✅ User warned about offline queuing
|
||||
- ✅ No data loss
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Automatic Sync Test
|
||||
|
||||
**Purpose:** Verify queued contexts sync when API restored
|
||||
|
||||
```bash
|
||||
# 1. SSH to RMM server
|
||||
ssh guru@172.16.3.30
|
||||
|
||||
# 2. Start the API service
|
||||
sudo systemctl start claudetools-api
|
||||
|
||||
# 3. Verify API is running
|
||||
sudo systemctl status claudetools-api --no-pager
|
||||
# Expected: Active: active (running)
|
||||
|
||||
# 4. Test API health
|
||||
curl http://localhost:8001/health
|
||||
# Expected: {"status":"healthy","database":"connected"}
|
||||
|
||||
# 5. Exit SSH
|
||||
exit
|
||||
|
||||
# 6. Back on Windows - trigger sync
|
||||
# Method A: Send any message in Claude Code (automatic background sync)
|
||||
# Method B: Manual sync command
|
||||
bash .claude/hooks/sync-contexts
|
||||
|
||||
# Expected output from manual sync:
|
||||
# ===================================
|
||||
# Syncing Queued Contexts
|
||||
# ===================================
|
||||
# Found X pending context(s)
|
||||
#
|
||||
# Processing: [filename].json
|
||||
# ✓ Uploaded successfully
|
||||
#
|
||||
# ===================================
|
||||
# Sync Complete
|
||||
# ===================================
|
||||
# Successful: X
|
||||
# Failed: 0
|
||||
|
||||
# 7. Verify queue cleared
|
||||
ls -la .claude/context-queue/pending/
|
||||
# Expected: Empty (or nearly empty)
|
||||
|
||||
ls -la .claude/context-queue/uploaded/
|
||||
# Expected: Previously pending files moved here
|
||||
|
||||
# 8. Verify contexts in database
|
||||
curl -s "http://172.16.3.30:8001/api/conversation-contexts?limit=5" \
|
||||
-H "Authorization: Bearer $JWT_TOKEN" | python -m json.tool
|
||||
# Expected: Recently synced contexts appear in results
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Background sync triggered automatically
|
||||
- ✅ Queued contexts uploaded successfully
|
||||
- ✅ Files moved from pending/ to uploaded/
|
||||
- ✅ Contexts visible in database
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Cache Refresh Test
|
||||
|
||||
**Purpose:** Verify cache updates when API available
|
||||
|
||||
```bash
|
||||
# 1. API should be running from Phase 4
|
||||
|
||||
# 2. Delete local cache to force fresh fetch
|
||||
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null || git config --get remote.origin.url | md5sum | cut -d' ' -f1)
|
||||
rm -rf .claude/context-cache/$PROJECT_ID
|
||||
|
||||
# 3. Open Claude Code and send a message
|
||||
|
||||
# Expected:
|
||||
# - Hook fetches fresh context from API
|
||||
# - Cache recreated with new timestamp
|
||||
# - Online mode message (no offline warning)
|
||||
|
||||
# 4. Verify fresh cache
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
# Expected: latest.json with recent timestamp
|
||||
|
||||
cat .claude/context-cache/$PROJECT_ID/last_updated
|
||||
# Expected: Current timestamp (2026-01-17T...)
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Cache recreated from API
|
||||
- ✅ Fresh timestamp recorded
|
||||
- ✅ Online mode confirmed
|
||||
|
||||
---
|
||||
|
||||
## Test Results Template
|
||||
|
||||
```markdown
|
||||
## Offline Mode Test Results
|
||||
|
||||
**Date:** [DATE]
|
||||
**Tester:** [NAME]
|
||||
**System:** [OS/Machine]
|
||||
|
||||
### Phase 1: Baseline (Online Mode)
|
||||
- [ ] Context retrieved from API
|
||||
- [ ] Cache created successfully
|
||||
- [ ] Context injected correctly
|
||||
**Notes:**
|
||||
|
||||
### Phase 2: Offline Mode (Cache Fallback)
|
||||
- [ ] API stopped successfully
|
||||
- [ ] Offline warning displayed
|
||||
- [ ] Cached context used
|
||||
- [ ] No errors encountered
|
||||
**Notes:**
|
||||
|
||||
### Phase 3: Context Queuing
|
||||
- [ ] Context queued locally
|
||||
- [ ] Queue file created
|
||||
- [ ] Warning message shown
|
||||
**Notes:**
|
||||
|
||||
### Phase 4: Automatic Sync
|
||||
- [ ] API restarted successfully
|
||||
- [ ] Sync triggered automatically
|
||||
- [ ] All contexts uploaded
|
||||
- [ ] Queue cleared
|
||||
**Notes:**
|
||||
|
||||
### Phase 5: Cache Refresh
|
||||
- [ ] Old cache deleted
|
||||
- [ ] Fresh cache created
|
||||
- [ ] Online mode confirmed
|
||||
**Notes:**
|
||||
|
||||
### Overall Result
|
||||
- [ ] PASS - All phases successful
|
||||
- [ ] FAIL - Issues encountered (see notes)
|
||||
|
||||
### Issues Found
|
||||
[List any issues, errors, or unexpected behavior]
|
||||
|
||||
### Recommendations
|
||||
[Any suggestions for improvements]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: API Won't Stop
|
||||
|
||||
```bash
|
||||
# Force stop
|
||||
sudo systemctl kill claudetools-api
|
||||
|
||||
# Verify stopped
|
||||
sudo systemctl status claudetools-api
|
||||
```
|
||||
|
||||
### Issue: Cache Not Being Used
|
||||
|
||||
```bash
|
||||
# Check if cache exists
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
|
||||
# Check hook version
|
||||
head -3 .claude/hooks/user-prompt-submit
|
||||
# Should show: "v2 - with offline support"
|
||||
|
||||
# Check hook is executable
|
||||
ls -l .claude/hooks/user-prompt-submit
|
||||
# Should show: -rwxr-xr-x
|
||||
```
|
||||
|
||||
### Issue: Contexts Not Queuing
|
||||
|
||||
```bash
|
||||
# Check queue directory permissions
|
||||
ls -ld .claude/context-queue/pending/
|
||||
|
||||
# Check hook version
|
||||
head -3 .claude/hooks/task-complete
|
||||
# Should show: "v2 - with offline support"
|
||||
|
||||
# Check environment
|
||||
source .claude/context-recall-config.env
|
||||
echo $CLAUDE_API_URL
|
||||
# Should show: http://172.16.3.30:8001
|
||||
```
|
||||
|
||||
### Issue: Sync Not Working
|
||||
|
||||
```bash
|
||||
# Check JWT token
|
||||
source .claude/context-recall-config.env
|
||||
echo $JWT_TOKEN
|
||||
# Should show a long token string
|
||||
|
||||
# Manual sync with debug
|
||||
bash -x .claude/hooks/sync-contexts
|
||||
|
||||
# Check API is accessible
|
||||
curl http://172.16.3.30:8001/health
|
||||
```
|
||||
|
||||
### Issue: Contexts Moved to Failed/
|
||||
|
||||
```bash
|
||||
# View failed contexts
|
||||
ls -la .claude/context-queue/failed/
|
||||
|
||||
# Check specific failed context
|
||||
cat .claude/context-queue/failed/[filename].json | python -m json.tool
|
||||
|
||||
# Check API response
|
||||
curl -X POST http://172.16.3.30:8001/api/conversation-contexts \
|
||||
-H "Authorization: Bearer $JWT_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @.claude/context-queue/failed/[filename].json
|
||||
|
||||
# Move back to pending for retry
|
||||
mv .claude/context-queue/failed/*.json .claude/context-queue/pending/
|
||||
bash .claude/hooks/sync-contexts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Expected Behavior Summary
|
||||
|
||||
| Scenario | Hook Action | User Experience |
|
||||
|----------|-------------|-----------------|
|
||||
| **API Online** | Fetch from API → Cache locally → Inject | Normal operation, no warnings |
|
||||
| **API Offline (Recall)** | Read from cache → Inject with warning | "⚠️ Offline Mode - Using cached context" |
|
||||
| **API Offline (Save)** | Queue locally → Trigger background sync | "⚠ Context queued locally - will sync when online" |
|
||||
| **API Restored** | Background sync uploads queue → Clear | Silent sync, contexts uploaded |
|
||||
| **Fresh Start** | No cache available → Skip injection | Silent (no context to inject) |
|
||||
|
||||
---
|
||||
|
||||
## Performance Expectations
|
||||
|
||||
| Operation | Expected Time | Notes |
|
||||
|-----------|--------------|-------|
|
||||
| API Fetch | < 3 seconds | Timeout configured at 3s |
|
||||
| Cache Read | < 100ms | Local file read |
|
||||
| Queue Write | < 100ms | Local file write |
|
||||
| Background Sync | 0.5s per context | Non-blocking |
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
**What's Cached:**
|
||||
- Context summaries (dense_summary)
|
||||
- Titles, tags, scores
|
||||
- Project IDs (non-sensitive)
|
||||
|
||||
**What's NOT Cached:**
|
||||
- JWT tokens (in config file, gitignored)
|
||||
- Credentials or passwords
|
||||
- Full conversation transcripts
|
||||
|
||||
**Best Practices:**
|
||||
- Keep `.claude/context-cache/` in .gitignore
|
||||
- Keep `.claude/context-queue/` in .gitignore
|
||||
- Review queued contexts before manual sync if handling sensitive projects
|
||||
- Clear cache when switching machines: `rm -rf .claude/context-cache/`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Stop API (simulate offline)
|
||||
ssh guru@172.16.3.30 "sudo systemctl stop claudetools-api"
|
||||
|
||||
# Start API (restore online)
|
||||
ssh guru@172.16.3.30 "sudo systemctl start claudetools-api"
|
||||
|
||||
# Check API status
|
||||
curl -s http://172.16.3.30:8001/health
|
||||
|
||||
# View cache
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
cat .claude/context-cache/$PROJECT_ID/latest.json | python -m json.tool
|
||||
|
||||
# View queue
|
||||
ls -la .claude/context-queue/pending/
|
||||
|
||||
# Manual sync
|
||||
bash .claude/hooks/sync-contexts
|
||||
|
||||
# Clear cache (force refresh)
|
||||
rm -rf .claude/context-cache/$PROJECT_ID
|
||||
|
||||
# Clear queue (CAUTION: data loss!)
|
||||
rm -rf .claude/context-queue/pending/*.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Status:** Ready for Testing
|
||||
**Documentation:** See .claude/OFFLINE_MODE.md for architecture details
|
||||
483
docs/archives/offline-mode-removed/OFFLINE_MODE_VERIFICATION.md
Normal file
483
docs/archives/offline-mode-removed/OFFLINE_MODE_VERIFICATION.md
Normal file
@@ -0,0 +1,483 @@
|
||||
# Offline Mode Verification Report
|
||||
|
||||
**Date:** 2026-01-17
|
||||
**Status:** ✅ READY FOR TESTING
|
||||
|
||||
---
|
||||
|
||||
## Verification Summary
|
||||
|
||||
All components for offline-capable context recall have been installed and verified. The system is ready for live testing.
|
||||
|
||||
---
|
||||
|
||||
## Component Checklist
|
||||
|
||||
### ✅ 1. Hook Versions Upgraded
|
||||
|
||||
**user-prompt-submit:**
|
||||
```bash
|
||||
$ head -3 .claude/hooks/user-prompt-submit
|
||||
#!/bin/bash
|
||||
#
|
||||
# Claude Code Hook: user-prompt-submit (v2 - with offline support)
|
||||
```
|
||||
- **Status:** ✅ V2 Installed
|
||||
- **Features:** API fetch with 3s timeout, local cache fallback, cache refresh
|
||||
|
||||
**task-complete:**
|
||||
```bash
|
||||
$ head -3 .claude/hooks/task-complete
|
||||
#!/bin/bash
|
||||
#
|
||||
# Claude Code Hook: task-complete (v2 - with offline support)
|
||||
```
|
||||
- **Status:** ✅ V2 Installed
|
||||
- **Features:** API save with timeout, local queue on failure, background sync trigger
|
||||
|
||||
**sync-contexts:**
|
||||
```bash
|
||||
$ head -3 .claude/hooks/sync-contexts
|
||||
#!/bin/bash
|
||||
#
|
||||
# Sync Queued Contexts to Database
|
||||
```
|
||||
- **Status:** ✅ Present and Executable
|
||||
- **Features:** Batch upload from queue, move to uploaded/failed, auto-cleanup
|
||||
|
||||
---
|
||||
|
||||
### ✅ 2. Directory Structure Created
|
||||
|
||||
```bash
|
||||
$ ls -la .claude/context-cache/
|
||||
drwxr-xr-x context-cache/
|
||||
|
||||
$ ls -la .claude/context-queue/
|
||||
drwxr-xr-x failed/
|
||||
drwxr-xr-x pending/
|
||||
drwxr-xr-x uploaded/
|
||||
```
|
||||
|
||||
- **Cache Directory:** ✅ Created
|
||||
- Purpose: Store fetched contexts for offline reading
|
||||
- Location: `.claude/context-cache/[project-id]/`
|
||||
- Files: `latest.json`, `last_updated`
|
||||
|
||||
- **Queue Directories:** ✅ Created
|
||||
- `pending/`: Contexts waiting to upload
|
||||
- `uploaded/`: Successfully synced (auto-cleaned)
|
||||
- `failed/`: Failed uploads (manual review)
|
||||
|
||||
---
|
||||
|
||||
### ✅ 3. Configuration Updated
|
||||
|
||||
```bash
|
||||
$ grep CLAUDE_API_URL .claude/context-recall-config.env
|
||||
CLAUDE_API_URL=http://172.16.3.30:8001
|
||||
```
|
||||
|
||||
- **Status:** ✅ Points to Centralized API
|
||||
- **Server:** 172.16.3.30:8001 (RMM server)
|
||||
- **Previous:** http://localhost:8000 (local API)
|
||||
- **Change:** Complete migration to centralized architecture
|
||||
|
||||
---
|
||||
|
||||
### ✅ 4. Git Ignore Updated
|
||||
|
||||
```bash
|
||||
$ grep -E "(context-cache|context-queue)" .gitignore
|
||||
.claude/context-cache/
|
||||
.claude/context-queue/
|
||||
```
|
||||
|
||||
- **Status:** ✅ Both directories excluded
|
||||
- **Reason:** Local storage should not be committed
|
||||
- **Result:** No cache/queue files will be accidentally pushed to repo
|
||||
|
||||
---
|
||||
|
||||
### ✅ 5. API Health Check
|
||||
|
||||
```bash
|
||||
$ curl -s http://172.16.3.30:8001/health
|
||||
{"status":"healthy","database":"connected"}
|
||||
```
|
||||
|
||||
- **Status:** ✅ API Online and Healthy
|
||||
- **Database:** Connected to 172.16.3.30:3306
|
||||
- **Response Time:** < 1 second
|
||||
- **Ready For:** Online and offline mode testing
|
||||
|
||||
---
|
||||
|
||||
## Offline Capabilities Verified
|
||||
|
||||
### Reading Context (user-prompt-submit)
|
||||
|
||||
**Online Mode:**
|
||||
1. Hook executes before user message
|
||||
2. Fetches context from API: `http://172.16.3.30:8001/api/conversation-contexts/recall`
|
||||
3. Saves response to cache: `.claude/context-cache/[project]/latest.json`
|
||||
4. Updates timestamp: `.claude/context-cache/[project]/last_updated`
|
||||
5. Injects context into conversation
|
||||
6. **User sees:** Normal context recall, no warnings
|
||||
|
||||
**Offline Mode (Cache Fallback):**
|
||||
1. Hook executes before user message
|
||||
2. API fetch fails (timeout after 3 seconds)
|
||||
3. Reads from cache: `.claude/context-cache/[project]/latest.json`
|
||||
4. Injects cached context with warning
|
||||
5. **User sees:**
|
||||
```
|
||||
<!-- Context Recall: Retrieved X relevant context(s) from LOCAL CACHE (offline mode) -->
|
||||
⚠️ **Offline Mode** - Using cached context (API unavailable)
|
||||
```
|
||||
|
||||
**No Cache Available:**
|
||||
1. Hook executes before user message
|
||||
2. API fetch fails
|
||||
3. No cache file exists
|
||||
4. Hook exits silently
|
||||
5. **User sees:** No context injected (normal for first run)
|
||||
|
||||
---
|
||||
|
||||
### Saving Context (task-complete)
|
||||
|
||||
**Online Mode:**
|
||||
1. Hook executes after task completion
|
||||
2. POSTs context to API: `http://172.16.3.30:8001/api/conversation-contexts`
|
||||
3. Receives HTTP 200/201 success
|
||||
4. **User sees:** `✓ Context saved to database`
|
||||
|
||||
**Offline Mode (Queue Fallback):**
|
||||
1. Hook executes after task completion
|
||||
2. API POST fails (timeout after 5 seconds)
|
||||
3. Saves context to queue: `.claude/context-queue/pending/[project]_[timestamp]_context.json`
|
||||
4. Triggers background sync (opportunistic)
|
||||
5. **User sees:** `⚠ Context queued locally (API unavailable) - will sync when online`
|
||||
|
||||
---
|
||||
|
||||
### Synchronization (sync-contexts)
|
||||
|
||||
**Automatic Trigger:**
|
||||
- Runs in background on next user message (if API available)
|
||||
- Runs in background after task completion (if API available)
|
||||
- Non-blocking (user doesn't wait for sync)
|
||||
|
||||
**Manual Trigger:**
|
||||
```bash
|
||||
bash .claude/hooks/sync-contexts
|
||||
```
|
||||
|
||||
**Sync Process:**
|
||||
1. Scans `.claude/context-queue/pending/` for .json files
|
||||
2. For each file:
|
||||
- Determines endpoint (contexts or states based on filename)
|
||||
- POSTs to API with JWT auth
|
||||
- On success: moves to `uploaded/`
|
||||
- On failure: moves to `failed/`
|
||||
3. Auto-cleans `uploaded/` (keeps last 100 files)
|
||||
|
||||
**Output:**
|
||||
```
|
||||
===================================
|
||||
Syncing Queued Contexts
|
||||
===================================
|
||||
Found 3 pending context(s)
|
||||
|
||||
Processing: claudetools_20260117_140122_context.json
|
||||
✓ Uploaded successfully
|
||||
Processing: claudetools_20260117_141533_context.json
|
||||
✓ Uploaded successfully
|
||||
Processing: claudetools_20260117_143022_state.json
|
||||
✓ Uploaded successfully
|
||||
|
||||
===================================
|
||||
Sync Complete
|
||||
===================================
|
||||
Successful: 3
|
||||
Failed: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Readiness
|
||||
|
||||
### Prerequisites Met
|
||||
|
||||
- ✅ Hooks upgraded to v2
|
||||
- ✅ Storage directories created
|
||||
- ✅ Configuration updated
|
||||
- ✅ .gitignore updated
|
||||
- ✅ API accessible
|
||||
- ✅ Documentation complete
|
||||
|
||||
### Test Documentation
|
||||
|
||||
- **Procedure:** `OFFLINE_MODE_TEST_PROCEDURE.md`
|
||||
- 5 test phases with step-by-step instructions
|
||||
- Expected outputs documented
|
||||
- Troubleshooting guide included
|
||||
- Results template provided
|
||||
|
||||
- **Architecture:** `.claude/OFFLINE_MODE.md`
|
||||
- Complete technical documentation
|
||||
- Flow diagrams
|
||||
- Security considerations
|
||||
- FAQ section
|
||||
|
||||
### Test Phases Ready
|
||||
|
||||
1. **Phase 1 - Baseline (Online):** ✅ Ready
|
||||
- Verify normal operation
|
||||
- Test API fetch
|
||||
- Confirm cache creation
|
||||
|
||||
2. **Phase 2 - Offline Mode (Cache):** ✅ Ready
|
||||
- Stop API service
|
||||
- Verify cache fallback
|
||||
- Confirm offline warning
|
||||
|
||||
3. **Phase 3 - Context Queuing:** ✅ Ready
|
||||
- Test save failure
|
||||
- Verify local queue
|
||||
- Confirm warning message
|
||||
|
||||
4. **Phase 4 - Automatic Sync:** ✅ Ready
|
||||
- Restart API
|
||||
- Verify background sync
|
||||
- Confirm queue cleared
|
||||
|
||||
5. **Phase 5 - Cache Refresh:** ✅ Ready
|
||||
- Delete cache
|
||||
- Force fresh fetch
|
||||
- Verify new cache
|
||||
|
||||
---
|
||||
|
||||
## What Was Changed
|
||||
|
||||
### Files Modified
|
||||
|
||||
1. **`.claude/hooks/user-prompt-submit`**
|
||||
- **Before:** V1 (API-only, silent fail on error)
|
||||
- **After:** V2 (API with local cache fallback)
|
||||
- **Key Addition:** Lines 95-108 (cache fallback logic)
|
||||
|
||||
2. **`.claude/hooks/task-complete`**
|
||||
- **Before:** V1 (API-only, data loss on error)
|
||||
- **After:** V2 (API with local queue on failure)
|
||||
- **Key Addition:** Queue directory creation, JSON file writes, sync trigger
|
||||
|
||||
3. **`.gitignore`**
|
||||
- **Before:** No context storage entries
|
||||
- **After:** Added `.claude/context-cache/` and `.claude/context-queue/`
|
||||
|
||||
### Files Created
|
||||
|
||||
1. **`.claude/hooks/sync-contexts`** (111 lines)
|
||||
- Purpose: Upload queued contexts to API
|
||||
- Features: Batch processing, error handling, auto-cleanup
|
||||
- Trigger: Manual or automatic (background)
|
||||
|
||||
2. **`.claude/OFFLINE_MODE.md`** (481 lines)
|
||||
- Complete architecture documentation
|
||||
- Usage guide with examples
|
||||
- Migration instructions
|
||||
- Troubleshooting section
|
||||
|
||||
3. **`OFFLINE_MODE_TEST_PROCEDURE.md`** (517 lines)
|
||||
- 5-phase test plan
|
||||
- Step-by-step commands
|
||||
- Expected outputs
|
||||
- Results template
|
||||
|
||||
4. **`OFFLINE_MODE_VERIFICATION.md`** (This file)
|
||||
- Component verification
|
||||
- Readiness checklist
|
||||
- Change summary
|
||||
|
||||
5. **`scripts/upgrade-to-offline-mode.sh`** (170 lines)
|
||||
- Automated upgrade from v1 to v2
|
||||
- Backup creation
|
||||
- Directory setup
|
||||
- Verification checks
|
||||
|
||||
---
|
||||
|
||||
## Comparison: V1 vs V2
|
||||
|
||||
| Feature | V1 (Original) | V2 (Offline-Capable) |
|
||||
|---------|---------------|----------------------|
|
||||
| **API Fetch** | ✅ Yes | ✅ Yes |
|
||||
| **API Save** | ✅ Yes | ✅ Yes |
|
||||
| **Offline Read** | ❌ Silent fail | ✅ Cache fallback |
|
||||
| **Offline Save** | ❌ Data loss | ✅ Local queue |
|
||||
| **Auto-sync** | ❌ No | ✅ Background sync |
|
||||
| **Manual sync** | ❌ No | ✅ sync-contexts script |
|
||||
| **Status messages** | ❌ Silent | ✅ Clear warnings |
|
||||
| **Data resilience** | ❌ Low | ✅ High |
|
||||
| **Network tolerance** | ❌ Fails offline | ✅ Works offline |
|
||||
|
||||
---
|
||||
|
||||
## User Experience
|
||||
|
||||
### Before (V1)
|
||||
|
||||
**Scenario: API Unavailable**
|
||||
```
|
||||
User: [Sends message to Claude]
|
||||
System: [Hook tries API, fails silently]
|
||||
Claude: [Responds without context - no memory]
|
||||
|
||||
User: [Completes task]
|
||||
System: [Hook tries to save, fails silently]
|
||||
Result: Context lost forever ❌
|
||||
```
|
||||
|
||||
### After (V2)
|
||||
|
||||
**Scenario: API Unavailable**
|
||||
```
|
||||
User: [Sends message to Claude]
|
||||
System: [Hook tries API, falls back to cache]
|
||||
Claude: [Responds with cached context]
|
||||
Message: "⚠️ Offline Mode - Using cached context (API unavailable)"
|
||||
|
||||
User: [Completes task]
|
||||
System: [Hook queues context locally]
|
||||
Message: "⚠ Context queued locally - will sync when online"
|
||||
Result: Context queued for later upload ✅
|
||||
|
||||
[Later, when API restored]
|
||||
System: [Background sync uploads queue]
|
||||
Message: "✓ Synced 1 context(s)"
|
||||
Result: Context safely in database ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security & Privacy
|
||||
|
||||
### What's Stored Locally
|
||||
|
||||
**Cache (`.claude/context-cache/`):**
|
||||
- Context summaries (not full transcripts)
|
||||
- Titles, tags, relevance scores
|
||||
- Project IDs
|
||||
- Timestamps
|
||||
|
||||
**Queue (`.claude/context-queue/`):**
|
||||
- Same as cache, plus:
|
||||
- Context type (session_summary, decision, etc.)
|
||||
- Full dense_summary text
|
||||
- Associated tags array
|
||||
|
||||
### What's NOT Stored
|
||||
|
||||
- ❌ JWT tokens (in config file, gitignored separately)
|
||||
- ❌ Database credentials
|
||||
- ❌ User passwords
|
||||
- ❌ Full conversation transcripts
|
||||
- ❌ Encrypted credentials from database
|
||||
|
||||
### Privacy Measures
|
||||
|
||||
1. **Gitignore Protection:**
|
||||
- `.claude/context-cache/` excluded from git
|
||||
- `.claude/context-queue/` excluded from git
|
||||
- No accidental commits to repo
|
||||
|
||||
2. **File Permissions:**
|
||||
- Directories created with user-only access
|
||||
- No group or world read permissions
|
||||
|
||||
3. **Cleanup:**
|
||||
- Uploaded queue auto-cleaned (keeps last 100)
|
||||
- Cache replaced on each API fetch
|
||||
- Failed contexts manually reviewable
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### For Testing
|
||||
|
||||
1. **Review test procedure:**
|
||||
```bash
|
||||
cat OFFLINE_MODE_TEST_PROCEDURE.md
|
||||
```
|
||||
|
||||
2. **When ready to test, run Phase 1:**
|
||||
```bash
|
||||
# Open Claude Code, send a message, verify context cached
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
```
|
||||
|
||||
3. **To test offline mode (requires sudo):**
|
||||
```bash
|
||||
ssh guru@172.16.3.30
|
||||
sudo systemctl stop claudetools-api
|
||||
# Then use Claude Code and observe cache fallback
|
||||
```
|
||||
|
||||
### For Production Use
|
||||
|
||||
**System is ready for production use NOW:**
|
||||
- ✅ All components installed
|
||||
- ✅ Hooks active and working
|
||||
- ✅ API accessible
|
||||
- ✅ Documentation complete
|
||||
|
||||
**No action required** - offline support is automatic:
|
||||
- Online: Works normally
|
||||
- Offline: Falls back gracefully
|
||||
- Restored: Syncs automatically
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
### ✅ Verification Complete
|
||||
|
||||
All components for offline-capable context recall have been successfully:
|
||||
- Installed
|
||||
- Configured
|
||||
- Verified
|
||||
- Documented
|
||||
|
||||
### ✅ System Status
|
||||
|
||||
**ClaudeTools Context Recall System:**
|
||||
- **Version:** 2.0 (Offline-Capable)
|
||||
- **Status:** Production Ready
|
||||
- **API:** Centralized on 172.16.3.30:8001
|
||||
- **Database:** Centralized on 172.16.3.30:3306
|
||||
- **Hooks:** V2 with offline support
|
||||
- **Storage:** Local cache and queue ready
|
||||
- **Documentation:** Complete
|
||||
|
||||
### ✅ User Request Fulfilled
|
||||
|
||||
**Original Request:**
|
||||
> "Verify all the local code to make sure it complies with the new setup for dynamic storage and retrieval of context and all other data. Also verify it has a fallback to local storage with a complete sync once database is functional."
|
||||
|
||||
**Completed:**
|
||||
- ✅ Local code verified for centralized API compliance
|
||||
- ✅ Fallback to local storage implemented (cache + queue)
|
||||
- ✅ Complete sync mechanism implemented (automatic + manual)
|
||||
- ✅ Database functionality verified (API healthy)
|
||||
- ✅ All components tested and ready
|
||||
|
||||
---
|
||||
|
||||
**Report Generated:** 2026-01-17
|
||||
**Next Action:** Optional live testing using OFFLINE_MODE_TEST_PROCEDURE.md
|
||||
**System Ready:** Yes - offline support is now active and automatic
|
||||
236
docs/archives/offline-mode-removed/PERIODIC_SAVE_QUICK_START.md
Normal file
236
docs/archives/offline-mode-removed/PERIODIC_SAVE_QUICK_START.md
Normal 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
|
||||
Reference in New Issue
Block a user