Hermes Agent

Tool class: AI agent workspace

Hermes Agent is an open-source agent harness made by Nous Research. It runs on a computer or server that you control, works with a model provider that you configure, and can run commands, read and write files, and use connected tools. For Hermes Agent, a topic’s AI agent workspace is one working directory for the topic, with a project context file, AGENTS.md, that Hermes Agent reads when it works in that directory.

Hermes Agent also loads Agent Skills: folders that each contain a SKILL.md file with instructions for one kind of task. Skills are installed in ~/.hermes/skills for the user account that runs the agent, so every topic on that installation uses the same skills. Topic-specific context goes in the topic’s AGENTS.md, not in a skill.

Set up the surface for one topic

These steps use the example topic Example Co Operations (topic code EXOP).

1. Confirm the topic in the registry. Use the exact topic code and name.
2. Search the machine or server that runs Hermes Agent for an existing working directory for the topic. If one exists, use it. If two exist, record a provisioning gap.
3. Create one working directory for the topic, named with the lowercase topic code and the canonical name: exop-exampleco-operations. This is the same form as the chat channel names, without the channel suffix.
4. Write AGENTS.md at the root of the directory (see Settings).
5. If the directory is kept under version control, keep it in a repository of the topic in the organization’s account. Its name already starts with the repository prefix exop-, so it is part of the topic’s code repository surface. List it in the topic profile.
6. Install only the skills that the organization has approved (see Settings).
7. Configure the model provider, connected tools, and messaging connections within the topic’s access boundary (see Permissions).
8. Add the location of the working directory, and the repository if there is one, to the topic profile and to the Topic Surfaces table of the purpose page.

Settings

• Working directory. One directory per topic: exop-exampleco-operations. Start Hermes Agent in this directory for work on the topic, so that it reads the topic’s AGENTS.md. Do not start it in a directory that holds several topics.
• AGENTS.md. Short and specific to the topic. It states the topic, its purpose, the terms it uses, the limits on what the agent may do, and where the topic’s records are. It links to the records instead of copying them. A starting point:

# EXOP Example Co Operations

This directory is the AI agent workspace for the topic EXOP Example Co Operations
(venture Example Co, unit Operations, topic code EXOP).

Purpose of the topic: [one or two sentences from the Space Purpose and Usage page]

## Records of the topic (the source of truth)

- Accountable work and the Focus System: [link to the EXOP project]
- Durable knowledge: [link to the Space Purpose and Usage page]
- Files: [link to the shared drive EXOP Example Co Operations]
- Topic profile: [link]

Method: Topic Focused Workflow. Read https://tfw.how/llms.txt for the terms.

## Rules

- Your output is a draft. Propose changes; do not present a proposal as a decision.
- Look up topic codes in the registry: [link]. Do not rely on a list in this file.
- Change other tools only for these approved actions: [list, or "none"].
- Ask before you run a command that changes files outside this directory.
- Do not write credentials into this directory.

• Skills. A skill is a folder with a SKILL.md file. Hermes Agent can install skills from a GitHub repository with hermes skills tap add <owner>/<repo>. Install skills only from sources that the organization has approved, and read a skill before you install it, because a skill can tell the agent to run commands. Keep skills general to the method or to a kind of task, so that they are correct for every topic on the installation.
• Memory. Hermes Agent can keep memory across sessions. Unless memory is kept separately for each topic, it is shared by every topic that the installation works on. Memory is not a record of the topic. A fact that must last is written to its source of truth.
• Credentials. Keep model provider keys and tool tokens in the agent’s own configuration or in the organization’s secrets manager. Never put them in AGENTS.md, in a skill, or in the topic’s repository.
• Reference material. Keep stable material only, for example a glossary of the topic’s terms. Link to records that change instead of saving a copy in the directory.

Permissions

Hermes Agent acts with the permissions of the account that runs it and of the tokens it is given.

• Run it under an account that can reach the topic’s working directory and the resources the approved actions need, and no more. A shared installation that serves several topics can reach the records of all of them; if the access boundaries of those topics differ, use a separate installation or account for the topic, and record the reason.
• Give each connected tool a token with the narrowest scope the approved actions need, preferably a token for the agent and not a person’s own login. A connection to a tool does not authorize the agent to change records there.
• If Hermes Agent is connected to a messaging platform, connect it only to the topic’s own channels, for example the automated channel for its notifications, and limit who can send it instructions.
• Use the product’s settings that require approval before the agent runs commands, especially commands that change or delete files.
• If the working directory is in a repository, grant access to the repository through the topic’s access groups, as on the GitHub page.

Maintenance

The maintainer checks the workspace on a regular schedule:

• The directory name still matches the topic code and the canonical name.
• AGENTS.md still describes the topic, the links still work, and they point to the current surfaces.
• The directory has no copies that went out of date, no credentials, and no material outside the access boundary.
• The installed skills are still approved and current. Remove skills that are no longer used.
• Tokens for connected tools are still needed, still narrow, and not expired. Revoke tokens that are no longer used.
• Results from recent sessions were written to the source of truth.

When the topic becomes inactive:

1. Add a first line to AGENTS.md that states that the topic is inactive and links to any topic that took over the work.
2. Revoke the tokens and messaging connections used only for the topic.
3. Archive the repository, if there is one, or remove the working directory according to the retention rule.
4. Update the topic profile and the purpose page.

Agent notes

• Read AGENTS.md in the working directory before you start. If the request is about another topic, say so, and work in that topic’s directory instead.
• Treat your output as a draft. Write a result that must last to its source of truth only when a person asks you to, and report the link.
• Do not use remembered context from another topic as a fact about this topic.
• Use a skill for the method, and AGENTS.md for the facts of the topic. When they disagree, follow AGENTS.md and report the difference.
• Ask before a command that changes files outside the working directory, and before every write to another tool.
• Mark statements that you have not checked against a record as unverified.