Working in a monorepo, you’ve probably felt this: you open a session in packages/webapp/, and the agent only knows about the AGENTS.md sitting right there — the repo-root file with the whole-team conventions (branch policy, CI flow, commit rules) is invisible to it. So you either repeat those rules in every subdirectory, or watch the agent break them over and over. Starting this week, Hermes fixes this by merging the whole chain of context files automatically.

Deep in a monorepo, Hermes used to see only one layer

AGENTS.md is Hermes Agent’s primary project context file: it tells the agent how your project is structured, what conventions to follow, and what to watch out for. But previously, if you started a session in monorepo/packages/webapp/, Hermes loaded only the AGENTS.md in the current directory — the repo-root file with the “whole-repo” conventions (commit policy, branch strategy, CI flow) was invisible, unless you duplicated it into every deep directory.

Duplication brings its own problems: drift, unsynced updates, wasted context budget.

The directory chain merged into Hermes Agent main on 2026-08-08 fixes this: whenever your working directory is inside a git repository, session startup loads a merged chain of AGENTS.md files — git root first, every intermediate directory, then cwd — into the system prompt. The mechanism is a port of grok-cli’s directoryChain.

How the chain works

monorepo/                       (git root, cwd = packages/webapp/)
├── AGENTS.md                  ← loaded first (repo-wide conventions)
└── packages/
    ├── AGENTS.md              ← loaded second
    └── webapp/
        └── AGENTS.md          ← loaded last (most specific, takes precedence)

Key behaviors:

• Provenance labels: each file is injected under a relative-path heading such as ## ../../AGENTS.md or ## AGENTS.md, so the agent can tell which directory each rule came from;
• Deeper wins: deeper files appear later in the prompt, so more specific guidance takes precedence over repo-wide guidance;
• Content dedup: identical content encountered again along the chain (copied or symlinked files) is kept only once — no wasted context;
• Budget caps: each file passes through its own truncation budget, and the merged chain has an additional total cap — a deep monorepo cannot multiply context-file spend without bound;
• Security scan: every file passes the existing context-file threat scan (_scan_context_content) before it can enter the system prompt; malicious content is blocked.

Outside a git repo: parents never leak

The chain has a deliberate safety boundary: if the working directory is not inside a git repository, the chain is just [cwd] — parent directories are never consulted. An AGENTS.md planted in /tmp or $HOME can therefore never leak into unrelated sessions, mirroring the existing .hermes.md safety rationale.

The priority system: one context-file type per session

Note the directory chain applies only to AGENTS.md. Hermes’s project context types are resolved by priority:

.hermes.md / HERMES.md  →  AGENTS.md  →  CLAUDE.md  →  .cursorrules

(Only the first matching type is loaded per session; SOUL.md loads independently as global persona.) So if your repo root uses CLAUDE.md (Claude Code style), the chain does not apply — CLAUDE.md is still read from cwd only. Want the chain? Use AGENTS.md.

How this differs from progressive subdirectory discovery

Regular readers may already know Hermes’s other mechanism: when the agent reads files in a subdirectory mid-session, it progressively discovers and injects that directory’s AGENTS.md on demand (each subdirectory checked at most once per session). The directory chain complements it:

Mechanism	Timing	Coverage
Directory chain (new)	At session start	The vertical chain git root → cwd, into the system prompt
Progressive subdirectory discovery	During the session	Horizontal subdirectories the agent actually visits, injected on demand

Both are protected by the same security scan, and neither disturbs system-prompt byte stability (prompt-cache friendly).

Monorepo playbook: splitting AGENTS.md into three layers

The natural use of the chain is granularity layering:

# repo-root AGENTS.md (monorepo level)
## Shared conventions
- Every PR must pass CI and lint
- Commit messages follow Conventional Commits
- Changelog entries go into CHANGELOG.md

# packages/AGENTS.md (package level)
## Package rules
- New packages must be registered in the registry
- Cross-package deps go through public APIs only

# packages/webapp/AGENTS.md (directory level, most specific)
## Frontend-specific
- Components use TypeScript strict mode
- Styling uses design tokens only — no inline colors
- Tests live in __tests__/, run with Vitest

A session started in packages/webapp/ receives all three layers: repo conventions as the base, package rules on top, frontend specifics last. When touching frontend code, the agent won’t write commits that violate repo policy, and won’t inline colors that break the design system.

Upgrade tips

1. Sink the repo-wide conventions (branch/commit/CI) into a root AGENTS.md; deep directories should contain only rules that genuinely belong to that layer — no copying;
2. Don’t copy the same content into multiple directories — the chain dedups, but “store once” is the right answer anyway;
3. Migrating from Claude Code / Cursor? Rename the root CLAUDE.md to AGENTS.md (or add an AGENTS.md) and you get the whole chain.

To push long-task reliability further, see our long-task and timeout configuration guide; context files pair well with the productivity tips. New to Hermes Agent? Start with the install guide before experimenting.

Bottom line: organize AGENTS.md in three layers — repo, package, directory — and Hermes assembles the complete project context automatically at session start: generic conventions never get lost, specific rules naturally land last, and it all happens with zero effort.