portable-hermes-agent AGENTS.md

Hermes Agent - Development Guide

Instructions for AI coding assistants and developers working on the hermes-agent codebase.

Never give up on the right solution.

What Hermes Is

Hermes is a personal AI agent that runs the same agent core across a CLI, a messaging gateway (Telegram, Discord, Slack, and ~20 other platforms), a TUI, and an Electron desktop app. It learns across sessions (memory + skills), delegates to subagents, runs scheduled jobs, and drives a real terminal and browser. It is extended primarily through plugins and skills, not by growing the core.

Two properties shape almost every design decision and are the lens for reviewing any change:

• Per-conversation prompt caching is sacred. A long-lived conversation reuses a cached prefix every turn. Anything that mutates past context, swaps toolsets, or rebuilds the system prompt mid-conversation invalidates that cache and multiplies the user's cost. We do not do it (the one exception is context compression).
• The core is a narrow waist; capability lives at the edges. Every model tool we add is sent on every API call, so the bar for a new core tool is high. Most new capability should arrive as a CLI command + skill, a service-gated tool, or a plugin — not as core surface.

Contribution Rubric — What We Want / What We Don't

This is the project's intent layer. Use it two ways:

1. For humans and for your own work — what gets merged and what gets rejected, so a contribution aims at the target.
2. For automated review (the triage sweeper) — guidance on when a PR is safe to close on the three allowed reasons (implemented_on_main, cannot_reproduce, incoherent) and, just as important, when NOT to close one. Taste-based "we don't want this / out of scope" closes are NOT an automated decision — those stay with a human maintainer. The sweeper's job here is to recognize design intent and avoid wrongly closing a legitimate contribution, not to make the won't-implement call itself.