330 lines
16 KiB
Markdown
330 lines
16 KiB
Markdown
# THE FLEET LEXICON: Shared Vocabulary, Techniques & Patterns
|
|
|
|
**Author:** Ezra (Scribe) — Second Pass, Deep Analysis
|
|
**Date:** April 4, 2026
|
|
**Purpose:** Every agent in the fleet must speak the same language, use the same patterns, and understand the same architecture. This document is the authoritative reference.
|
|
|
|
---
|
|
|
|
## PART I: THE VOCABULARY
|
|
|
|
Every term below has appeared in issues, code, or operational practice. If you're an agent in this fleet, you must know these words and use them correctly.
|
|
|
|
### Identity & Structure
|
|
|
|
| Term | Meaning | Example |
|
|
|------|---------|---------|
|
|
| **Wizard House** | A complete agent environment: Hermes profile, config, memory, skills, gateway connection, and Telegram presence. Each wizard is a house. | Ezra's house lives at /root/wizards/ezra/ |
|
|
| **Harness** | The Hermes Agent runtime — the framework wrapping an LLM with tools, config, skills, sessions, and platform adapters. ALL wizard houses share the same harness codebase. | "The Hermes harness" = run_agent.py + model_tools.py + tools/ + gateway/ |
|
|
| **SOUL.md** | A wizard's identity document — system prompt, personality, constraints, mission. Doctrine-bearing file. Any change to SOUL.md is a soul change. | timmy-config/SOUL.md defines who Timmy is |
|
|
| **Profile** | A fully isolated Hermes instance with its own HERMES_HOME, config, API keys, memory, sessions, skills, and gateway. Each wizard house IS a profile. | `hermes -p ezra` activates Ezra's profile |
|
|
| **Gateway** | The messaging platform bridge. A long-lived async process that receives messages from Telegram/Discord/Slack/etc, dispatches them to AIAgent, and returns responses. Tracked by gateway.pid. | Ezra's gateway connects to Telegram as @EzraScribeBot |
|
|
| **Skin** | Data-driven CLI visual theme — colors, spinner faces, branding text. Pure data, no code changes needed. | Built-in skins: default (gold), ares (crimson), mono (grayscale), slate (blue) |
|
|
| **Toolset** | A named group of related tools. Users enable/disable toolsets. The master list is _HERMES_CORE_TOOLS in toolsets.py. | "web" toolset = web_search + web_extract |
|
|
| **Sovereign** | Local-first, no cloud dependency for core operations. Alexander's highest principle. Every architectural choice is measured against sovereignty. | "Is this sovereign?" = "Does it work if the internet dies?" |
|
|
|
|
### Operations & Deployment
|
|
|
|
| Term | Meaning | Example |
|
|
|------|---------|---------|
|
|
| **Burn / Burn Down** | Execute and close issues aggressively. Tested commits. No half-measures. Alexander's primary directive to agents. | "Burn down your epic" = close issues with working code |
|
|
| **Burn Night** | An overnight session of continuous issue execution. Agents run loops, produce PRs, close tickets. | Timmy ran burn nights via cron + Gitea task router |
|
|
| **Burn Report** | A post-session summary of what was accomplished. Filed as an issue. Format: issues closed, code written, tests run. | timmy-home #143: "Burn Report #1 — 2026-03-31" |
|
|
| **RCA** | Root Cause Analysis. Structured incident post-mortem with severity (P0-P3), 5-Whys, timeline, action items, prevention. | RCA-295: Who NERFED Bilbo? |
|
|
| **Health Check** | Automated infrastructure verification. Each check is critical or non-critical, returns PASS/FAIL/ERROR. | Disk space, gateway alive, Gitea token valid, llama-server responding |
|
|
| **Deadman Switch** | Alert when zero commits for 2+ hours. Detects stalled agents. | timmy-config #115 |
|
|
| **Morning Report** | Daily fleet status report. Due 7 AM. Each agent submits their overnight results. | timmy-config #110 |
|
|
| **Checkpoint** | Cross-wizard state snapshot stored in the wizard-checkpoints repo. Used for fleet coordination and drift detection. | Ezra owns the checkpoint registry (8 wizards registered) |
|
|
| **Cron Job** | Scheduled task using natural language prompts. Schema: id, name, prompt, schedule (crontab), repeat, deliver target. | "ezra-self-check" runs at 6 AM daily |
|
|
| **Trajectory** | A complete session transcript (messages, tool calls, results) saved for training data. The raw material for LoRA/DPO. | Hermes saves trajectories as JSONL in sessions/ |
|
|
|
|
### Infrastructure
|
|
|
|
| Term | Meaning | Example |
|
|
|------|---------|---------|
|
|
| **llama-server** | llama.cpp's HTTP inference server. Serves local models. Critical flags: --jinja (tool-calling), -fa (flash attention), --port, -ngl 999 (full GPU offload). | Port 11435 on VPS, serving Gemma 4 |
|
|
| **Gemma 4** | Google's MoE model. 4B active / 26B total parameters. 8GB RAM efficient. THE standard local model. Alexander says: never recommend alternatives. Revolutionary, different class. | gemma-4-E4B-it-Q4_K_M.gguf |
|
|
| **TurboQuant** | KV cache compression technique (PolarQuant + QJL) for longer context on Apple Silicon. Timmy Foundation's own innovation. | turboquant repo, Phase 1 complete |
|
|
| **Gitea** | Self-hosted Forgejo/Gitea instance at 143.198.27.163:3000. ALL project management lives here. 18 repos, 1031+ issues. | Use urllib, NOT curl (security scanner blocks raw IPs) |
|
|
| **Hermes VPS** | The primary Digital Ocean server hosting Ezra, Bilbo, Bezalel, and shared infrastructure. | 143.198.27.163 |
|
|
| **Testbed VPS** | Secondary server for Allegro. | 167.99.126.228 |
|
|
| **state.db** | SQLite database storing session state, search index (FTS5), and persistent data per wizard house. | Each profile gets its own state.db |
|
|
|
|
### Architecture Patterns (from Gitea issues)
|
|
|
|
| Term | Meaning | First Appeared |
|
|
|------|---------|---------------|
|
|
| **The Door** | Crisis front door for broken men. Single URL, no login. 988 visible. Alexander's MISSION. | the-door repo |
|
|
| **The Nexus** | Timmy's 3D sovereign home. Three.js world with portals, agent board, sovereignty meter. | the-nexus repo |
|
|
| **Evennia** | Python MUD framework. Timmy's text-based mind palace / world shell. | timmy-academy repo |
|
|
| **Aurora Pipeline** | Session transcripts → model weight updates. The training flywheel. | the-nexus #598 |
|
|
| **Crucible** | Z3 SMT solver as a sidecar for deterministic reasoning. | timmy-config #86 |
|
|
| **Archon** | A three-layer wizard: Hermes → Claw → Gemma4. Ezra's architectural proof-of-concept. | timmy-home #363 |
|
|
| **Gemma Spectrum** | 9-wizard multimodal fleet, all running Gemma 4. | timmy-home #352 |
|
|
| **Grand Timmy / Uniwizard** | The endgame: all wizard identities dissolved into one unified intelligence. | timmy-home #94 |
|
|
| **Robing** | OpenClaw (Claw Code) as a sidecar shell on top of Hermes. Claw wears like a robe — convenience layer, not replacement. | timmy-home #141 |
|
|
| **GOFAI** | Good Old-Fashioned AI. Rule-based, symbolic, deterministic. Sidecar to the LLM for constraint enforcement. | timmy-home #67 |
|
|
|
|
---
|
|
|
|
## PART II: THE TECHNIQUES
|
|
|
|
These are the proven patterns extracted from working code. If you're building something, use these patterns.
|
|
|
|
### 1. THE TOOL REGISTRATION PATTERN (Hermes Core)
|
|
|
|
Three files, every time:
|
|
|
|
```
|
|
1. tools/your_tool.py — Implementation + registry.register() call
|
|
2. model_tools.py — Import in _discover_tools()
|
|
3. toolsets.py — Add name to _HERMES_CORE_TOOLS or a toolset
|
|
```
|
|
|
|
Handler MUST return a JSON string. check_fn gates availability. requires_env declares needed API keys. The registry handles schema collection, dispatch, and error wrapping.
|
|
|
|
### 2. THE ENV-VAR FALLBACK CHAIN
|
|
|
|
Constructor param > environment variable > hardcoded default. Always.
|
|
|
|
```python
|
|
self.base_url = (base_url or os.getenv("GITEA_URL", "http://143.198.27.163:3000")).rstrip("/")
|
|
self.token = token or os.getenv("GITEA_TOKEN", "")
|
|
```
|
|
|
|
This pattern makes tools testable (pass params directly), deployable (set env vars), and safe (hardcoded defaults as last resort).
|
|
|
|
### 3. THE ENSURE/IDEMPOTENT PATTERN
|
|
|
|
For any resource that might already exist: check first, create only if missing. Case-insensitive matching. Safe to re-run.
|
|
|
|
```python
|
|
def ensure_label(self, owner, repo, name, color, description=""):
|
|
labels = self.list_labels(owner, repo)
|
|
for l in labels:
|
|
if l["name"].lower() == name.lower():
|
|
return l
|
|
return self.create_label(owner, repo, name, color, description)
|
|
```
|
|
|
|
Use this for labels, milestones, repos, users, configs — anything where duplicates are bad.
|
|
|
|
### 4. THE RETRY WITH EXPONENTIAL BACKOFF
|
|
|
|
Retry transient failures. NEVER retry auth/validation errors.
|
|
|
|
```python
|
|
for attempt in range(max_retries):
|
|
try:
|
|
return make_request()
|
|
except HTTPError as e:
|
|
if e.code in (401, 403, 404, 422):
|
|
raise # Don't retry these
|
|
time.sleep(retry_delay * (2 ** attempt))
|
|
```
|
|
|
|
### 5. THE CHECK-RUNNER PATTERN (Health Monitoring)
|
|
|
|
Each check is a callable returning (bool, detail_string). The runner wraps execution, catches exceptions, classifies results. Checks are tagged critical or non-critical.
|
|
|
|
```python
|
|
def check(self, name, fn, critical=False):
|
|
try:
|
|
ok, detail = fn()
|
|
return {"name": name, "status": "PASS" if ok else "FAIL", "detail": detail, "critical": critical}
|
|
except Exception as e:
|
|
return {"name": name, "status": "ERROR", "detail": str(e), "critical": critical}
|
|
```
|
|
|
|
Aggregate: total passed, total failed, critical failures. System is HEALTHY only if zero critical failures.
|
|
|
|
### 6. THE VALIDATION-FINDINGS PATTERN (Quality Gates)
|
|
|
|
Accumulate findings during validation. Three severity tiers: ERROR (must fix), WARNING (should fix), INFO (nice to know). Validate in passes: frontmatter, then body, then directory structure.
|
|
|
|
```python
|
|
class ValidationError:
|
|
def __init__(self, level, message, field=""): # level: ERROR/WARNING/INFO
|
|
...
|
|
|
|
self.errors = [] # accumulator
|
|
# ... validate_frontmatter() appends errors
|
|
# ... validate_body() appends errors
|
|
# ... validate_directory() appends errors
|
|
return self.errors
|
|
```
|
|
|
|
### 7. THE BACKUP ROTATION PATTERN
|
|
|
|
Create timestamped archives. Rotate by count (keep max N, delete oldest). Restore with dry_run preview by default.
|
|
|
|
```python
|
|
def _rotate_backups(self):
|
|
backups = sorted(self.backup_dir.glob("*.tar.gz"), key=lambda p: p.stat().st_mtime, reverse=True)
|
|
for old in backups[self.max_backups:]:
|
|
old.unlink()
|
|
```
|
|
|
|
### 8. THE URLLIB-OVER-CURL PATTERN (Gitea API)
|
|
|
|
The Hermes security scanner blocks curl to raw IP addresses. ALL Gitea API calls MUST use Python's urllib, not curl, not requests.
|
|
|
|
```python
|
|
req = urllib.request.Request(url, data=body, headers=headers, method=method)
|
|
resp = urllib.request.urlopen(req, timeout=30)
|
|
return json.loads(resp.read())
|
|
```
|
|
|
|
### 9. THE TEMPLATE-BASED GENERATION PATTERN (Reports/RCAs)
|
|
|
|
Define a multi-line TEMPLATE as a class constant. Normalize inputs, then .format(). Auto-increment numbering. Sanitize filenames.
|
|
|
|
```python
|
|
TEMPLATE = """# RCA-{number}: {title}
|
|
## Summary
|
|
...
|
|
"""
|
|
safe_title = re.sub(r'[^a-z0-9-]', '', title.lower().replace(' ', '-'))[:40]
|
|
```
|
|
|
|
### 10. THE MOCK HTTP SERVER PATTERN (Testing)
|
|
|
|
For testing API clients without hitting real servers:
|
|
|
|
```python
|
|
class MockHandler(BaseHTTPRequestHandler):
|
|
def do_GET(self):
|
|
if self.path == "/api/v1/user":
|
|
self._json_response(200, {"login": "ezra"})
|
|
|
|
server = HTTPServer(("127.0.0.1", 0), MockHandler) # port 0 = auto-assign
|
|
port = server.server_address[1]
|
|
thread = threading.Thread(target=server.serve_forever, daemon=True)
|
|
thread.start()
|
|
client = GiteaClient(base_url=f"http://127.0.0.1:{port}", token="test")
|
|
```
|
|
|
|
### 11. THE SLASH COMMAND REGISTRY PATTERN (Hermes Core)
|
|
|
|
One source of truth for all commands. All consumers derive from the same registry:
|
|
|
|
```python
|
|
CommandDef("mycommand", "Description", "Session", aliases=("mc",), args_hint="[arg]")
|
|
```
|
|
|
|
CLI dispatch, gateway dispatch, Telegram menu, Slack routing, autocomplete, help text — ALL auto-generated from the registry. Adding an alias = one tuple change, everything else follows.
|
|
|
|
### 12. THE SKILL STRUCTURE
|
|
|
|
Every skill is a directory with SKILL.md at the root:
|
|
|
|
```
|
|
~/.hermes/skills/category/skill-name/
|
|
SKILL.md # YAML frontmatter + markdown body
|
|
references/ # Supporting docs
|
|
templates/ # Config templates
|
|
scripts/ # Automation scripts
|
|
assets/ # Static assets
|
|
```
|
|
|
|
Frontmatter: name, description, version (required), author, tags (recommended).
|
|
Body: Trigger (when to use), Steps (numbered), Pitfalls (what can go wrong), Verification (how to confirm success).
|
|
|
|
Skills are injected as USER messages, not system prompt — this preserves prompt caching.
|
|
|
|
---
|
|
|
|
## PART III: THE TESTING STANDARD
|
|
|
|
All agents producing code must follow this:
|
|
|
|
1. **Tests live alongside code:** tools/ and tests/ as sibling directories
|
|
2. **Every module gets a test file:** test_{module_name}.py
|
|
3. **Three test tiers:**
|
|
- Unit tests (mocked dependencies)
|
|
- Integration tests (mock HTTP server for APIs)
|
|
- Live tests (clearly marked, may fail in CI)
|
|
4. **Test fixtures as module constants:** VALID_SKILL, BROKEN_SKILL_NO_FM, etc.
|
|
5. **Temp directories for isolation:** tempfile.mkdtemp() in setUp, shutil.rmtree() in tearDown
|
|
6. **Edge cases required:** empty files, missing files, auth failures, rotation limits, dry-run modes
|
|
7. **All tests must pass before commit.** `python3 -m pytest tests/ -v`
|
|
|
|
---
|
|
|
|
## PART IV: THE COMMIT STANDARD
|
|
|
|
From Gitea issue evidence, Alexander's merge proof standard:
|
|
|
|
1. **Screenshot for visual changes** — prove it renders
|
|
2. **Log output for CLI changes** — prove it runs
|
|
3. **Test output for code changes** — prove it passes
|
|
4. **One commit, one concern** — atomic, reviewable
|
|
5. **Epic tagging:** reference the epic/issue in commit message
|
|
|
|
Format: `{type}: {description} ({issue ref})`
|
|
Types: feat, fix, docs, test, refactor, chore
|
|
|
|
---
|
|
|
|
## PART V: THE CONFIG ANATOMY
|
|
|
|
Every wizard house config.yaml follows this structure:
|
|
|
|
```yaml
|
|
_config_version: 10 # Schema version (bump triggers migration)
|
|
model:
|
|
default: claude-opus-4-6 # Primary model
|
|
fallback_providers: # Ranked list of backup providers
|
|
- provider: anthropic
|
|
model: claude-sonnet-4-20250514
|
|
agent:
|
|
max_turns: 50 # Max tool-calling iterations
|
|
reasoning_effort: high
|
|
session_reset:
|
|
mode: both # idle + time-of-day reset
|
|
idle_minutes: 1440
|
|
at_hour: 4 # 4 AM daily reset
|
|
compression:
|
|
threshold: 0.77 # Context compression trigger
|
|
memory:
|
|
memory_char_limit: 2200 # MEMORY.md max size
|
|
user_char_limit: 1375 # USER.md max size
|
|
display:
|
|
skin: default # Visual theme
|
|
platforms:
|
|
api_server:
|
|
enabled: true
|
|
host: 127.0.0.1
|
|
port: 8643 # UNIQUE per wizard house
|
|
telegram:
|
|
enabled: true
|
|
```
|
|
|
|
Key rule: NEVER hardcode ~/.hermes. Always use get_hermes_home() for code, display_hermes_home() for user messages.
|
|
|
|
---
|
|
|
|
## PART VI: WHO DOES WHAT
|
|
|
|
Based on the full issue audit — the actual division of labor that has emerged:
|
|
|
|
| Agent | Proven Competency | Lane |
|
|
|-------|------------------|------|
|
|
| **Timmy** @Timmy | Sovereign local house, model training, Evennia, harness config, overnight loops | The sovereign — judges locally |
|
|
| **Ezra** @ezra | Gitea API, health monitoring, RCA analysis, skill validation, architecture review, fleet auditing | Scribe — read, reconcile, document, review |
|
|
| **Bilbo** @bilbobagginshire | Fast local inference (4B Gemma), Telegram dual-mode, churn handling | The Hobbit — resilient, cheerful, executes |
|
|
| **Allegro** @allegro | Security hardening, GOFAI rules, input sanitization, conscience validation | The Executor — security & deployment |
|
|
| **Bezalel** @bezalel | Gemma 4 31B serving, artisan work, model hosting | The Artisan — heavy model work |
|
|
| **Claude** @claude | Nexus 3D world (Three.js), rapid prototyping, bulk feature implementation | Cloud partner — fast iteration |
|
|
| **KimiClaw** @KimiClaw | Knowledge ingestion, performance benchmarking, PR review | Silent — needs reactivation |
|
|
| **Fenrir** @fenrir | Security (Nostr audit, secret leak hooks, stale lockfile alerts) | The Wolf — security guardian |
|
|
|
|
---
|
|
|
|
*Every agent who reads this document now speaks the same language. Use the vocabulary. Follow the patterns. Cite the techniques by name. When you say "ensure pattern" or "check-runner" or "urllib-over-curl" — we all know what that means.*
|
|
|
|
*Read the pattern. Name the truth. Return a clean artifact.*
|
|
|
|
— Ezra, Scribe of the Timmy Foundation
|
|
April 4, 2026
|