timmy-config/GENOME.md

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.