docs/hermes/memory.md

# Hermes Memory Layer

## Purpose

This layer stores durable context that future Codex, Hermes, Claude, or
agent-team workers should remember before changing Hermes-related utilities.

## Current State

- Hermes / agent-team integration is an auxiliary operations layer, not a
  prediction-model layer.
- Current helper utilities include Telegram notification wrappers, W&B
  experiment tracking, data quality validation, and agent-team integration
  tests.
- `hermes_tools is not importable` inside the normal project venv, so
  `scripts/telegram_bot_wrapper.py` uses fallback console output unless Hermes
  injects that module at runtime.
- `.env.telegram` and `.env.wandb` are local-only files and should not be
  committed.
- `.env.telegram.example` is the shareable template.

## Decisions To Preserve

- Keep Hermes changes independent from core predictor code by default.
- Treat Telegram and W&B as optional observability helpers.
- Treat data quality validation as a preflight check, not proof of model
  accuracy.
- Record experiment results in JSON/HTML reports before changing production
  weights.
- Store lessons compactly in memory docs and keep detailed evidence in
  `docs/validation_runs/`.

## Known Side Effects Already Fixed

- `scripts/telegram_bot_wrapper.py` now parses `.env.telegram` as a key/value
  dict instead of a set.
- `scripts/telegram_bot_wrapper.py` now uses mode-specific CLI validation so
  `--update`, `--validation`, and experiment modes can run without a dummy
  `--message`.
- `scripts/test_agent_integration.py` now imports `argparse`.
- `scripts/test_agent_integration.py` now checks Antigravity CLI/config rather
  than importing Python's built-in `antigravity` easter egg.

## Update Rule

Append a short note here only when a change affects:

- Hermes runtime assumptions
- Telegram or W&B configuration
- validation commands
- production/HF publish boundaries
- known data gaps or failures

Do not paste long logs. Link to JSON/HTML artifacts or command names instead.