diff --git a/channel_directory.json b/channel_directory.json index c686a3b..dec3e51 100644 --- a/channel_directory.json +++ b/channel_directory.json @@ -1,5 +1,5 @@ { - "updated_at": "2026-05-24T15:21:22.433893", + "updated_at": "2026-05-25T11:31:28.733336", "platforms": { "telegram": [], "discord": [], diff --git a/cron/jobs.json b/cron/jobs.json index 82117e6..ec73595 100644 --- a/cron/jobs.json +++ b/cron/jobs.json @@ -62,15 +62,15 @@ "schedule_display": "0 23 * * 0", "repeat": { "times": null, - "completed": 1 + "completed": 2 }, "enabled": true, "state": "scheduled", "paused_at": null, "paused_reason": null, "created_at": "2026-05-23T18:47:21.071463+00:00", - "next_run_at": "2026-05-24T23:00:00+00:00", - "last_run_at": "2026-05-23T18:48:39.356717+00:00", + "next_run_at": "2026-05-31T23:00:00+00:00", + "last_run_at": "2026-05-24T23:00:25.774486+00:00", "last_status": "ok", "last_error": null, "last_delivery_error": null, @@ -125,7 +125,50 @@ ], "workdir": null, "profile": null + }, + { + "id": "febd377a1d4a", + "name": "daily-db-snapshot", + "prompt": "Run the SQLite database snapshot script to back up memory_store.db and state.db to ~/.hermes/backups/", + "skills": [], + "skill": null, + "model": null, + "provider": null, + "base_url": null, + "script": "snapshot_hermes_db.sh", + "no_agent": true, + "context_from": null, + "schedule": { + "kind": "cron", + "expr": "0 4 * * *", + "display": "0 4 * * *" + }, + "schedule_display": "0 4 * * *", + "repeat": { + "times": null, + "completed": 2 + }, + "enabled": true, + "state": "scheduled", + "paused_at": null, + "paused_reason": null, + "created_at": "2026-05-24T15:28:17.082309+00:00", + "next_run_at": "2026-05-26T04:00:00+00:00", + "last_run_at": "2026-05-25T11:34:28.944549+00:00", + "last_status": "ok", + "last_error": null, + "last_delivery_error": null, + "deliver": "origin", + "origin": { + "platform": "matrix", + "chat_id": "!lRwsFeLuAJFwcbOOGU:conlon.fun", + "chat_name": null, + "thread_id": null + }, + "enabled_toolsets": null, + "workdir": null, + "profile": null } ], - "updated_at": "2026-05-23T19:35:05.710881+00:00" + "updated_at": "2026-05-25T11:34:28.945040+00:00" } \ No newline at end of file diff --git a/memories/MEMORY.md b/memories/MEMORY.md index 25c633e..2aca75b 100644 --- a/memories/MEMORY.md +++ b/memories/MEMORY.md @@ -6,4 +6,8 @@ Homelab 192.168.68.0/24 — full map in skill homelab-network-recon. Key service § Memory rules: save durable preferences/env facts. Do NOT save task progress, PR numbers, commit SHAs, session outcomes, or anything stale in 7 days. Use skills for reusable workflows (skill_manage tool). Patch skills immediately when they're wrong. § -Holographic memory provider is active (SQLite-backed, local-only, ~/.hermes/memory_store.db). Built-in memory still active alongside. Fact_store tool handles deep facts; MEMORY.md/USER.md hold only always-in-context essentials. \ No newline at end of file +Holographic memory provider is active (SQLite-backed, local-only, ~/.hermes/memory_store.db). Built-in memory still active alongside. Fact_store tool handles deep facts; MEMORY.md/USER.md hold only always-in-context essentials. +§ +Hermes config version-controlled in Gitea at https://gitea.conlon.fun/andy/hermes-config.git — tracks config.yaml, SOUL.md, memories/, skills/, scripts/, cron/jobs.json. Daily DB snapshot cron at 4AM ET backs up memory_store.db and state.db to ~/.hermes/backups/ (30-day retention). Recovery docs in README.md. +§ +Skill `hermes-config-management` (devops category) covers Hermes memory provider selection, git-backed config backup to Gitea, SQLite DB snapshot cron, and disaster recovery. Load when asked about backup, memory setup, or recovery. \ No newline at end of file diff --git a/memory_store.db-shm b/memory_store.db-shm new file mode 100644 index 0000000..6aaba24 Binary files /dev/null and b/memory_store.db-shm differ diff --git a/memory_store.db-wal b/memory_store.db-wal new file mode 100644 index 0000000..8da97a4 Binary files /dev/null and b/memory_store.db-wal differ diff --git a/reading_state.json b/reading_state.json index 66d45e8..037558c 100644 --- a/reading_state.json +++ b/reading_state.json @@ -1,5 +1,5 @@ { - "last_check": "2026-05-23", + "last_check": "2026-05-24", "known_read_books": [ { "title": "The Heroes", @@ -44,6 +44,6 @@ "detected_on": "2026-05-23" } ], - "weekly_digest_sent": 3, + "weekly_digest_sent": 4, "_prev_read_count": 4 } \ No newline at end of file diff --git a/skills/.usage.json b/skills/.usage.json index bc119c1..cbe7584 100644 --- a/skills/.usage.json +++ b/skills/.usage.json @@ -25,6 +25,19 @@ "use_count": 10, "view_count": 10 }, + "hermes-config-management": { + "archived_at": null, + "created_at": "2026-05-24T15:31:15.036256+00:00", + "created_by": "agent", + "last_patched_at": "2026-05-24T15:32:21.106565+00:00", + "last_used_at": "2026-05-25T11:34:10.661632+00:00", + "last_viewed_at": "2026-05-25T11:34:10.655677+00:00", + "patch_count": 3, + "pinned": false, + "state": "active", + "use_count": 2, + "view_count": 2 + }, "hermes-gateway-platforms": { "archived_at": null, "created_at": "2026-05-22T15:01:59.623821+00:00", @@ -95,13 +108,13 @@ "created_at": "2026-05-22T21:05:43.722952+00:00", "created_by": "agent", "last_patched_at": "2026-05-23T15:14:01.187666+00:00", - "last_used_at": "2026-05-23T15:13:54.791149+00:00", - "last_viewed_at": "2026-05-23T15:13:54.785232+00:00", + "last_used_at": "2026-05-24T15:29:38.020427+00:00", + "last_viewed_at": "2026-05-24T15:29:38.014372+00:00", "patch_count": 5, "pinned": false, "state": "active", - "use_count": 3, - "view_count": 3 + "use_count": 4, + "view_count": 4 }, "us-election-research": { "archived_at": null, diff --git a/skills/devops/hermes-config-management/SKILL.md b/skills/devops/hermes-config-management/SKILL.md new file mode 100644 index 0000000..83cf3ea --- /dev/null +++ b/skills/devops/hermes-config-management/SKILL.md @@ -0,0 +1,181 @@ +--- +name: hermes-config-management +description: "Hermes Agent configuration management: memory providers, git-backed config backup, DB snapshot strategies, disaster recovery." +version: 1.0.0 +author: Hermes Agent +tags: [hermes, configuration, backup, memory, gitea, sqlite, recovery] +triggers: + - "back up hermes config" + - "memory provider setup" + - "switch memory provider" + - "hermes disaster recovery" + - "hermes gitea backup" + - "holographic memory" + - "hermes db snapshot" +references: + - references/memory-provider-comparison.md + - references/gitea-backup-setup.md +templates: + - templates/dot-gitignore.md +--- + +# Hermes Config Management + +System administration procedures for the Hermes Agent installation: memory provider selection, configuration backup, database snapshot strategy, and disaster recovery. + +## Memory Provider Selection + +### Built-in (always active) + +Two files at `~/.hermes/memories/`: +- `MEMORY.md` — 2,200 char limit, agent's personal notes +- `USER.md` — 1,375 char limit, user profile + +Injected into every session's system prompt as a frozen snapshot. Managed via the `memory` tool (add/replace/remove). + +**When to use a different provider:** the built-in is adequate for light use but fills quickly (~3-4 sessions of heavy interaction). Use an external provider when you regularly hit 90%+ capacity. + +### External Providers + +Only one external provider can be active at a time. The built-in always stays active alongside. + +For the full comparison table, see `references/memory-provider-comparison.md`. + +**Recommended for homelab (free/self-hosted):** Holographic — SQLite-backed, zero dependencies, no API keys, no servers, no LLM costs. Full FTS5 search, trust scoring, entity resolution. + +Pitfalls: +- Setting `memory.provider: honcho` with an empty `honcho: {}` block — reads return empty, writes fail silently. +- External providers still require an LLM API key if they do their own inference (Honcho, Hindsight embedded). Holographic and chronological built-in do not. + +### Switch Provider + +```bash +hermes memory setup # interactive picker +hermes config set memory.provider NAME # or manual +hermes memory status # verify +``` + +Changes take effect on next session start (`/reset`). + +## Built-in Memory Sizing with External Provider + +When an external provider is active, the built-in should hold only **always-in-context essentials** — things that need to be in every session's face without retrieval cost. Let the external provider handle deep facts (API endpoints, cron job IDs, copy-paste conventions). + +Strategy: +- MEMORY.md: persona/SOUL.md location, active provider, high-level homelab overview, memory rules +- USER.md: values, timezone, ops style, current reading +- Move environment facts (API tokens, service endpoints, cron job details) to external provider — they're retrievable on demand + +Target: 1,500–1,700 total chars across both files, well under the 3,575 combined limit. + +## Git-Backed Configuration Backup + +The entire `~/.hermes/` directory can be version-controlled, excluding secrets and ephemeral data. + +### .gitignore Strategy + +See `templates/dot-gitignore.md` for the canonical `.gitignore` template. + +Key exclusion rules: +- **Secrets:** `.env`, `auth.json`, `honcho.json` +- **Runtime:** `logs/`, `cache/`, `sessions/`, `state-snapshots/`, `checkpoints/`, `plugins/` +- **Binaries:** `node/`, `bin/`, `lsp/`, `hermes-agent/`, `platforms/` +- **SQLite DBs:** `memory_store.db`, `state.db`, `state.db-*` (handled by cron snapshot) +- **Locks:** `*.lock`, `gateway.pid`, `gateway_state.json`, `processes.json` +- **Generated:** `.install_method`, `.update_check`, `models_dev_cache.json`, `interrupt_debug.log` +- **Backups:** `*.bak.*` +- **Git creds:** `.git-credentials` + +### Initialize Repo + +```bash +cd ~/.hermes +git init +git branch -m main +git add .gitignore README.md config.yaml SOUL.md memories/ skills/ scripts/ cron/ \ + kanban.db reading_*.json channel_directory.json +git commit -m "init: hermes agent config, skills, memories, and scripts" +git remote add origin https://gitea.example.com/user/hermes-config.git +git config credential.helper 'store --file ~/.hermes/.git-credentials' +echo "https://user:token@gitea.example.com" > ~/.hermes/.git-credentials +chmod 600 ~/.hermes/.git-credentials +git push -u origin main +``` + +**Pitfalls:** +- Git prompt creds fail in non-interactive terminal (`No such device or address`). Use token-in-credential-store or token-in-remote-URL. +- Skills directory is large (~15M with bundled skills). Still worth tracking — one-command recovery. +- Set git user.email and user.name immediately to avoid noisy commit warnings. + +## SQLite Database Backup + +SQLite databases (`memory_store.db`, `state.db`) are binary files. Git handles binary diffs poorly, so use a `no_agent` cron job instead. + +### Snapshot Script + +Place at `~/.hermes/scripts/snapshot_hermes_db.sh`: + +```bash +#!/bin/bash +HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" +BACKUP_DIR="$HERMES_HOME/backups" +RETENTION_DAYS=30 +mkdir -p "$BACKUP_DIR" +DATE=$(date +%Y%m%d_%H%M%S) +for db in memory_store.db state.db; do + SRC="$HERMES_HOME/$db" + [ -f "$SRC" ] && cp "$SRC" "$BACKUP_DIR/${db%.db}_${DATE}.db" && echo "backed up $db" || echo "skipping $db" +done +find "$BACKUP_DIR" -name '*.db' -type f -mtime +$RETENTION_DAYS -delete +echo "snapshot complete: $(date)" +``` + +### Create Cron Job + +```bash +hermes cron create \ + --name daily-db-snapshot \ + --schedule "0 4 * * *" \ + --script scripts/snapshot_hermes_db.sh \ + --no-agent +``` + +The `no_agent` flag makes this a pure shell-script job — zero token cost, just copies files. + +## Disaster Recovery + +On a fresh machine: + +```bash +# 1. Install Hermes +curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash + +# 2. Clone config repo +cd ~/.hermes +git init +git remote add origin https://gitea.example.com/user/hermes-config.git +git pull origin main + +# 3. Restore secrets — copy .env and auth.json back from safe backup +# .env needs: OPENROUTER_API_KEY, MATRIX_ACCESS_TOKEN, etc. +# auth.json holds OAuth tokens + +# 4. Restore SQLite DBs from latest snapshot in backups/ + +# 5. Verify skills loaded +hermes skills list + +# 6. Cron jobs auto-load from cron/jobs.json +hermes cron list + +# 7. Start gateway +hermes gateway run +``` + +## Pitfalls + +- **Don't put `.env` or `auth.json` in git** — matrix tokens, API keys, OAuth tokens are in plaintext. +- **Token auth for Gitea**: use HTTPS token in credential store, not SSH deploy keys. Private keys get redacted by Hermes. +- **SQLite DBs change on every session** — daily snapshot is sufficient; more frequent adds no value. +- **Built-in memory still matters** even with an external provider — it's the privileged always-in-context slot. Use it wisely. +- **`hermes-agent` skill is bundled/protected** — you can't patch it. This skill fills the gaps the bundled skill doesn't cover (backup, recovery, provider comparisons). \ No newline at end of file diff --git a/skills/devops/hermes-config-management/references/gitea-backup-setup.md b/skills/devops/hermes-config-management/references/gitea-backup-setup.md new file mode 100644 index 0000000..c8ec913 --- /dev/null +++ b/skills/devops/hermes-config-management/references/gitea-backup-setup.md @@ -0,0 +1,78 @@ +# Gitea Backup Setup for Hermes Config + +This documents the exact setup done in session 2026-05-24 for Andy's homelab. + +## Repo + +`https://gitea.conlon.fun/andy/hermes-config.git` (user: andy) + +## What's Tracked + +| Path | Purpose | +|------|---------| +| `config.yaml` | Model provider, toolsets, feature toggles | +| `SOUL.md` | Persona definition | +| `memories/` | MEMORY.md + USER.md | +| `skills/` | All installed skills (bundled + agent-created) | +| `scripts/` | Custom automation scripts (snapshot, Calibre scan, grocery CRUD) | +| `cron/jobs.json` | Scheduled job definitions | +| `kanban.db` | Multi-agent board | +| `reading_*.json` | Reading list and state | +| `channel_directory.json` | Gateway platform routing | + +## What's NOT in Git + +| File | How to restore | +|------|----------------| +| `~/.hermes/.env` | Contains OPENROUTER_API_KEY, MATRIX_ACCESS_TOKEN — copy from safe backup | +| `~/.hermes/auth.json` | OAuth tokens — copy from safe backup | +| `memory_store.db`, `state.db` | Latest snapshot in `~/.hermes/backups/` | + +## Auth Setup + +Gitea API token: stored in git credential helper at `~/.hermes/.git-credentials`: + +``` +https://andy:TOKEN@gitea.conlon.fun +``` + +Token permissions: user-level (needs repo create/push access). + +## Initial Commit Stats + +- 667 files +- ~213K lines +- Commit message: `init: hermes agent config, skills, memories, and scripts` + +## Push Pattern + +```bash +cd ~/.hermes +git add -A # or selective add +git commit -m "type: concise message" +git push +``` + +## Cron Snapshot Job + +| Field | Value | +|-------|-------| +| Name | `daily-db-snapshot` | +| Schedule | `0 4 * * *` (daily at 4AM ET) | +| Script | `scripts/snapshot_hermes_db.sh` | +| Mode | `no_agent=true` | +| Retention | 30 days via `find -mtime +30 -delete` | +| Next run | next scheduled 4AM tick | + +The script copies `memory_store.db` and `state.db` to `~/.hermes/backups/` with timestamps. + +## Recovery Path + +From README.md (committed in the repo): + +1. Install Hermes via curl install script +2. Clone repo to ~/.hermes +3. Restore .env + auth.json from safe backup +4. Restore latest DB snapshots from backups/ +5. Verify skills and cron jobs auto-load +6. Start gateway \ No newline at end of file diff --git a/skills/devops/hermes-config-management/references/memory-provider-comparison.md b/skills/devops/hermes-config-management/references/memory-provider-comparison.md new file mode 100644 index 0000000..2e88c97 --- /dev/null +++ b/skills/devops/hermes-config-management/references/memory-provider-comparison.md @@ -0,0 +1,129 @@ +# Memory Provider Comparison + +Comparison of all 8 external Hermes memory providers and the built-in memory. Focused on free/self-hosted options. + +## Built-In (always active alongside any external provider) + +| Property | Value | +|----------|-------| +| Storage | Two flat markdown files (~/.hermes/memories/) | +| Limits | MEMORY.md: 2,200 chars, USER.md: 1,375 chars | +| Cost | Free — zero dependencies | +| Retrieval | Full scan via system prompt injection | +| Search | None (agent reads everything every session) | +| Notes | Always active. Use for always-in-context essentials only when using an external provider. | + +## External Providers (only one active at a time) + +### Holographic ✅ Recommended for homelab + +| Property | Value | +|----------|-------| +| Storage | Local SQLite with FTS5 | +| Hosting | Local only | +| API Key Required | No | +| LLM Costs | None — all operations are local DB queries | +| Dependencies | None (SQLite always available) | +| Setup | `hermes config set memory.provider holographic` | +| Tools | `fact_store` (9 actions), `fact_feedback` | +| Features | FTS5 search, trust scoring, entity resolution, HRR vector algebra | +| Config | `plugins.hermes-memory-store.db_path` (default: ~/.hermes/memory_store.db) | +| Notes | Zero ongoing cost. DB auto-creates on first use. | + +### Hindsight (Local Embedded) + +| Property | Value | +|----------|-------| +| Storage | PostgreSQL (built-in daemon) | +| Hosting | Local daemon | +| API Key Required | Yes — LLM API key for memory extraction | +| LLM Costs | Yes — each retain/recall round burns tokens | +| Dependencies | LLM API key (OpenAI, Anthropic, OpenRouter, Ollama, etc.) | +| Setup | `hermes memory setup` → select hindsight → local_embedded | +| Features | Knowledge graph, entity resolution, multi-strategy retrieval, auto-retain/recall | +| Notes | Most powerful option but burns tokens. Free if pointed at local Ollama. Daemon auto-starts/auto-stops. | + +### Hindsight (Cloud) + +| Property | Value | +|----------|-------| +| Storage | Managed cloud | +| Hosting | vectorize.io | +| API Key Required | Yes — from ui.hindsight.vectorize.io | +| Cost | Paid (free tier may exist) | +| Features | Same as local embedded but no daemon to manage | + +### Honcho (Self-Hosted) + +| Property | Value | +|----------|-------| +| Storage | PostgreSQL + pgvector | +| Hosting | Docker/Python self-hosted | +| API Key Required | Yes — LLM API key for its own inference | +| LLM Costs | Yes — dialectic reasoning, dream consolidation, summarization | +| Dependencies | PostgreSQL, pgvector, LLM API key | +| Notes | Self-hosting doesn't eliminate LLM costs — Honcho runs its own inference for memory operations. Complex setup. | + +### OpenViking + +| Property | Value | +|----------|-------| +| Storage | Context database (Volcengine/ByteDance) | +| Hosting | Local server process | +| API Key Required | Optional | +| LLM Costs | Varies — needs embedding + VLM models | +| Dependencies | `pip install openviking`, running server, embedding models | +| Setup | `hermes config set memory.provider openviking`, set OPENVIKING_ENDPOINT | +| Notes | Filesystem-style knowledge hierarchy. Requires running a server daemon. | + +### RetainDB + +| Property | Value | +|----------|-------| +| Storage | Cloud API | +| Hosting | retaindb.com | +| API Key Required | Yes | +| Cost | $20/month subscription | +| Notes | Paid only. Hybrid search (Vector + BM25 + Reranking), 7 memory types. | + +### ByteRover + +| Property | Value | +|----------|-------| +| Cost | API key required | +| Notes | Paid. | + +### Supermemory + +| Property | Value | +|----------|-------| +| Cost | API key required | +| Notes | Paid. | + +### Mem0 + +| Property | Value | +|----------|-------| +| Cost | API key required or self-hosted | +| Notes | Self-hosted is complex. Managed tier is paid. | + +## Decision Flow + +1. **Just want more space with zero cost/fuss?** → Holographic (SQLite, local, free) +2. **Want knowledge graphs and deep retrieval?** → Hindsight local embedded (needs LLM API key, tokens cost) +3. **Want to run a full server?** → OpenViking or Honcho self-hosted +4. **Happy to pay?** → Hindsight Cloud, Mem0, RetainDB + +## Configuration Reference + +```yaml +memory: + memory_enabled: true + user_profile_enabled: true + provider: holographic # or builtin, honcho, mem0, openviking, hindsight, etc. +``` + +```bash +hermes memory setup # interactive picker +hermes memory status # check active provider +hermes memory off # disable external provider (reverts to built-in only) \ No newline at end of file diff --git a/skills/devops/hermes-config-management/templates/dot-gitignore.md b/skills/devops/hermes-config-management/templates/dot-gitignore.md new file mode 100644 index 0000000..b14c6da --- /dev/null +++ b/skills/devops/hermes-config-management/templates/dot-gitignore.md @@ -0,0 +1,81 @@ +# Canonical `.gitignore` for `~/.hermes/` + +Place this at `~/.hermes/.gitignore` to safely version-control your Hermes config without committing secrets or ephemeral data. + +```gitignore +# Secrets — never commit these +.env +auth.json +honcho.json + +# Ephemeral runtime data +logs/ +cache/ +sessions/ +state-snapshots/ +checkpoints/ +spawn-trees/ +sandboxes/ +whatsapp/ +pairing/ +notes/ +plugins/ +cron/output/ +backups/ + +# Downloaded binaries +node/ +bin/ +lsp/ +hermes-agent/ +platforms/ + +# SQLite databases (handled by daily snapshot cron) +memory_store.db +state.db +state.db-shm +state.db-wal + +# Lock files +*.lock +gateway.pid +gateway_state.json +processes.json + +# Shell history +.hermes_history + +# OS files +.DS_Store +Thumbs.db + +# Generated metadata +.install_method +.skills_prompt_snapshot.json +.update_check +interrupt_debug.log +models_dev_cache.json + +# Backup files +*.bak.* + +# Git credentials +.git-credentials +``` + +## Explanation of Key Exclusions + +**Secrets:** `.env` contains API keys (OpenRouter, Matrix, etc.). `auth.json` contains OAuth tokens for Spotify, GitHub Copilot, etc. Both are plaintext. + +**SQLite DBs:** `memory_store.db` (holographic memory) and `state.db` (session store) change on every session. Git handles binary diffs poorly — daily snapshot cron is better. + +**Binaries:** `node/`, `bin/`, `lsp/`, `hermes-agent/`, `platforms/` are all downloaded by the Hermes installer and can be recreated by reinstalling. + +**Plugins:** `plugins/` contains bundled plugins that are reinstalled via `hermes plugins enable` — no need to version-control. + +## Files to Track + +```bash +git add .gitignore README.md config.yaml SOUL.md memories/ skills/ scripts/ cron/ \ + kanban.db reading_*.json channel_directory.json +``` \ No newline at end of file