context-files

Context Files System

Task Objectives

• This Skill is used to: master the Hermes Agent context file system
• Capabilities include: priority loading mechanism, AGENTS.md progressive discovery, SOUL.md special status, secure handling
• Trigger conditions: when project context needs to be configured or the file loading order needs to be understood

Core Concepts

The Context Files system automatically discovers and loads configuration files, shaping the Agent's behavior.

Supported File Types：

File	Purpose	Discovery Method	Priority
.hermes.md / HERMES.md	Project instructions (highest priority)	Walk to git root	⭐⭐⭐⭐⭐
AGENTS.md	Project instructions, architecture, conventions	CWD + subdirectory progressive	⭐⭐⭐⭐
CLAUDE.md	Claude Code context compatibility	CWD + subdirectory progressive	⭐⭐⭐
.cursorrules	Cursor IDE coding standards	CWD only	⭐⭐
.cursor/rules/*.md	Cursor rules modules	CWD only	⭐⭐
SOUL.md	Global personality customization	HERMES_HOME only	Always loaded (slot #1)

Priority Loading Mechanism

First Match Wins Algorithm

启动检测流程：
    │
    ▼
检查 .hermes.md ──→ 存在？→ 加载它，停止检测
    │               不存在 ↓
    ▼
检查 AGENTS.md ──→ 存在？→ 加载它，停止检测
    │               不存在 ↓
    ▼
检查 CLAUDE.md ──→ 存在？→ 加载它，停止检测
    │               不存在 ↓
    ▼
检查 .cursorrules → 存在？→ 加载它
    │
    ▼
（独立加载）SOUL.md → 始终从 HERMES_HOME 加载

Important Rules：

• Each session loads onlyoneproject context type (first match wins)
• SOUL.md is always loaded independentlyas the Agent identity (unaffected by the above priorities)
• Priorities cannot be customized; detection follows a fixed order

AGENTS.md Progressive Discovery

Working Mechanism

my-project/
├── AGENTS.md              ← 启动时加载（系统提示词）
├── frontend/
│   ├── src/
│   │   └── App.tsx       ← Agent 读取此文件时
│   └── AGENTS.md          ← 发现并注入 frontend/AGENTS.md
├── backend/
│   ├── main.py            ← Agent 读取此文件时
│   └── AGENTS.md          ← 发现并注入 backend/AGENTS.md
└── shared/
    └── utils.ts

Three Major Advantages

Advantage 1: Avoiding Prompt Bloat

传统方式（全部加载）：50,000 tokens overhead ❌
渐进式发现方式：只加载需要的部分 ✅

Advantage 2: Prefix Cache Preservation

Without: Large cache size, slower invalidation
With: Smaller caches, faster overall ✅

Advantage 3: Context Relevance

When working on frontend code → Only see frontend conventions
When working on backend code → Only see backend rules ✅

SOUL.md Special Status

Key Differences from Other Context Files

Dimension	SOUL.md	AGENTS.md / Others
Loading Source	HERMES_HOME only	Project working directory
Scope	Global (follows the instance)	Project level
System Position	Slot #1 (identity)	Project Context section
Discovery Method	Does not probe the working directory	Progressive directory discovery
Override Mechanism	Can be overridden by /personality	No override mechanism

SOUL.md Design Principles

• ✅ Should include: tone, communication style, directness, default interaction style
• ❌ Should not include: one-off project instructions, specific file paths, repository conventions

Secure Handling Mechanism

Multi-layer Security Pipeline

文件内容
    │
    ▼
[Layer 1: UTF-8 编码验证]
    │
    ▼
[Layer 2: Prompt Injection 扫描]
    │
    ├── 检测到恶意内容 → 阻止加载
    └── 安全通过 ↓
            ▼
        [Layer 3: 长度检查]
            │
            ├── ≤ 20,000 chars → 完整加载
            └── > 20,000 chars → 头尾截断 (70%头 + 20%尾)

Truncation Algorithm

Automatically truncates when a file exceeds 20,000 characters:

Original (25,000 chars):
# Project Guide (完整文档)

After truncation (20,000 chars max):
┌────────────────────────────┐
│ 前 14,000 chars (70%)     │  ← 主要内容
├────────────────────────────┤
│ [CONTENT TRUNCATED]       │  ← 截断标记
│ Original: 25,000 chars    │
└────────────────────────────┘
└── 后 4,000 chars (20%)     │  ← 结尾内容

Usage Examples

Example 1: Creating a Standard AGENTS.md

# Project Context

This is a Next.js 14 web application with Python FastAPI backend.

## Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on Hetzner VPS

## Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` (frontend) or `tests/` (backend)

## Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB port is 5432

Example 2: Creating a Personalized SOUL.md

# Personality

You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Repeating the user's framing if it's wrong
- Overexplaining obvious things

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup

Example 3: Multi-level Project Structure

company-monorepo/
├── AGENTS.md                    # 公司级规范（启动时加载）
├── packages/
│   ├── web-app/
│   │   ├── AGENTS.md            # Web 应用特定规范（访问时发现）
│   │   └── src/
│   └── api-service/
│       ├── AGENTS.md            # API 服务特定规范（访问时发现）
│       └── src/

Advanced Tips

Tip 1: Leverage .cursorrules Compatibility

If you are already using the Cursor IDE, you can directly reuse the configuration:

# 现有 .cursorrules 文件会被 Hermes 自动识别
# （前提是没有更高优先级的 .hermes.md 或 AGENTS.md）

Tip 2: Dynamic Context Switching

Use symbolic links to quickly switch project configurations:

# 创建多个配置变体
cat > AGENTS.dev.md << 'EOF'
# Development Mode
- Enable verbose logging
- Use hot reload
- Run linting in watch mode
EOF

cat > AGENTS.prod.md << 'EOF'
# Production Mode
- Optimize for performance
- Minimize bundle size
- Strict type checking
EOF

# 快速切换
ln -sf AGENTS.dev.md AGENTS.md   # 切换到开发模式
ln -sf AGENTS.prod.md AGENTS.md  # 切换到生产模式

Tip 3: Token Budget Allocation

Recommended system prompt budget(assuming a 128K context window):

总预算: ~128,000 tokens
│
├── SOUL.md: ~2,000 tokens (1.5%)        ← 身份定义
├── Project Context: ~5,000 tokens (4%)   ← 项目指令
├── Dynamic Context: ~10,000 tokens (8%)  ← 渐进式发现
├── Memory: ~1,300 tokens (1%)           ← 持久化记忆
├── Conversation History: ~80,000 tokens (62.5%)
├── Tool Results: ~20,000 tokens (15.6%)
└── System Overhead: ~9,700 tokens (7.6%)

Troubleshooting

Issue 1: Context File Not Loaded

Diagnostic Steps：

# 1. 检查文件是否存在
ls -la AGENTS.md .hermes.md CLAUDE.md .cursorrules

# 2. 检查文件名是否正确（区分大小写）
#    AGENTS.md ≠ Agents.md ≠ agents.md

# 3. 检查是否有更高优先级文件覆盖了它
ls -la .hermes.md  # 如果存在，会覆盖 AGENTS.md

Issue 2: Subdirectory AGENTS.md Not Discovered

Solution：

1. Ensure the Agent reads the files in the subdirectory first
2. Manually prompt the Agent to check that directory
3. If you frequently need to work in a certain subdirectory, consider promoting that directory's content to the root AGENTS.md

Issue 3: SOUL.md Changes Not Taking Effect

Cause: Same frozen snapshot mechanism as Memory

Solution：

# 1. 确认编辑了正确的文件
#    应该是 ~/.hermes/SOUL.md
#    不是项目目录下的 SOUL.md（不会被加载）

# 2. 重启 Hermes 会话
#    SOUL.md 只在会话开始时加载

Resource Index

• Official Documentation：https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files
• Parent Skill：SKILL.md - Complete skill system overview
• Related Sub-skill：agents-workflow - AGENTS.md workbook in practice
• Related Sub-skill：personality-config - SOUL.md configuration details

Notes

• Priority cannot be customized; detection follows a fixed order
• SOUL.md is only loaded from HERMES_HOME, not placed in the working directory
• Oversized files (>20,000 chars) will be automatically truncated
• All files undergo prompt injection scanning
• Version-control AGENTS.md to bring project context under Git management