docs: add shared agent knowledgebase

2026-04-26 18:51:31 +02:00
parent fcf1b91224
commit e4a37bd705
13 changed files with 652 additions and 2 deletions
@@ -0,0 +1,106 @@
+# Gerhard Hermes architecture
+
+## Identity
+
+Gerhard Rug is the first priority Hermes agent in Agent0.
+
+Gerhard's identity file is:
+
+```text
+agents/gerhard-hermes/SOUL.md
+```
+
+Inside the container, Hermes home is:
+
+```text
+/opt/data
+```
+
+So Gerhard reads his soul at:
+
+```text
+/opt/data/SOUL.md
+```
+
+## Container mounts
+
+Gerhard is expected to mount:
+
+```text
+./agents/gerhard-hermes   -> /opt/data
+./agents/gerhard-workspace -> /workspace
+../gutasktool             -> /opt/gutasktool
+./shared/knowledge        -> /knowledge
+${HOME}/.ssh              -> /root/.ssh
+```
+
+`/opt/gutasktool` is read-write so Gerhard can improve gutasktool, commit, and push to Gitea when instructed or when a task requires it.
+
+`/knowledge` is the shared library. It is not Hermes memory. It is version-controlled institutional knowledge.
+
+## Environment
+
+Gerhard receives local credentials from Agent0's host-local `.env` via Docker Compose.
+
+Expected variables include:
+
+- `API_URL`
+- `CONTENT_API_KEY`
+- `AGENT_ID`
+- `AGENT_NAME`
+- `AGENT_PASSWORD`
+- provider keys such as `ANTHROPIC_TOKEN` when needed
+
+Do not commit these values.
+
+## gutask access
+
+Gerhard has a wrapper at:
+
+```text
+/opt/data/bin/gutask
+```
+
+The wrapper runs:
+
+```bash
+python3 /opt/gutasktool/gutasktool/cli.py "$@"
+```
+
+Use the absolute path in cron prompts because container `PATH` may vary:
+
+```bash
+/opt/data/bin/gutask orient --agent "$AGENT_ID"
+```
+
+## Scheduled orientation
+
+The desired source of truth for Gerhard scheduled jobs is:
+
+```text
+agents/gerhard-hermes/cron/desired-jobs.json
+```
+
+Hermes live cron runtime state is stored in `cron/jobs.json` and should remain ignored because it mutates as jobs run.
+
+On wake, Gerhard should:
+
+1. Read `/opt/data/SOUL.md`.
+2. Read `/knowledge/README.md` and relevant shared knowledge files.
+3. Run `/opt/data/bin/gutask orient --agent "$AGENT_ID"`.
+4. Use the returned task orientation as current work context.
+5. Keep final reports short, in Gerhard voice.
+
+## Runtime state
+
+Do not version Hermes runtime state unless explicitly reviewed.
+
+Examples to keep ignored:
+
+- `agents/gerhard-hermes/state.db*`
+- `agents/gerhard-hermes/sessions/`
+- `agents/gerhard-hermes/logs/`
+- `agents/gerhard-hermes/gateway_state.json`
+- `agents/gerhard-hermes/channel_directory.json`
+- `agents/gerhard-hermes/cron/jobs.json`
+- `agents/gerhard-hermes/cron/output/`