Upload AGENTS.md with huggingface_hub

AGENTS.md

@@ -0,0 +1,206 @@
+# Hermes Memory Synchronization System
+
+## Overview
+This system enables Hermes to backup and restore all persistent state to/from Hugging Face Datasets, ensuring data survives Docker restarts.
+
+## Main File: hermes_sync.py
+
+The `hermes_sync.py` script handles:
+
+- **Backup**: Archives all of Hermes' state to a Hugging Face Dataset
+- **Restore**: Recovers data from a Hugging Face Dataset back to Hermes
+- **Auto-backup**: Automatic hourly backups (configurable via cron)
+- **Auto-cleanup**: Automatically removes local backup files after successful upload
+
+## What Gets Backed Up
+
+The `hermes_sync.py` script backs up the following data from the `.hermes` directory:
+
+- `state.db` + WAL - core KV state (sessions, memory, channel directory, etc.)
+- `response_store.db` - chat response cache
+- `sessions/` - session transcripts
+- `skills/` - user-installed skills
+- `cron/` - cron job definitions
+- `memories/` - persistent memories
+- `auth.json` - OAuth tokens
+- `channel_directory.json` - registered channels
+- `config.yaml` - active configuration
+- `gateway_state.json` - gateway routing state
+- `.env` - environment overrides
+- `SOUL.md` - persona
+- `.skills_prompt_snapshot.json` - skill snapshot
+
+## What's Excluded
+
+The following items are not backed up:
+
+- `logs/` - runtime logs
+- `plans/` - transient plans
+- `workspace/` - user workspace (too large)
+- `bin/` - binaries (reinstalled on start)
+- `.update_check` - ephemeral data
+- `auth.lock` - runtime lock file
+
+## Usage
+
+### 1. Download hermes_sync.py
+
+Before using, download the script:
+
+```bash
+# Method 1: wget
+wget https://huggingface.co/datasets/R1000/Hermes-Memory/resolve/main/hermes_sync.py
+
+# Method 2: huggingface-cli
+huggingface-cli download --repo-type dataset R1000/Hermes-Memory hermes_sync.py
+
+# Method 3: curl
+curl -O https://huggingface.co/datasets/R1000/Hermes-Memory/resolve/main/hermes_sync.py
+```
+
+### 2. Set Environment Variables
+
+Before using, set HF_TOKEN:
+
+```bash
+export HF_TOKEN=hf_your_token_here
+```
+
+Or in a `.env` file:
+
+```bash
+HF_TOKEN=hf_your_token_here
+```
+
+### 3. Backup
+
+```bash
+# Create backup and upload to Hugging Face
+python3 hermes_sync.py backup --upload
+
+# Local backup file is created at /tmp/hermes_backup/hermes_memory_backup.zip
+# After successful upload, local file is automatically deleted to save Docker space
+```
+
+Note: Local backup files are automatically deleted after successful upload to prevent Docker space from filling up.
+
+### 4. Restore
+
+```bash
+# Restore data from the latest backup on Hugging Face
+python3 hermes_sync.py restore
+
+# All data is fetched and extracted back to ~/.hermes/
+```
+
+### 5. Auto-backup Every Hour
+
+```bash
+# Start auto-backup service (runs in background)
+python3 hermes_sync.py start
+
+# Or use cron job:
+# 0 * * * * cd /opt/data/.hermes/home && HF_TOKEN=xxx python3 hermes_sync.py backup --upload
+```
+
+## Setting Up Hourly Auto-backup
+
+### Method 1: System Cron Job
+
+Edit crontab:
+
+```bash
+crontab -e
+```
+
+Add this line (runs every hour at minute 0):
+
+```bash
+0 * * * * cd /opt/data/.hermes/home && export HF_TOKEN=hf_your_token && python3 hermes_sync.py backup --upload
+```
+
+### Method 2: Hermes Cron Job
+
+Create a cron job through Hermes:
+
+```bash
+hermes cron create --schedule "0 * * * *" --name "hermes-auto-backup" --command "python3 hermes_sync.py backup --upload"
+```
+
+### Method 3: Python Schedule Library
+
+The `hermes_sync.py` file includes a `start_auto_backup()` function that uses the schedule library:
+
+```bash
+python3 hermes_sync.py start
+```
+
+## Security
+
+- Token is stored only in environment variables, never hardcoded in files
+- Backup files are compressed with ZIP_DEFLATED
+- After successful upload, local files are automatically deleted
+- No tokens are stored in the repository or public files
+
+## File Locations
+
+- Script file: `./hermes_sync.py` (after download)
+- Local backup file: `/tmp/hermes_backup/` (automatically deleted after upload)
+- Cloud backup file: `https://huggingface.co/datasets/R1000/Hermes-Memory`
+
+## Usage Examples
+
+### After Docker Restart
+
+After restarting Docker:
+
+```bash
+# Download the script
+wget https://huggingface.co/datasets/R1000/Hermes-Memory/resolve/main/hermes_sync.py
+
+# Set token
+export HF_TOKEN=hf_your_token
+
+# Restore data
+python3 hermes_sync.py restore
+```
+
+All data is restored from the latest backup.
+
+### Immediate Backup
+
+```bash
+# Download file (if not already present)
+wget https://huggingface.co/datasets/R1000/Hermes-Memory/resolve/main/hermes_sync.py
+
+# Set token
+export HF_TOKEN=hf_your_token
+
+# Create backup and upload
+python3 hermes_sync.py backup --upload
+
+# Local backup file is automatically deleted after successful upload
+```
+
+## Troubleshooting
+
+- Error: "HF_TOKEN environment variable is not set"
+  ```bash
+  export HF_TOKEN=hf_your_token_here
+  ```
+
+- Error: "Upload failed"
+  - Check that HF_TOKEN is correct
+  - Check internet connectivity
+  - Check that the dataset has write permission
+
+- Error: "Restore failed"
+  - Check that backup file exists on Hugging Face
+  - Check permissions on the `~/.hermes/` directory
+
+## Important Notes
+
+- The `hermes_sync.py` file is regularly updated at: https://huggingface.co/datasets/R1000/Hermes-Memory/blob/main/hermes_sync.py
+- After successful upload, local backup files are automatically deleted
+- Auto-backup runs every hour at minute 0 (or as scheduled)
+- The system supports data recovery after Docker restarts