This was originally published on All Agents Considered.
I just got back from two weeks on the Croatian coast. While scrolling in a café in Rovinj, a Forbes headline caught my attention and I had to read the whole thing. AI costs more than the people it was supposed to replace. The technology that was promised to make labor cheaper is, at this moment, more expensive than the humans it was meant to displace.
That made me realize something. A few months earlier, I spent three weeks swapping models, adding MCPs, and building automation layers because Hermes kept getting confused. I kept chasing smarter models and better integrations when the problem was my workspace the whole time. None of it worked until I stopped adding tools and started looking at the files underneath them.
I wrote about the fix in a previous piece, and that article showed what a clean workspace looks like after reorganization, but people kept asking me the same question: how do you know which folder is broken before you start fixing things?
Today I cover the five-point audit I use, a prompt that runs it through Hermes itself, and how to pick the one fix that matters most without rebuilding your entire setup.
In this piece:
Why adding tools before auditing your workspace makes the same problem worse, because every new tool inherits the same confusion
A five-point audit that finds exactly where Hermes gets lost in your files and takes twenty minutes to run
A copy-paste prompt that audits any folder through Hermes itself and tells you where the confusion lives
How to pick the one fix that matters most without reorganizing your entire setup or over-structuring folders that work fine
When Tools Inherit the Mess
The hardest thing about working with Hermes, or any other AI harness for that matter, is accepting that it has no memory of what I already know.
When I open a folder, my brain automatically filters everything. I remember which draft I was working on yesterday, I can tell the difference between notes from this month and notes from six months ago, and I know exactly which file I need because I remember writing it.
Hermes doesn’t get any of that context. It looks at my workspace the same way a stranger would, reading only what’s visible right now and making assumptions based on file names, folder names, dates, and whatever instructions I happened to give it.
That gap between what I know and what Hermes can see is where everything breaks down.
If current and archived files look identical from their names alone, Hermes treats them as equally valid options and sometimes picks the wrong one without realizing it. If there’s no clear starting point in a folder, Hermes has to search through everything before it understands what it’s looking at. And if draft work lives in the same space as public actions, Hermes has no way to know when it should stop and ask for permission.
This is why my Hermes maintenance routine only works when the workspace underneath it is clean.
That routine checks models, memory, cron jobs, and gateway health, but every single one of those checks depends on reading from files. When the files are a mess, the routine produces noise instead of signal.
Workflow handoffs and approval gates fail the same way because they all assume Hermes knows where to read, where to write, and when to ask before acting. Those assumptions collapse the moment the folder structure doesn’t make those answers obvious.
I learned this by watching the same failure repeat every time I tried to fix it with a new tool.
A smarter model reading the wrong file still produces the wrong answer. A new MCP fetching data into a folder with no structure still loses the output somewhere. Switching providers doesn’t change where Hermes writes things down.
The one variable that determines whether Hermes succeeds or searches in circles is the one I kept ignoring, because it wasn’t as exciting as upgrading to a better model or connecting a new integration.
The 20-Minute Audit
My audit runs five checks on one folder Hermes touches often. Pick that folder and open it like Hermes would, with fresh eyes and no memory of what’s inside.
Hermes Workspace Audit
1. Active work
There is one obvious place for current work.
Pass if Hermes knows where current drafts, notes, or tasks live.
Fail if current and old material share the same folder.
2. Archive boundary
Old files have a separate archive folder.
Pass if archived material is clearly historical.
Fail if old files look current from the filename alone.
3. Entry point
The folder has an obvious starting file when it has multiple subfolders.
Pass if the first file tells Hermes where to start.
Fail if Hermes has to search before it understands the folder.
4. Handoff path
Each repeated workflow has an input and output location.
Pass if Hermes knows where to read and where to write.
Fail if every run invents a new output location.
5. Risk boundary
External, paid, destructive, or public actions have a review step.
Pass if Hermes knows when to stop.
Fail if the same instruction lets it draft and publish.
Walk through each check on one folder. Don’t audit the whole vault, don’t reorganize anything yet. Find the one folder where Hermes wastes the most time and understand why.
This prompt runs the same audit through Hermes:
Audit this folder as if Hermes had to work inside it.
Folder path or description:
[PASTE FOLDER PATH OR DESCRIBE THE FOLDER]
Main task Hermes should do here:
[DESCRIBE TASK]
Check the folder across these categories:
1. Active work
Does the current source of truth stand out.
2. Archived work
Does old material look separate from current material.
3. Starting point
Is there an obvious first file, root map, or README.
4. Handoffs
Are input and output locations clear.
5. Risk boundary
Are public, paid, destructive, or external actions separated from draft work.
Return:
- what would confuse Hermes
- the first file it should read
- the first file or folder I should rename, move, or index
- whether this folder needs a root map, and a recommendation on creating an INDEX.md for it
- one warning about over-organizing this folder
Run it on the folder you audited by hand and compare the results. If Hermes finds problems you missed, your instinct about the folder was incomplete. If you find problems Hermes missed, your prompt needs more context about the task. You can build this as an agent or skill file, or keep it in your docs and point Hermes to the folder when you’re running the audit.
Walking Through an Audit
Let me show you what this looks like with a real folder so you can see where to pay attention and how to interpret what you find.
I’ll use the research workflow I rebuilt in my previous piece because it’s a concrete example of what happens when you get the structure right from the start. The folder is called 01.Research Sorter and it holds the entire workflow that turns raw research links into scored article angles.
01.Research Sorter/
├── 01.instructions.md
├── 02.input.md
├── 03.output.md
└── 04.review.md
Four files, numbered for reading order, each with one job. Let me walk through how each audit check applies to this folder.
{image 5: diagram-036-folder-pass.png — Infographic: folder structure passing all five audit checks}
Check 1: Can Hermes find the current work? Pass. The numbered prefixes tell Hermes exactly where to start. 01.instructions.md is the entry point, 02.input.md is where I paste my research links, 03.output.md is where Hermes writes the scored results, and 04.review.md is the checklist I run through after. There’s no ambiguity about which file matters for which step. Hermes reads the instructions first, then moves to the input, then writes to the output. The sequence is explicit.
Check 2: Archive boundary. Pass. This folder only holds the current workflow. Old research runs get archived to a separate Archive folder once I’ve picked an article angle from them. The active folder stays clean because completed runs don’t pile up inside it.
Check 3: Entry point. Pass. 01.instructions.md is the obvious starting file. When Hermes opens this folder, it reads the instructions first and knows exactly what the workflow does, what the brand filter is, and how to score each item. No searching required.
Check 4: Handoff paths. This is where the audit caught a real problem in my earlier version. Before the rebuild, my research workflow would write output to different locations depending on what I’d told Hermes that day. Sometimes it went to 01.Articles/Drafts, sometimes to the root folder, sometimes to a folder I’d created on the fly. Every time Hermes had to find the output from the last run, it had to search again. The numbered file structure fixes this as 03.output.md is always in the same place. The next workflow step knows exactly where to look.
Check 5: Risk boundaries. Pass. This folder only produces draft observations and article angles. Nothing in it triggers a publish action or sends anything public. The actual writing and publishing happens in a separate workflow folder with its own risk boundaries. That separation means Hermes can run this research workflow freely without accidentally pushing something live.
Once I walked through these five checks, I could see why this workflow runs reliably while others didn’t. The structure answers every question Hermes might have before it asks.
The key thing I learned from auditing this folder is that you’re not looking for problems in isolation. You’re looking for the one problem that creates the most confusion for Hermes. In folders that fail the audit, the archive boundary is usually the biggest issue because it affects every single task.
That prioritization is what makes the audit useful. You’re not trying to fix everything at once. You’re trying to find the one thing that, if fixed, would make the biggest difference across most tasks.
Pick One Fix
Find the single issue from the audit that creates the most Hermes confusion. One fix, not five.
If current and archived files live together, fix the archive boundary first. Move old files to a separate archive folder. This one change solves more Hermes confusion than any other because it stops the most common failure: picking the wrong version of a file.
If outputs are unclear, define where Hermes should write before changing any tool. Create one output folder and point Hermes at it every time. Consistency matters more than location.
If there’s no starting point, build the INDEX.md pattern from my piece on file-first agent workflows. Read that piece, build one INDEX.md for the folder that failed the audit, and run the same task again. If Hermes finds the right file in under thirty seconds, the fix worked.
What you shouldn’t do is fix everything at once. Most of your folder names are fine, and the audit tells you which ones confuse Hermes. I wrote about the over-organizing trap in my previous piece on file-first agent workflows, where adding INDEX.md to every subfolder made Hermes slower. The short version: add only enough structure to fix the specific problem the audit found.
Also, don’t use memory to paper over bad file structure. Memory tells Hermes things across sessions, but it doesn’t help Hermes find the right file inside the current one. If the folder is confusing, fix the folder. And don’t add another MCP before Hermes knows where the work lives. I wrote about the MCP versus CLI versus custom tool decision in a previous piece. If Hermes can’t find files in a clean local workspace, no external tool integration will compensate.
Once the workspace is clear, the tool choice gets easier. A clear local workspace often points to CLI or file tools first. Shared external systems point to MCP. Repeated narrow steps point to a custom wrapper or skill. Most of the time, the audit reveals that I don’t need a new tool. I need a better folder. Even when I’m running multiple agent frameworks through the same Hermes brain, the workspace structure is what makes it work. Different agents, same files, same folder map.
If the broader stack is what you’re after, whether that’s provider routing, memory ownership, or scheduled workflows, I wrote the full cost breakdown of the stack and the morning workflow that runs on it. Both of those depend on the same workspace audit pattern to stay reliable across sessions.
Everything I’ve written about in this newsletter traces back to one instinct. Own the layer that matters. I built my stack so no company controls my tools. I built my workflows so no noise controls my output.
Capability is cheap when the foundation is broken. Audit one folder. Fix one thing. Then decide whether you need another tool.
Top comments (0)