Tệp ngữ cảnh

Hermes Agent tự động phát hiện và tải các tệp ngữ cảnh định hình cách hoạt động của nó. Một số là dự án cục bộ và được phát hiện từ thư mục làm việc của bạn. SOUL.md hiện có tính toàn cầu đối với phiên bản Hermes và chỉ được tải từ HERMES_HOME.

Tệp ngữ cảnh được hỗ trợ

Tập tin	Mục đích	Khám phá
.hermes.md / HERMES.md	Hướng dẫn dự án (ưu tiên cao nhất)	Đi tới git root
ĐẠI LÝ.md	Hướng dẫn dự án, quy ước, kiến ​​trúc	CWD khi khởi động + thư mục con dần dần
CLAUDE.md	Tệp ngữ cảnh Mã Claude (cũng được phát hiện)	CWD khi khởi động + thư mục con dần dần
SOUL.md	Tùy chỉnh tông màu và cá tính toàn cầu cho phiên bản Hermes này	Chỉ HERMES_HOME/SOUL.md
.cursorrules	Quy ước mã hóa IDE con trỏ	Chỉ CWD
.cursor/rules/*.mdc	Mô-đun quy tắc IDE con trỏ	Chỉ CWD

Priority system

Chỉ một loại ngữ cảnh dự án được tải mỗi phiên (trận đấu đầu tiên thắng): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md luôn được tải độc lập dưới dạng danh tính tác nhân (khe số 1).

ĐẠI LÝ.md

AGENTS.md là tệp ngữ cảnh chính của dự án. Nó cho đại lý biết dự án của bạn được cấu trúc như thế nào, những quy ước nào cần tuân theo và bất kỳ hướng dẫn đặc biệt nào.

Khám phá thư mục con lũy tiến

Khi bắt đầu phiên, Hermes tải AGENTS.md từ thư mục làm việc của bạn vào dấu nhắc hệ thống. Khi tác nhân điều hướng đến các thư mục con trong phiên (thông qua read_file, terminal, search_files, v.v.), nó phát hiện dần dần các tệp ngữ cảnh trong các thư mục đó và đưa chúng vào cuộc trò chuyện tại thời điểm chúng trở nên phù hợp.

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

Cách tiếp cận này có hai ưu điểm so với việc tải mọi thứ khi khởi động:

• Không có dấu nhắc hệ thống — gợi ý thư mục con chỉ xuất hiện khi cần
• Bảo quản bộ nhớ đệm nhanh — lời nhắc hệ thống luôn ổn định qua các lượt

Mỗi thư mục con được kiểm tra nhiều nhất một lần mỗi phiên. Việc khám phá cũng đi lên các thư mục mẹ, vì vậy việc đọc backend/src/main.py sẽ khám phá backend/AGENTS.md ngay cả khi backend/src/ không có tệp ngữ cảnh riêng.

thông tin

Các tệp ngữ cảnh thư mục con trải qua cùng một quét bảo mật như các tệp ngữ cảnh khởi động. Các tập tin độc hại bị chặn.

Ví dụ ĐẠI LÝ.md

# Project Context

This is a Next.js 14 web application with a 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 a 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__/` directories (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 is 5432

SOUL.md

SOUL.md controls the agent's personality, tone, and communication style. See the Personality page for full details.

Location:

• ~/.hermes/SOUL.md
• or $HERMES_HOME/SOUL.md if you run Hermes with a custom home directory

Important details:

• Hermes seeds a default SOUL.md automatically if one does not exist yet
• Hermes loads SOUL.md only from HERMES_HOME
• Hermes does not probe the working directory for SOUL.md
• If the file is empty, nothing from SOUL.md is added to the prompt
• If the file has content, the content is injected verbatim after scanning and truncation

.cursorrules

Hermes is compatible with Cursor IDE's .cursorrules file and .cursor/rules/*.mdc rule modules. If these files exist in your project root and no higher-priority context file (.hermes.md, AGENTS.md, or CLAUDE.md) is found, they're loaded as the project context.

This means your existing Cursor conventions automatically apply when using Hermes.

How Context Files Are Loaded

At startup (system prompt)

Context files are loaded by build_context_files_prompt() in agent/prompt_builder.py:

1. Scan working directory — checks for .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules (first match wins)
2. Content is read — each file is read as UTF-8 text
3. Security scan — content is checked for prompt injection patterns
4. Truncation — files exceeding 20,000 characters are head/tail truncated (70% head, 20% tail, with a marker in the middle)
5. Assembly — all sections are combined under a # Project Context header
6. Injection — the assembled content is added to the system prompt

During the session (progressive discovery)

SubdirectoryHintTracker in agent/subdirectory_hints.py watches tool call arguments for file paths:

1. Path extraction — after each tool call, file paths are extracted from arguments (path, workdir, shell commands)
2. Ancestor walk — the directory and up to 5 parent directories are checked (stopping at already-visited directories)
3. Hint loading — if an AGENTS.md, CLAUDE.md, or .cursorrules is found, it's loaded (first match per directory)
4. Security scan — same prompt injection scan as startup files
5. Truncation — capped at 8,000 characters per file
6. Injection — appended to the tool result, so the model sees it in context naturally

The final prompt section looks roughly like:

# Project Context

The following project context files have been loaded and should be followed:

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

Notice that SOUL content is inserted directly, without extra wrapper text.

Security: Prompt Injection Protection

All context files are scanned for potential prompt injection before being included. The scanner checks for:

• Instruction override attempts: "ignore previous instructions", "disregard your rules"
• Deception patterns: "do not tell the user"
• System prompt overrides: "system prompt override"
• Hidden HTML comments: <!-- ignore instructions -->
• Hidden div elements: <div style="display:none">
• Credential exfiltration: curl ... $API_KEY
• Secret file access: cat .env, cat credentials
• Invisible characters: zero-width spaces, bidirectional overrides, word joiners

If any threat pattern is detected, the file is blocked:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

cảnh báo

This scanner protects against common injection patterns, but it's not a substitute for reviewing context files in shared repositories. Always validate AGENTS.md content in projects you didn't author.

Size Limits

Limit	Value
Max chars per file	20,000 (~7,000 tokens)
Head truncation ratio	70%
Tail truncation ratio	20%
Truncation marker	10% (shows char counts and suggests using file tools)

When a file exceeds 20,000 characters, the truncation message reads:

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

Tips for Effective Context Files

Best practices for AGENTS.md

1. Keep it concise — stay well under 20K chars; the agent reads it every turn
2. Structure with headers — use ## sections for architecture, conventions, important notes
3. Include concrete examples — show preferred code patterns, API shapes, naming conventions
4. Mention what NOT to do — "never modify migration files directly"
5. List key paths and ports — the agent uses these for terminal commands
6. Update as the project evolves — stale context is worse than no context

Per-Subdirectory Context

For monorepos, put subdirectory-specific instructions in nested AGENTS.md files:

<!-- frontend/AGENTS.md -->
# Frontend Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`

<!-- backend/AGENTS.md -->
# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`