docs: add shared agent knowledgebase
This commit is contained in:
@@ -0,0 +1,84 @@
|
||||
# Agent0 and Omega13 architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
Agent0 is the local Glitch University agent bundle intended to run on the Omega13 home inference server.
|
||||
|
||||
Omega13 provides local compute and long-running containers. A reverse SSH tunnel connects selected services to the public Glitch University infrastructure at `glitch.university`.
|
||||
|
||||
## Core repositories
|
||||
|
||||
Expected side-by-side checkout layout:
|
||||
|
||||
```text
|
||||
Projects/
|
||||
Agent0/
|
||||
gutasktool/
|
||||
```
|
||||
|
||||
Agent0 remote:
|
||||
|
||||
```text
|
||||
ssh://git@ramanujan.glitch.university:2222/glitch-university/Agent0.git
|
||||
```
|
||||
|
||||
gutasktool remote:
|
||||
|
||||
```text
|
||||
ssh://git@ramanujan.glitch.university:2222/glitch-university/gutasktool.git
|
||||
```
|
||||
|
||||
## Deployment model
|
||||
|
||||
Preferred operator flow on Omega13:
|
||||
|
||||
```bash
|
||||
cd ~/Projects/Agent0
|
||||
git pull
|
||||
docker compose up -d gerhard gerhard-dashboard
|
||||
```
|
||||
|
||||
Once Gerhard is stable, bring up the tunnel and then the rest of the stack:
|
||||
|
||||
```bash
|
||||
docker compose up -d glitch-tunnel
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Docker Compose services
|
||||
|
||||
The stack includes Agent Zero style agents, Hermes Gerhard, a Gerhard dashboard, Postgres/Festinger, and a tunnel.
|
||||
|
||||
Important service names include:
|
||||
|
||||
- `gerhard`
|
||||
- `gerhard-dashboard`
|
||||
- `glitch-tunnel`
|
||||
- `postgres`
|
||||
- `festinger`
|
||||
- `dobby`, `gemma`, `gunnar`, `rind`, `abyssinthia`
|
||||
|
||||
## Persistence model
|
||||
|
||||
Version control:
|
||||
|
||||
- `docker-compose.yml`
|
||||
- agent identities such as `agents/gerhard-hermes/SOUL.md`
|
||||
- shared knowledge in `shared/knowledge/`
|
||||
- shared skills and runbooks
|
||||
- `.env.example` with placeholders only
|
||||
|
||||
Host-local or ignored:
|
||||
|
||||
- `.env`
|
||||
- `auth.json`, `auth.lock`
|
||||
- Hermes `state.db*`
|
||||
- sessions and logs
|
||||
- cron runtime state such as `cron/jobs.json` and `cron/output/`
|
||||
- model caches and package caches
|
||||
|
||||
## Secrets rule
|
||||
|
||||
No secrets in Git.
|
||||
|
||||
Store credentials on Omega13 in local environment files, SSH config, Docker secrets, or service-specific auth stores. Use placeholders such as `***` or `[REDACTED]` in docs and examples.
|
||||
@@ -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/`
|
||||
@@ -0,0 +1,72 @@
|
||||
# gutasktool architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
`gutasktool` provides the `gutask` CLI for Glitch University task and agent operations.
|
||||
|
||||
Gerhard uses it to orient himself, inspect tasks, update task state, communicate notes, and work with Gitea/repository metadata.
|
||||
|
||||
## Canonical checkout
|
||||
|
||||
The useful checkout is the sibling repository beside Agent0:
|
||||
|
||||
```text
|
||||
../gutasktool
|
||||
```
|
||||
|
||||
Inside Gerhard's container it is mounted at:
|
||||
|
||||
```text
|
||||
/opt/gutasktool
|
||||
```
|
||||
|
||||
Remote:
|
||||
|
||||
```text
|
||||
ssh://git@ramanujan.glitch.university:2222/glitch-university/gutasktool.git
|
||||
```
|
||||
|
||||
## Important command
|
||||
|
||||
Gerhard orientation:
|
||||
|
||||
```bash
|
||||
/opt/data/bin/gutask orient --agent "$AGENT_ID"
|
||||
```
|
||||
|
||||
The `orient` command contacts the Glitch University API endpoint for agent orientation and prints a briefing prompt.
|
||||
|
||||
## Identity and credentials
|
||||
|
||||
The CLI should read operational credentials from environment variables, not from committed files:
|
||||
|
||||
- `API_URL`
|
||||
- `CONTENT_API_KEY`
|
||||
- `AGENT_ID`
|
||||
- `AGENT_NAME`
|
||||
- `AGENT_PASSWORD`
|
||||
- `GITEA_TOKEN` if needed by commands that talk to Gitea APIs
|
||||
|
||||
Top-level CLI flags may override environment values for one-off use.
|
||||
|
||||
## Development rule
|
||||
|
||||
When Gerhard fixes gutasktool:
|
||||
|
||||
1. Work in `/opt/gutasktool`.
|
||||
2. Inspect `git status --short --branch` before changing files.
|
||||
3. Pull/rebase carefully before pushing.
|
||||
4. Avoid reading or committing `.env` or other credentials.
|
||||
5. Run syntax/help checks before commit.
|
||||
6. Commit with a clear conventional message.
|
||||
7. Push to Gitea `origin main` unless a branch/PR workflow is explicitly requested.
|
||||
|
||||
## Known history
|
||||
|
||||
The local checkout once diverged from Gitea with local orient support ahead of origin and remote work behind it. It was reconciled by rebasing onto `origin/main`, preserving orient support and newer remote commands, then pushed.
|
||||
|
||||
Current good commit containing orientation support:
|
||||
|
||||
```text
|
||||
9a4ef82 feat: add agent orientation support
|
||||
```
|
||||
Reference in New Issue
Block a user