# Hermes Integration

How Trinity uses hosted Hermes for agent work while Phoenix, policy, and ToolRouter keep authority.

Status: implemented
Version: latest
Review: source-backed

## Runtime contract

Trinity packages project state into authenticated hosted-Hermes tasks. Hermes can plan, draft, reason over released project context, compose skills, and return action intents. Phoenix remains authoritative for account membership, run state, approval pauses, CRM data, uploaded document release state, provider readiness, and audit proof.

| Object | What Hermes receives | What Hermes must not receive |
| --- | --- | --- |
| Project context | Goal, run refs, CRM summaries, approval state, released source refs | Unreleased inbound email or document bodies |
| Tools | Read-only project tools and ToolRouter-mediated action intents | Direct adapter credentials or unmanaged side effects |
| Approvals | Approval request refs and status summaries | Authority to approve its own high-risk action |
| Skills | Approved or reusable skill summaries with proof links | Unreviewed memory made from quarantined content |
| Secrets | Provider slot labels and readiness metadata | NVIDIA key, OAuth refresh token, Stripe secret, raw credential value |

## Project context

| Context category | Source | Runtime treatment |
| --- | --- | --- |
| Project identity | Project, account, membership, owner/team records | Used for scope and authorization |
| CRM state | Companies, contacts, deals, activities, segments | Summarized into task packages and updated through approved tools |
| Revenue state | Offers, orders, checkout sessions, RevenueEvents, deals | Read as proof and used to guide fulfillment |
| Inbox state | Threads, messages, aliases, mailbox readiness | Metadata or released content only |
| Document state | Project docs, artifacts, attachment metadata | Quarantined until human release, then referenced by source ID |
| Skill state | Project, account, and global-core skill rows | Filtered by visibility and scope constraints |
| Proof state | ToolCalls, ModelDecisions, ApprovalEvents, AuditEvents | Used as evidence, not as hidden memory |

## Scoped skills and profiles

Hermes skills are not global by default. Trinity stores skills with explicit visibility and scope:

| Scope | Intended use | Database guard |
| --- | --- | --- |
| Project-private | Skills learned for one project only | Unique identity includes `account_id` and `project_id` |
| Account | Skills promoted for the owner/team across projects | Unique identity includes `account_id` and excludes `project_id` |
| Global-core | Platform-maintained baseline skills | Immutable platform path, not user-created default |

Agent profiles follow the same principle. A project can have a project-specific Hermes profile configured from account defaults. An account can keep reusable preferences and skills, while project data stays project-scoped unless intentionally promoted.

## Integration path

1. User asks Trinity to pursue a project goal in chat.
2. Phoenix stores the message, builds a project-scoped context pack, and queues Oban work.
3. Jido-backed content firewall checks source refs and quarantined content state.
4. Hosted Hermes receives only bounded, released, scoped context.
5. Hermes returns a plan, draft, skill proposal, artifact request, or action intent.
6. Phoenix converts high-risk action intents into ApprovalRequests.
7. ToolRouter executes only after policy, readiness, idempotency, and approval gates pass.
8. Run timeline, ledger, and audit surfaces link back to Hermes task proof.

## Why hosted Hermes instead of local CLI state

- The agent runtime can live outside the browser and outside a developer laptop.
- Project context is constructed from durable state.
- Runtime health and task outcomes are visible in status, run timeline, and ledger surfaces.
- Credentials stay in server-side configuration or credential vault paths.
- Project/account skill scope is enforced by Postgres-backed records rather than runtime convention.

## Primary source links

- [Hermes Agent docs](https://hermes-agent.nousresearch.com/docs/)
- [Hermes profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles/)
- [Hermes skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/)
- [Hermes providers](https://hermes-agent.nousresearch.com/docs/integrations/providers/)
- [Vendor and integration reference](/docs/reference/vendor-map)


Source paths:
- `lib/autonomous_agency/ai/hermes_runtime.ex`
- `lib/autonomous_agency/ai/hermes_runtime_client.ex`
- `lib/autonomous_agency/workers/hermes_run_worker.ex`
- `lib/autonomous_agency/hermes/agent_profile.ex`
- `lib/autonomous_agency/hermes/skill_registry.ex`
- `lib/autonomous_agency/hermes/skill.ex`
- `lib/autonomous_agency/hermes/project_context.ex`
- `lib/autonomous_agency/hermes/project_tools.ex`
- `lib/autonomous_agency/tools/hermes.ex`
- `priv/repo/migrations/20260629164000_scope_hermes_skills_and_profiles.exs`