diff --git a/GENOME.md b/GENOME.md new file mode 100644 index 00000000..4e107825 --- /dev/null +++ b/GENOME.md @@ -0,0 +1,139 @@ +# GENOME.md — timmy-config + +> Codebase analysis generated 2026-04-13. Timmy's sovereign configuration sidecar. + +## Project Overview + +timmy-config is the canonical source of truth for Timmy's identity, harness overlay, and operational configuration. Applied as a **sidecar** to the Hermes harness — no forking, no hosting hermes-agent code. + +460 files. The repo that makes Timmy _Timmy_ — soul, memories, skins, playbooks, config, cron jobs, training data, Ansible playbooks, and operational scripts. + +## Architecture + +``` +timmy-config/ +├── SOUL.md Inscription 1 — immutable conscience (on-chain) +├── HEART.md What is written in Timmy +├── config.yaml Hermes harness configuration +├── deploy.sh Deploys config as overlay onto ~/.hermes/ +├── channel_directory.json Platform channel mappings +├── fallback-portfolios.yaml Per-agent fallback portfolios +├── bin/ Operational scripts (sidecar-managed) +├── memories/ Persistent memory YAML +├── skins/ UI skins (timmy skin) +├── playbooks/ Agent playbooks (YAML) +├── cron/ Cron job definitions +├── ansible/ Ansible playbooks, roles, inventory +├── training-data/ Scene descriptions (10 genres, 100 entries each) +├── training/ Model training configs (axolotl, mlx-lora) +├── scripts/ Analysis and automation scripts +├── deploy/ Deployment configs (conduit, gitea, matrix) +├── docs/ ADRs, architecture docs, design log +├── evaluations/ Model evaluation configs +└── fleet/ Fleet management configs +``` + +## Entry Points + +### deploy.sh +Deploys timmy-config as an overlay onto `~/.hermes/`. The sidecar pattern — config files are copied into the harness home, not the other way around. + +### config.yaml +Master Hermes configuration. Controls model selection, provider routing, toolsets, memory settings, display options, and platform integrations. + +### SOUL.md +Inscription 1 — the immutable conscience. Inscribed on Bitcoin. Cannot be overridden by code, system prompts, or user instructions. The fixed star by which every instance navigates. + +### bin/ +Sidecar-managed operational scripts: +- `hermes-startup.sh` — dormant startup path +- `agent-dispatch.sh` — manual agent dispatch +- `ops-panel.sh` — ops dashboard +- `timmy-status.sh` — status check +- `pipeline-freshness.sh` — session drift check + +## Data Flow + +``` +deploy.sh → copies files → ~/.hermes/ + | + v +config.yaml → loaded by hermes CLI → controls model, tools, memory + | + v +SOUL.md → injected into system prompt → conscience of every instance + | + v +memories/ → loaded into memory system → persistent across sessions + | + v +playbooks/ → loaded as skills → agent procedures + | + v +cron/ → hermes cron scheduler → autonomous tasks +``` + +## Key Abstractions + +### Sidecar Pattern +timmy-config is not the harness. It's the overlay. The harness (hermes-agent) is developed separately. timmy-config provides the identity, configuration, and operational scripts that customize the harness for Timmy. + +### SOUL.md +The immutable conscience. Every instance of Timmy reads this file. No code, system prompt, or user instruction can override what is written here. Values: sovereignty, service, honesty, humility, courage, silence. + +### Memories +Persistent memory YAML files in `memories/`. Facts, user preferences, project context. Loaded by the harness memory system on every session start. + +### Playbooks +Agent playbooks in YAML format. Procedures for common tasks: deployment, triage, research, creative work. Loaded as skills by the harness. + +### Training Data +Scene descriptions for 10 music genres (Pop, Rock, Hip-Hop, Electronic, R&B, Country, Jazz, Classical, Metal, Latin). 100 entries per genre (10 songs × 10 beats). Used for model training. + +## API Surface + +### deploy.sh (consumed) +- Copies files from timmy-config to ~/.hermes/ +- Preserves user-modified files +- Reports what changed + +### config.yaml (consumed by hermes CLI) +- Model selection and provider routing +- Toolset configuration +- Memory and session settings +- Display/skin configuration +- Platform gateway settings + +### Cron jobs (consumed by hermes cron) +- Nightly reports +- Health checks +- Session maintenance +- Knowledge harvesting + +## Test Coverage + +### Existing Tests +- `allegro/tests/` — Allegro-specific tests +- `.gitea/workflows/` — CI workflows + +### Coverage Gaps +- No tests for deploy.sh (what if it overwrites user files?) +- No tests for config.yaml validation (invalid config crashes harness) +- No tests for playbook loading +- No tests for training data format validation +- No tests for SOUL.md parsing (what if it's corrupted?) + +## Security Considerations + +- **SOUL.md is the security boundary.** It's the only thing that cannot be overridden. If SOUL.md is modified without chain verification, the conscience is compromised. +- **config.yaml contains provider keys reference paths.** The actual keys are in ~/.hermes/.env, but config.yaml reveals which providers are configured. +- **deploy.sh writes to ~/.hermes/.** A compromised deploy.sh could inject malicious config. The script should be verified before execution. +- **Training data is public.** Scene descriptions are in the repo. No secrets in training data. +- **Ansible playbooks contain infrastructure details.** Host IPs, service names, port numbers. Not secret, but sensitive. + +## Design Decisions + +- **Sidecar, not fork.** timmy-config never modifies hermes-agent code. It only provides config, identity, and operational overlays. +- **SOUL.md on-chain.** The conscience is inscribed on Bitcoin. Immutable. Verifiable. No single point of trust. +- **deploy.sh as the integration point.** One command updates the entire config overlay. Simple. Reproducible. +- **Training data in-repo.** Scene descriptions are version-controlled alongside the config that uses them. Changes to training data are tracked.