Overview

Modern AI coding agents (Cursor, Aider, Claude Code, Windsurf) all share a critical UX pattern that Hermes Agent currently lacks: project-level context awareness. This manifests in two complementary features: (1) @ references that let users scope what the agent sees (@file, @folder, @codebase), and (2) project config files (.hermes.md or HERMES.md) that define per-project rules, conventions, and context — similar to CLAUDE.md, .cursorrules, or .windsurfrules.

Together, these transform the agent from "a general assistant that happens to have terminal access" into "an assistant that deeply understands this specific project." This was the #1 most-requested UX pattern across the 30+ agent interfaces studied in this research sweep.

---

Research Findings

@ Reference Systems in Existing Agents

Cursor IDE — The most mature implementation:

• @codebase — Semantic search across the entire repo using vector embeddings
• @folder — Scope to a specific directory
• @file — Include specific file(s) as context
• @web — Search the web and include results
• @docs — Reference indexed documentation
• @git — Reference git history/diffs
• Fuzzy matching with .gitignore respect
• Auto-complete dropdown as you type @

Aider — CLI-native approach:

• /add <file> — Add files to the "chat" (editable context)
• /read <file> — Add as read-only context
• /drop <file> — Remove from context
• Repository map via tree-sitter (automatic architectural understanding)
• .aiderignore file for excluding paths

Toad CLI — @ with fuzzy file search, respects .gitignore

Windsurf — @-mention conversations to reference previous chats, plus file/folder scoping

Project Config Files

Claude Code (CLAUDE.md) — The gold standard:

• CLAUDE.md at repo root acts as a "constitution" for the agent
• Can contain: code style rules, testing conventions, deployment procedures, file organization docs
• Nested CLAUDE.md files in subdirectories for scoped rules
• Automatically loaded when agent opens a project
• Can reference other files

Cursor (.cursorrules) — Similar concept:

• JSON or markdown file with project-specific instructions
• Prepended to system prompt
• Community-maintained collections of rules for different frameworks

Key insight: Project config files are essentially "persistent context that lives with the code." They eliminate the need to re-explain project conventions every session.

---

Current State in Hermes Agent

@ References: Not implemented. Users must manually copy-paste file contents, describe file paths in natural language, or hope the agent searches correctly. There is no structured way to say "look at these specific files."

Project Config: Not implemented. Hermes uses global ~/.hermes/config.yaml for agent configuration and MEMORY.md/USER.md for persistent context, but nothing project-scoped. When the agent works in different repos, it has no project-specific rules.

What we DO have that's relevant:

• read_file tool — Agent can read files, but user must describe what to read
• search_files tool — Agent can search, but lacks architectural overview
• Skills with reference files — Per-skill context, but not per-project
• Memory system — Global, not project-scoped
• System prompt injection — Could be extended to include project config

---

Implementation Plan

Skill vs. Tool Classification

This should be a core codebase change, not a skill. It requires:

• Message pre-processing to parse @ references before the LLM sees them (deterministic)
• File system scanning and config loading at session start
• System prompt modification to inject project context
• Auto-complete/suggestion support in CLI

What We'd Need

1. Message parser for @ references (runs before message is sent to LLM)
2. Config file loader that discovers and reads .hermes.md / HERMES.md
3. System prompt builder changes to inject project context
4. CLI auto-complete for @ references (prompt_toolkit completer)
5. Gateway message pre-processor for @ references in messaging platforms

Phased Rollout

Phase 1: .hermes.md Project Config

• On session start, scan CWD (and parents up to git root) for .hermes.md or HERMES.md
• Load contents and inject into system prompt as "Project Context"
• Support nested configs: subdirectory .hermes.md overrides/extends parent
• Document the feature and create example configs for common frameworks
• Add a /project slash command to view/reload the active project config
• Respect .hermesignore for files/dirs the agent should never touch

Phase 2: @ Reference System

• Parse @file:path/to/file — read file contents and prepend to message
• Parse @folder:path/to/dir — list directory tree and prepend
• Parse @diff — include current git diff as context
• Parse @git:N — include last N git log entries
• Parse @url:https://... — fetch and include web content
• CLI: tab-completion for file paths after @file: (using prompt_toolkit)
• Gateway: parse @ references from plain text messages
• Show injected context size (token estimate) so users know the cost
• Support .hermesignore patterns in @ folder expansion

Phase 3: Smart Context & Repository Map

• @codebase — Generate a tree-sitter-based repository map (like Aider)
• Auto-detect project type and suggest relevant @ references
• Context budget management: warn when @ references exceed a threshold
• Persistent @ reference sets: "always include these files in this project"
• Integration with project config: .hermes.md can declare default context files

---

Pros & Cons

Pros

• Dramatically reduces friction for code-focused work (the Terminal tool #1 use case)
• Project config eliminates repetitive re-explanation of conventions
• @ references give users precise control over what the agent sees
• Follows established patterns — users coming from Cursor/Claude Code will feel at home
• .hermes.md lives in the repo, so it's shared across team members
• Relatively low implementation complexity for high UX impact

Cons / Risks

• @ parsing in messages must be careful not to match email addresses or social media handles
• Project config could contain sensitive info (API keys, secrets) — need to warn/redact
• Repository map generation (Phase 3) requires tree-sitter, adding a dependency
• Token budget: loading too much context from @ references can crowd out conversation
• Cross-platform: @ references in Telegram/Discord may feel awkward vs CLI

---

Open Questions

• Should @ references use @file:path syntax (explicit) or just @path (shorter but ambiguous)?
• Should .hermes.md support YAML frontmatter for structured config (model, tools, personality) plus markdown body for prose instructions?
• Should project config be opt-in (only loaded if file exists) or should the agent auto-generate a starter .hermes.md when it detects a project?
• How do we handle @ references on messaging platforms where there's no file system context? (Would need the agent to resolve paths relative to CWD)
• Should the repository map (Phase 3) be generated on-demand or cached?

---

References

• Cursor @ mentions — @codebase, @folder, @file, @web scoping
• CLAUDE.md spec — Project-level agent configuration
• .cursorrules — Community-maintained project rule collections
• Aider /add system — CLI-native context management
• Toad CLI — @ fuzzy file search in terminal agents
• Windsurf rules — Project-scoped agent behavior rules
• Related Hermes issues: Feature: PAHF Personalization Loop — Pre-Action Clarification, Preference Grounding & Post-Action Feedback Integration #362 (PAHF Personalization), Feature: Structured Memory System — Typed Nodes, Graph Edges, and Hybrid Search #346 (Structured Memory)