Context References — Precise Citations

Welcome back to our Hermes Agent series! Today we’re diving into something that makes your agent dramatically more useful: context references. If you’ve ever wished your agent could point to exactly where it got information—like a proper research paper with citations—this is the feature for you.

What Are Context References?

Think of context references like footnotes in a book. When your agent processes a document, a conversation, or a file, it can now remember where specific pieces of information came from. Instead of just saying “the sky is blue,” it can say “the sky is blue (from weather_report.md, line 42).”

This is a game-changer for:

• Research tasks — verify sources instantly
• Code reviews — trace where a bug was introduced
• Legal or compliance work — prove where a fact came from
• Long conversations — remember which message contained a key detail

How It Works

The magic happens behind the scenes. When you feed your agent documents, chat history, or files, Hermes automatically tracks the origin of each piece of content. You don’t need to do anything special—it just works.

Here’s a simple example:

hermes chat --with file:contract.pdf

Ask a question like “What’s the termination clause?” and the agent will respond with a citation pointing to the exact section of the PDF.

The New Configuration Options

The latest update brings some powerful new ways to control how context references behave. All of these live in your ~/.hermes/config.yaml file.

Enabling and Disabling

By default, context references are on for file-based content. But you can control them per-session:

context_references:
  enabled: true              # master switch
  include_line_numbers: true # add line numbers to citations
  max_citations: 5           # cap how many references per response

Citation Formats

You can choose how citations appear in responses:

context_references:
  format: markdown  # options: markdown, plain, json

• markdown — [source: file.md, line 12] (renders nicely in chat UIs)
• plain — (file.md:12) (compact, good for terminals)
• json — structured output for programmatic use

Working with Sessions

Context references shine in long-running sessions. The agent remembers which message introduced a fact, even hours later:

hermes chat --session research-project

Ask “What did we learn about pricing earlier?” and get a citation pointing to the exact message from two hours ago.

Practical Tips

1. Use Descriptive Filenames

The citation includes the filename, so make them meaningful:

hermes chat --with docs/Q3-financial-report.md

Better than file1.txt, right?

2. Combine with Memory

Context references work beautifully with Hermes’ memory system. When the agent stores something in memories/, it also records the source. Later, when it recalls that memory, it can tell you where the information originally came from.

3. Check Your Configuration

After updating Hermes, run:

hermes config check
hermes config migrate

This ensures you have all the latest options available.

A Quick Example

Let’s see it in action:

hermes chat --with ~/notes/meeting-notes.md

You: “What action items did we agree on?”

Agent: “Based on the meeting notes, you agreed to:

1. Finalize the Q3 budget (from meeting-notes.md, line 15)
2. Schedule the client demo (from meeting-notes.md, line 22)
3. Update the project timeline (from meeting-notes.md, line 28)“

See how each item has its own citation? That’s context references doing their job.

Configuration Precedence Reminder

Remember, settings are resolved in this order:

1. CLI arguments — highest priority
2. config.yaml — your main config file
3. .env — for secrets only
4. Built-in defaults — fallback

So you can override context reference settings per-command:

hermes chat --with file:report.pdf --set context_references.format=plain

Wrapping Up

Context references turn your agent from a “black box” into a transparent, verifiable assistant. Whether you’re doing research, debugging code, or just want to trust your agent’s answers more, this feature gives you the receipts.

Try it out with your own documents and see how much more confident you feel when every answer comes with a source. Your future self—trying to remember where that fact came from—will thank you.

Happy citing! 🎯