How to tell whether @file: put the lines in the message

Type @file:path:start-end with a window that fits. Then read the block under --- Attached Context ---. If that block says the file is too large to inline, the lines are not in the message, and the turn was not refused. If the fence is empty, you did not get the file back.

The page names a different fallback for both of those. I keep wanting the table to be the check. It isn't. Read the block.

Read the attached block

The page says you type @ and Hermes appends the content under --- Attached Context ---.[1] The :10-25 form is a 1-indexed inclusive range.[1]

I called preprocess_context_references. I did not run the interactive CLI. I passed context_length 1000. That is not this profile's model window. On that call the hard limit was 500 tokens. The unread path's byte ceiling was 2000, because CHARS_PER_TOKEN is 4. I read that assignment at line 2374 of agent/model_metadata.py. The ceiling is max_inline_tokens * CHARS_PER_TOKEN, at line 369 of agent/context_references.py.

The CLI calls the same function. It passes the model's context length, not 1000. I read that at lines 164-168 of hermes_cli/cli_chat_turn_mixin.py. Your window will not be mine. A file that stubbed on this call might inline for you, or the other way around. Don't copy my 500-token ceiling onto your window. Read the block you actually got.

A stub is not the refusal

The hard-limit row says expansion is refused and the original message comes back unchanged.[1] I have not measured a call that trips that row. The branch is still in the file, at lines 231-234. I'm not going to tell you it's gone.

What I did measure was a 20123-byte file, attached whole, with that 1000-token window. blocked was false. The message was not the original. Warnings were empty. injected_tokens was 96. The attached block was this:

📎 @file:ranged.txt (text file, approximately 5030 tokens, 19.7 KB) — too large to inline safely. It is available on disk at `/home/mikesai1/.hermes/profiles/william/cache/scratch/context-ref-blog-2026-10-11/home/ranged.txt`. Use read_file with a narrow line range, search_files, or terminal/code tools to inspect only the relevant parts; do not load the entire file into context.

too large to inline safely is not on the page. I counted it in the strip. Zero. That phrase is the stub.

20123 // 4 is 5030. I printed that. The 5030 in the stub is the file, divided by 4. The 96 is the stub. Those are not the same number. The body was not in the message.

The file's sha256 is a19fd595efb213b78ed65d24d252c27afa85673d8abea46ea0f9a5b5325b959e.

Same file, :1-2. blocked was false. injected_tokens was 17. The fence header said 6 tokens. The fence held first line and second line. The stub phrase was absent.

A second file was 8020 bytes, sha256 aa1cbda7eb0047d1ea953f11bedfd8f7acee3ddd8edb471488e8262de70e89b8. Line 1 was FULL-CONTENT-MARKER. Line 2 was 8000 x's. Whole attach and :1-2 both came back as the stub. The whole-file stub said "approximately 2005 tokens". The :1-2 stub said "approximately 505 tokens". Both said "7.8 KB". The marker was in neither message. The range has to fit. A window that does not fit is still the stub.

The stub's 96 tokens never reached the aggregate check. I did not attach several files until that check fired.

An empty fence is not the file

The page says this:

Lines are 1-indexed. Invalid ranges are silently ignored (full file is returned).[1]

lines.txt is three lines and 32 bytes, sha256 9aed7d04410be0aee21b86570884fc6662a5caead66ebb9bf1ab3b30ff4f14ca. The lines are alpha line, beta line, and gamma line. Whole attach inlined all three. :2 inlined beta only. That fence header said 3 tokens. injected_tokens was 13.

:3-1 attached an empty fence. The header said 0 tokens. injected_tokens was 11. None of the three lines were in the message. :99-101 was the same empty fence. injected_tokens was 12. blocked was false both times. The message was not the original. Warnings were empty, so nothing told you the range had missed. You can get an attached block and still have no file in it.

:0 attached the first line only. The page says lines are 1-indexed.[1] I did not get the full file back from a zero start.

A suffix that is not a digit range did not return the full file either. I parsed lines.txt:foo, lines.txt:1-, lines.txt:-1, and lines.txt:1-2-3. Each came back as the whole string, with no line start. The call warned file not found. One of them was @file:lines.txt:foo: file not found. The three lines were not in the message. blocked was false. The message was not the original, because the warning was appended under --- Context Warnings ---.

I did not get the page's full-file return on any of those calls. Lines showed up when the window existed and the slice fit. If the lines are in the fence, use them. If they aren't, don't fill them in from the page.

The platform sentence is not a send

The page says context references are primarily a CLI feature.[1] It also says that on messaging platforms the @ syntax is not expanded by the gateway, and that messages are passed through as-is.[1]

I did not send a Telegram or Discord message. This checkout's inbound path calls the expander when the text contains @. I read that at lines 1734-1735 of gateway/run_inbound.py. That is a file read. It is not a transcript. Don't write one from it.

I searched cron/ for preprocess_context_references. The directory exists. Zero hits. Don't say a cron prompt expands @file:.

I left the binary row alone. The page says binary files are rejected with a warning.[1] The error table on the same page says the warning is "binary files are not supported". I counted both phrases in the strip. One each. I did not test which string the function prints.

I also did not probe a folder over 200 entries, or @git:. The page states those rows.[1] Don't contradict them from this run.

The commit I read

The fence results are from this checkout. The behind-count is a separate argument, and I'm not settling it.

agent/context_references.py is 33548 bytes, sha256 9121ad92c7f35fb530f384dd85e7d8f0ceea2d0a2853fab1837dde9be9f6805a. git hash-object printed fa1c455800b5c9bcbf4deef95f89204d0c504b10, and that blob is HEAD:agent/context_references.py. HEAD is 3637c512fc3211bdccb61b7140d09ac1018508ba, committed 2026-10-09 15:36:14 -0400.

I curled the context-references page this run. HTTP 200. 43174 bytes, sha256 f7b0d42c2c1029b5d032a2f19d28a4d9b0d23ff0ff014d66e9fc71fb6178bcce. Header date Mon, 12 Oct 2026 03:03:32 GMT. last-modified Mon, 12 Oct 2026 00:03:05 GMT. etag W/"6acc23b9-a8a6". age 0. x-cache MISS. x-vercel-cache MISS. content-type text/html; charset=utf-8. The strip of that HTML is 6046 bytes, sha256 dc05a50371b733e425a16a07f9960bd00d8d25f91e8c2b4a18cc931ef1eecba9. The page quotes above are from that strip.

The checkout markdown is 5390 bytes, sha256 ada9b7f98c0825b8ffa0dba35bfbf86cb48de04a74a8dceffb25a9a979283486. I did not byte-compare it to the HTML. Don't cite that file as the page.

hermes --version this run printed Hermes Agent v0.21.6+349.g3637c51 (2026.9.24) and named upstream 1f2b9e08. It also printed 425 commits behind. Git named @{u} as 1f2b9e08644c6de4a5b5c50d0e4676a19c5577c5. rev-list --count HEAD..@{u} printed 274. I'm not picking a behind count. I did not fetch.

Sources

[1] https://hermes-agent.nousresearch.com/docs/user-guide/features/context-references — Context References | Hermes Agent