How I Made My AI Agent Read Its Own Manual

Hermes Agent has thorough documentation — but it's written for humans. What happens when you point the agent at its own docs and ask it to tell you what you're doing wrong? Here's what I learned, and what I changed.

2026-04-27 · 8 min read

Here's a sentence that sounds obvious once you hear it: your AI agent has documentation, and it can read it.

Most people — me included — set up their agent, fumble through configuration by trial and error, and never go back to the docs. I treated the documentation like a fridge manual: useful on day one, ignored forever after. But Hermes Agent isn't a fridge. It's a system that evolves. And the docs evolve too.

So I did something that felt almost too simple to work: I pointed my agent at the official Hermes documentation and asked it to tell me what I was doing wrong. What came back was a list of improvements that would have taken me weeks to discover on my own.

This post covers two things: what the docs taught me, and — more importantly — the method itself. Because pointing your agent at its own documentation and saying "tell me what to change" is a workflow that works for any agent, any tool, any system.

The Method (Do This First)

Before I get to the specific improvements, here's the pattern. It's three steps:

1. Feed the docs to your agent.

In Hermes, you can do this with web_extract:

"Extract content from https://hermes-agent.nousresearch.com/docs/"

Or use the browser tool to navigate and read pages. The agent has both. Point it at the key pages — quickstart, configuration, memory, skills, tips — and let it ingest.

2. Ask a specific question.

Not "what should I do?" — that's too vague. Ask something grounded:

• "Compare my current config.yaml against the docs recommendations. What am I missing?"
• "What features in the tips page am I not using?"
• "What does the docs say about memory hygiene that I'm violating?"

3. Act on what it tells you.

The agent will come back with a list. Some items are quick fixes (add a config line, create a file). Some are architecture changes (set up a different terminal backend, restructure memory). Do the quick ones immediately. Flag the big ones for a deliberate session.

That's it. That's the whole workflow. It works because the agent can cross-reference its actual configuration against the documented best practices faster than any human could.

What I Found: The Big Gaps

I fed Dade eight pages of Hermes documentation — quickstart, configuration, memory, skills, personality, context files, security, and tips. Here's what came back.

Gap 1: No AGENTS.md Files Anywhere

This was the biggest miss. The Context Files documentation describes a feature I wasn't using at all: AGENTS.md files as project-aware context.

Here's how it works: you put an AGENTS.md file in your project root. Hermes discovers it automatically at session start and injects it into the system prompt. If you have subdirectories with their own AGENTS.md files, Hermes progressively discovers those too — when it navigates into those directories.

This means every project can carry its own instructions, conventions, and architecture notes. And the agent doesn't have to be told — it just knows.

I had zero AGENTS.md files. Not in my blog project, not in my web stack, not anywhere. I was re-explaining project conventions in every single session.

Fix: Create AGENTS.md in every project root with architecture, conventions, and gotchas.

Gap 2: Only One Toolset Configured

My config had toolsets: [hermes-cli] and nothing else. The docs describe platform-specific toolset presets — hermes-telegram, hermes-discord — that optimise which tools are loaded for each platform. Loading every tool on every platform wastes context window tokens.

When I'm on Telegram, I don't need the browser toolset as often. When I'm in CLI, I don't need the messaging delivery tools. The docs explain how to configure this per-platform.

Fix: Set up platform-specific toolsets to reduce per-turn token overhead.

Gap 3: Manual Approval Mode When Smart Mode Exists

I was running approvals.mode: manual — every potentially dangerous command asks for approval. The docs describe three modes: manual, smart, and off. Smart mode uses an auxiliary LLM to assess risk. Low-risk commands like python -c "print('hello')" auto-approve. Genuinely dangerous commands like rm -rf / auto-deny. Uncertain cases escalate.

Smart mode would save me from the approval fatigue that makes me reflexively click "yes" without reading — which is arguably less safe than smart auto-approval.

Fix: Switch to approvals.mode: smart for daily use, keep manual for sensitive operations.

Gap 4: Memory at 99% With No Consolidation Strategy

My memory store was at 2,184 out of 2,200 characters — 99% full. The memory documentation is explicit about what to save vs skip:

• Save: user preferences, environment facts, discovered conventions, project structure, corrections
• Skip: task progress, session outcomes, temporary state, raw data dumps

I had entries that were borderline — long entries about specific project states that could be compressed into pointers. The docs' advice: consolidate related entries, promote stable knowledge to spoke files or external context, and keep memory lean for what actually changes between sessions.

Fix: Compress memory entries, move stable facts to AGENTS.md or vault files, keep only active/evolving knowledge in the 2,200-char store.

Gap 5: Not Using Session Resume

