Context Files as Knowledge Injection

+15 Mana ✨
Hermes context files(DOCUMENTATION)

Introduction

Memory is what the agent learns over time. Context files are what your project hands the agent the moment a session starts. The two systems serve different jobs and combine naturally. Once you see context files as "knowledge injection" rather than "another kind of memory", the design choices Hermes makes around them become obvious.

Key Concepts

  • Context file: A plain text or Markdown file whose contents get pasted into the prompt to brief the agent.
  • Auto-discovery: Hermes finds context files automatically by walking the working directory and known paths; you do not pass them by hand.
  • Project context vs identity context: AGENTS.md is about a project; USER.md is about you.
  • Frozen versus just-in-time: A project context file loads once at session start; nested context files load on first access during the session.

Real World Context

A backend engineer pulls down a new repo and runs Hermes inside it. The repo has an AGENTS.md at the root explaining the architecture, conventions, and a few prohibitions ("never edit migrations directly"). Without that file, the agent would have to discover those rules through trial and error. With it, the agent starts the first session already calibrated. That is what context injection does.

Deep Dive

The Hermes context injection system has two layers, in order of how often they fire:

  1. Auto-discovery at session start: Hermes walks the working directory and its ancestors to find a project context file. The first match wins among .hermes.md (or HERMES.md), AGENTS.md, CLAUDE.md, and .cursorrules. In parallel, SOUL.md is loaded independently from HERMES_HOME for personality, and persistent memory (USER.md, MEMORY.md) is read from ~/.hermes/memories/.
  2. Progressive subdirectory discovery during the session: As the agent navigates into subdirectories using tools like read_file, terminal, or search_files, additional context files in those subdirectories load on first access. This keeps the system prompt lean at startup and brings in nested context just-in-time when it becomes relevant.

Notice the design: the cheap-and-common case (project context at startup) is automatic. The deeper case (subsystem-specific context that may or may not be relevant) is also automatic, but deferred until the agent actually touches that subdirectory. You never have to remember a flag or paste a file.

All injected content is run through a security scanner before being placed in the prompt: prompt-injection patterns, credential exfiltration attempts, and invisible Unicode characters are blocked or rejected. Each loaded file is capped at roughly 20,000 characters; oversized files get truncated to a 70% head plus 20% tail format with a marker that tells the agent how much was cut and to use file-reading tools if the missing middle is needed.

A practical implication: every context file lives in your repo or your ~/.hermes/ directory. You do not pass them at launch. You write them once, drop them in the right place, and Hermes finds them.

Common Pitfalls

  1. Treating context files as a substitute for memory: They are static. They cannot learn that you switched from npm to pnpm halfway through the week. That belongs in MEMORY.md.
  2. Overloading AGENTS.md: A 19,000-character AGENTS.md will be loaded but will dominate every prompt. Keep it well under the 20K cap and let progressive subdirectory discovery handle nested detail.

Best Practices

  1. Match the file to the scope: Project-wide rules go in the root context file. Subsystem-specific rules go in nested frontend/AGENTS.md, backend/AGENTS.md, etc.
  2. Trust auto-discovery: If you find yourself reaching for a manual step to make Hermes "see" a file, you probably want to put that file at a path auto-discovery already covers.

Summary

  • Context injection is the system that puts project knowledge into the prompt; memory is the system that learns over time.
  • Two layers: auto-discovery at startup and progressive subdirectory discovery during the session.
  • All injected content is security-scanned and truncated if it exceeds the ~20,000-character cap.
  • You never pass context files at launch; you place them where auto-discovery looks.

Code Examples

text
Layer 1 (startup, automatic):
  AGENTS.md at repo root  →  loaded once into the system prompt.
  SOUL.md in HERMES_HOME  →  loaded independently for personality.
  MEMORY.md / USER.md     →  loaded from ~/.hermes/memories/.

Layer 2 (mid-session, automatic when navigated into):
  cd into frontend/       →  frontend/AGENTS.md auto-discovered on first access.
  cd into backend/        →  backend/AGENTS.md auto-discovered on first access.

There is no manual injection layer. Put the file where auto-discovery looks.
✓ Completed