andy/hermes-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: correct snapshot script path in cron job (was scripts/ prefix)

Browse Source
This commit is contained in:
Andy
2026-05-25 11:35:28 +00:00
parent f8f391201d
commit 822625787a
11 changed files with 541 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
channel_directory.json
View File

@@ -1,5 +1,5 @@
{
"updated_at": "2026-05-24T15:21:22.433893",
"updated_at": "2026-05-25T11:31:28.733336",
"platforms": {
"telegram": [],
"discord": [],

51
cron/jobs.json
View File

@@ -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"
}

4
memories/MEMORY.md
View File

@@ -7,3 +7,7 @@ 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.
§
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.

BIN
memory_store.db-shm Normal file
View File

Binary file not shown.

BIN
memory_store.db-wal Normal file
View File

Binary file not shown.

4
reading_state.json
View File

@@ -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
}

21
skills/.usage.json
View File

@@ -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,

181
skills/devops/hermes-config-management/SKILL.md Normal file
View File

@@ -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).

78
skills/devops/hermes-config-management/references/gitea-backup-setup.md Normal file
View File

@@ -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

129
skills/devops/hermes-config-management/references/memory-provider-comparison.md Normal file
View File

@@ -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)

81
skills/devops/hermes-config-management/templates/dot-gitignore.md Normal file
View File

@@ -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
```