Merge PR #788: GENOME.md

2026-04-16 05:14:34 +00:00
parent 2920236376
commit 1a7a666287
1 changed files with 139 additions and 0 deletions
--- a/GENOME.md
+++ 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.