forked from Rockachopa/Timmy-time-dashboard
79 lines
2.6 KiB
Markdown
79 lines
2.6 KiB
Markdown
# Usage Guide
|
|
|
|
How to use the Timmy Time Dashboard repository for research, auditing, and improvement of the Hermes Agent system.
|
|
|
|
## What This Repository Is
|
|
|
|
This is an **analysis and documentation** repository. It contains the results of an empirical audit of the Hermes Agent system — 10,985 sessions analyzed, 82,645 error log lines processed, 2,160 errors categorized.
|
|
|
|
There is no application to run. The value is in the documentation.
|
|
|
|
## Reading Guide
|
|
|
|
Start here, in order:
|
|
|
|
1. **README.md** — overview and key findings. Read this first to understand the 5 root causes of agent failure and the 15 proposed solutions.
|
|
|
|
2. **hermes-agent-architecture-report.md** — deep dive into the system architecture. Covers session management, cron infrastructure, tool execution, and the gateway layer.
|
|
|
|
3. **failure_root_causes.md** — detailed breakdown of every error pattern found, with examples and frequency data.
|
|
|
|
4. **complete_test_report.md** — what testing was done and what it revealed.
|
|
|
|
5. **experiment-framework.md** — methodology for reproducing the audit.
|
|
|
|
6. **experiment_log.md** — step-by-step log of experiments conducted.
|
|
|
|
## Using the Findings
|
|
|
|
### For Developers
|
|
|
|
The 15 issues identified in the audit are prioritized in `IMPLEMENTATION_GUIDE.md`:
|
|
|
|
- **P1 (Critical):** Circuit breaker, token tracking, gateway config — fix these first
|
|
- **P2 (Important):** Path validation, syntax validation, tool fixation detection
|
|
- **P3 (Beneficial):** Session management, memory tool, model routing
|
|
|
|
Each issue includes implementation patterns with code snippets.
|
|
|
|
### For Researchers
|
|
|
|
The data supports reproducible research:
|
|
|
|
- `results/experiment_data.json` — raw experimental data
|
|
- `paper_outline.md` — academic paper structure
|
|
- `paper/main.tex` — LaTeX paper draft
|
|
|
|
### For Operators
|
|
|
|
If you run a Hermes Agent deployment:
|
|
|
|
- Check `failure_root_causes.md` for error patterns you might be hitting
|
|
- Use the circuit breaker pattern from `IMPLEMENTATION_GUIDE.md`
|
|
- Monitor for the 5 root cause categories in your logs
|
|
|
|
## Key Numbers
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Sessions analyzed | 10,985 |
|
|
| Error log lines | 82,645 |
|
|
| Total errors | 2,160 |
|
|
| Error rate | 9.4% |
|
|
| Empty sessions | 3,564 (32.4%) |
|
|
| Error cascade factor | 2.33x |
|
|
| Dead cron jobs | 9 |
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute findings, corrections, or new analysis.
|
|
|
|
## Related Repositories
|
|
|
|
- [hermes-agent](https://github.com/nousresearch/hermes-agent) — the system being analyzed
|
|
- [timmy-config](https://forge.alexanderwhitestone.com/Rockachopa/timmy-config) — Timmy's sovereign configuration
|
|
|
|
---
|
|
|
|
*Sovereignty and service always.*
|