43d468cea8
Major changes across 20 documentation pages: Staleness fixes: - Fix FAQ: wrong import path (hermes.agent → run_agent) - Fix FAQ: stale Gemini 2.0 model → Gemini 3 Flash - Fix integrations/index: missing MiniMax TTS provider - Fix integrations/index: web_crawl is not a registered tool - Fix sessions: add all 19 session sources (was only 5) - Fix cron: add all 18 delivery targets (was only telegram/discord) - Fix webhooks: add all delivery targets - Fix overview: add missing MCP, memory providers, credential pools - Fix all line-number references → use function name searches instead - Update file size estimates (run_agent ~9200, gateway ~7200, cli ~8500) Expanded thin pages (< 150 lines → substantial depth): - honcho.md: 43 → 108 lines — added feature comparison, tools, config, CLI - overview.md: 49 → 55 lines — added MCP, memory providers, credential pools - toolsets-reference.md: 57 → 175 lines — added explanations, config examples, custom toolsets, wildcards, platform differences table - optional-skills-catalog.md: 74 → 153 lines — added 25+ missing skills across communication, devops, mlops (18!), productivity, research categories - integrations/index.md: 82 → 115 lines — added messaging, HA, plugins sections - cron-internals.md: 90 → 195 lines — added job JSON example, lifecycle states, tick cycle, delivery targets, script-backed jobs, CLI interface - gateway-internals.md: 111 → 250 lines — added architecture diagram, message flow, two-level guard, platform adapters, token locks, process management - agent-loop.md: 112 → 235 lines — added entry points, API mode resolution, turn lifecycle detail, message alternation rules, tool execution flow, callback table, budget tracking, compression details - architecture.md: 152 → 295 lines — added system overview diagram, data flow diagrams, design principles table, dependency chain Other depth additions: - context-references.md: added platform availability, compression interaction, common patterns sections - slash-commands.md: added quick commands config example, alias resolution - image-generation.md: added platform delivery table - tools-reference.md: added tool counts, MCP tools note - index.md: updated platform count (5 → 14+), tool count (40+ → 47)
143 lines
5.3 KiB
Markdown
143 lines
5.3 KiB
Markdown
---
|
|
sidebar_position: 9
|
|
sidebar_label: "Context References"
|
|
title: "Context References"
|
|
description: "Inline @-syntax for attaching files, folders, git diffs, and URLs directly into your messages"
|
|
---
|
|
|
|
# Context References
|
|
|
|
Type `@` followed by a reference to inject content directly into your message. Hermes expands the reference inline and appends the content under an `--- Attached Context ---` section.
|
|
|
|
## Supported References
|
|
|
|
| Syntax | Description |
|
|
|--------|-------------|
|
|
| `@file:path/to/file.py` | Inject file contents |
|
|
| `@file:path/to/file.py:10-25` | Inject specific line range (1-indexed, inclusive) |
|
|
| `@folder:path/to/dir` | Inject directory tree listing with file metadata |
|
|
| `@diff` | Inject `git diff` (unstaged working tree changes) |
|
|
| `@staged` | Inject `git diff --staged` (staged changes) |
|
|
| `@git:5` | Inject last N commits with patches (max 10) |
|
|
| `@url:https://example.com` | Fetch and inject web page content |
|
|
|
|
## Usage Examples
|
|
|
|
```text
|
|
Review @file:src/main.py and suggest improvements
|
|
|
|
What changed? @diff
|
|
|
|
Compare @file:old_config.yaml and @file:new_config.yaml
|
|
|
|
What's in @folder:src/components?
|
|
|
|
Summarize this article @url:https://arxiv.org/abs/2301.00001
|
|
```
|
|
|
|
Multiple references work in a single message:
|
|
|
|
```text
|
|
Check @file:main.py, and also @file:test.py.
|
|
```
|
|
|
|
Trailing punctuation (`,`, `.`, `;`, `!`, `?`) is automatically stripped from reference values.
|
|
|
|
## CLI Tab Completion
|
|
|
|
In the interactive CLI, typing `@` triggers autocomplete:
|
|
|
|
- `@` shows all reference types (`@diff`, `@staged`, `@file:`, `@folder:`, `@git:`, `@url:`)
|
|
- `@file:` and `@folder:` trigger filesystem path completion with file size metadata
|
|
- Bare `@` followed by partial text shows matching files and folders from the current directory
|
|
|
|
## Line Ranges
|
|
|
|
The `@file:` reference supports line ranges for precise content injection:
|
|
|
|
```text
|
|
@file:src/main.py:42 # Single line 42
|
|
@file:src/main.py:10-25 # Lines 10 through 25 (inclusive)
|
|
```
|
|
|
|
Lines are 1-indexed. Invalid ranges are silently ignored (full file is returned).
|
|
|
|
## Size Limits
|
|
|
|
Context references are bounded to prevent overwhelming the model's context window:
|
|
|
|
| Threshold | Value | Behavior |
|
|
|-----------|-------|----------|
|
|
| Soft limit | 25% of context length | Warning appended, expansion proceeds |
|
|
| Hard limit | 50% of context length | Expansion refused, original message returned unchanged |
|
|
| Folder entries | 200 files max | Excess entries replaced with `- ...` |
|
|
| Git commits | 10 max | `@git:N` clamped to range [1, 10] |
|
|
|
|
## Security
|
|
|
|
### Sensitive Path Blocking
|
|
|
|
These paths are always blocked from `@file:` references to prevent credential exposure:
|
|
|
|
- SSH keys and config: `~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, `~/.ssh/authorized_keys`, `~/.ssh/config`
|
|
- Shell profiles: `~/.bashrc`, `~/.zshrc`, `~/.profile`, `~/.bash_profile`, `~/.zprofile`
|
|
- Credential files: `~/.netrc`, `~/.pgpass`, `~/.npmrc`, `~/.pypirc`
|
|
- Hermes env: `$HERMES_HOME/.env`
|
|
|
|
These directories are fully blocked (any file inside):
|
|
- `~/.ssh/`, `~/.aws/`, `~/.gnupg/`, `~/.kube/`, `$HERMES_HOME/skills/.hub/`
|
|
|
|
### Path Traversal Protection
|
|
|
|
All paths are resolved relative to the working directory. References that resolve outside the allowed workspace root are rejected.
|
|
|
|
### Binary File Detection
|
|
|
|
Binary files are detected via MIME type and null-byte scanning. Known text extensions (`.py`, `.md`, `.json`, `.yaml`, `.toml`, `.js`, `.ts`, etc.) bypass MIME-based detection. Binary files are rejected with a warning.
|
|
|
|
## Platform Availability
|
|
|
|
Context references are primarily a **CLI feature**. They work in the interactive CLI where `@` triggers tab completion and references are expanded before the message is sent to the agent.
|
|
|
|
In **messaging platforms** (Telegram, Discord, etc.), the `@` syntax is not expanded by the gateway — messages are passed through as-is. The agent itself can still reference files via the `read_file`, `search_files`, and `web_extract` tools.
|
|
|
|
## Interaction with Context Compression
|
|
|
|
When conversation context is compressed, the expanded reference content is included in the compression summary. This means:
|
|
|
|
- Large file contents injected via `@file:` contribute to context usage
|
|
- If the conversation is later compressed, the file content is summarized (not preserved verbatim)
|
|
- For very large files, consider using line ranges (`@file:main.py:100-200`) to inject only relevant sections
|
|
|
|
## Common Patterns
|
|
|
|
```text
|
|
# Code review workflow
|
|
Review @diff and check for security issues
|
|
|
|
# Debug with context
|
|
This test is failing. Here's the test @file:tests/test_auth.py
|
|
and the implementation @file:src/auth.py:50-80
|
|
|
|
# Project exploration
|
|
What does this project do? @folder:src @file:README.md
|
|
|
|
# Research
|
|
Compare the approaches in @url:https://arxiv.org/abs/2301.00001
|
|
and @url:https://arxiv.org/abs/2301.00002
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Invalid references produce inline warnings rather than failures:
|
|
|
|
| Condition | Behavior |
|
|
|-----------|----------|
|
|
| File not found | Warning: "file not found" |
|
|
| Binary file | Warning: "binary files are not supported" |
|
|
| Folder not found | Warning: "folder not found" |
|
|
| Git command fails | Warning with git stderr |
|
|
| URL returns no content | Warning: "no content extracted" |
|
|
| Sensitive path | Warning: "path is a sensitive credential file" |
|
|
| Path outside workspace | Warning: "path is outside the allowed workspace" |
|