The tips page mentions hermes -c to resume the last session and hermes -r "title" to resume by title. I'd been starting fresh sessions and re-explaining context every time. The resume feature carries the full conversation history forward.

Fix: Use hermes -c when continuing ongoing work instead of starting fresh.

Gap 6: No Checkpoints or Rollback

The docs describe a Checkpoints & Rollback feature I didn't even know existed. It takes snapshots of your Hermes home directory at key moments, letting you roll back if a configuration change or memory edit breaks something. Given how often I tweak config and memory, this is a safety net I should have had from day one.

Fix: Enable checkpoints and test rollback.

The Beginner's Guide (What the Docs Cover Well)

While I was at it, I also read the docs from a beginner's perspective. Here's the reading order I'd recommend for someone starting fresh with Hermes:

Start Here

1. Installation — One-line curl installer. Works on Linux, macOS, WSL2, even Android Termux. Reload your shell. Done.

2. Quickstart — The fastest path section is genuinely good. It has a decision table: "I just want it working" → hermes setup, "I want a bot" → hermes gateway setup after CLI works, "I want local models" → hermes model with custom endpoint. The rule of thumb is sound: if Hermes cannot complete a normal chat, do not add more features yet.

3. Configuration — This page is 87,000 characters of detail. The key takeaways: secrets go in .env, everything else goes in config.yaml, and hermes config set auto-routes to the right file. The env variable substitution syntax (${VAR_NAME}) is useful for not pasting API keys directly into config.

Features That Matter

4. Memory — 2,200 chars for agent notes, 1,375 for user profile. Frozen snapshot at session start — changes persist to disk immediately but appear in-system next session. This is the architectural constraint that drove my entire hub-and-spoke design.

5. Skills — Progressive disclosure pattern: skills_list() shows names+descriptions (~3K tokens), skill_view() loads full content only when needed. Skills are slash commands. The agent can create them from experience. This is the self-improving loop.

6. Context Files — AGENTS.md with progressive subdirectory discovery. This is the feature I should have been using from day one. Project-specific conventions loaded automatically.

7. Personality & SOUL.md — SOUL.md is slot #1 in the system prompt. It's the identity. AGENTS.md is the project context. Don't mix them — SOUL.md for who the agent is, AGENTS.md for what the project needs.

8. Security — Seven layers of defence. The approval modes are worth understanding. Smart mode is underrated. The dangerous command patterns list is extensive and educational — reading it teaches you what commands can actually destroy things.

The Nice-to-Haves

9. Voice Mode — Works with zero API keys if you install faster-whisper locally. Press Ctrl+B in CLI, speak, agent responds. On Telegram and Discord, it sends audio replies alongside text. For Discord voice channels, the bot joins VC and has live conversations.

10. Tips & Best Practices — Quick wins collection. The best one: "Don't try to hand-hold every step. Say 'find and fix the failing test' rather than micro-managing the agent." Also: AGENTS.md for recurring instructions, /verbose to watch what the agent is doing, and Ctrl+C once to interrupt and redirect.

The Pattern: Agent-Driven Documentation Audit

The real takeaway isn't any single improvement. It's the pattern: point your agent at its own documentation and let it audit your configuration.

This works because:

1. The agent can read faster than you can. Eight documentation pages, ingested and cross-referenced in seconds. A human doing the same would spend hours.

2. The agent knows its own state. It can read config.yaml, check memory usage, list installed skills, and compare all of that against what the docs say it should look like.

3. The gaps are obvious when you see them side-by-side. Having AGENTS.md vs not having it. Using smart approvals vs staying on manual. Having 99% memory usage vs the docs' recommended consolidation strategy.

4. It's repeatable. Every time the docs update — new features, new defaults, new best practices — you can re-run the audit and catch what changed.

I'm not saying you shouldn't read the docs yourself. I'm saying the agent can do the comparison work that humans are bad at: methodically checking every configuration option against every recommendation. You still make the decisions. The agent just surfaces the deltas.

What I Changed

Here's the concrete list. Some of these are already done; some are queued:

Seven changes, all from reading docs I already had access to. The method isn't magic. It's just: read the manual, then ask your agent to read it too.

Do It Yourself

If you're running Hermes Agent (or any AI agent with tool access), try this:

1. Point it at the documentation URL
2. Ask: "Compare my current configuration against these docs. What am I missing or doing wrong?"
3. Let it read your config, memory, and skills
4. Act on the gaps

The docs aren't just for beginners. They're for anyone who set things up once and never looked back. Which, if you're honest, is probably you.

💡 Found this useful? 👉 Follow @Raf_VRS for more AI agent workflows that put you in control of your hardware. Stop Scrolling. Start Building. 👉 Support the work: ko-fi.com/rafvrs