Building a memory system in isolation is one thing. Making it play nice with an existing agent framework is where the real pain lives. I spent the better part of a week fighting Hermes Agent's plugin system, and I have the commit history to prove it.
The theory was simple. Hermes has a plugin loader that looks for a `register()` function in your module. You expose your tools, the agent picks them up, everyone is happy. The practice was... not that.
The directory mismatch bug
Hermes installs plugins to `~/.hermes/plugins/`. Mnemosyne expected to find its data in `~/.local/share/mnemosyne/`. When Hermes loaded the plugin from its own directory, relative paths broke. The database file ended up in the plugin directory, or didn't get found at all, or got created in a temp folder that vanished on reboot. I spent an entire afternoon tracing why memories kept disappearing before I realized the plugin was looking in the wrong place.
The fix was an install script that detects where Hermes lives and creates symlinks. It sounds trivial now. At the time, it felt like performing surgery with a butter knife. I committed it with the frustrated message: "fix: add install script to handle Hermes plugin directory mismatch (Issue #2)."
The register() export saga
Hermes expects a `register()` function at the module level. I had one. But it wasn't being found. Why? Because Python's import system is subtle, and Hermes' plugin loader is pickier than it looks. The function needed to be exported in `__init__.py`, but it also needed to handle the case where `hermes_plugin` wasn't available (for standalone installs). And it needed to work both as a direct import and as a dynamically loaded plugin.
I went through four iterations. First attempt: `register()` in the main module. Second attempt: separate `hermes_plugin.py` file. Third attempt: lazy imports with graceful fallback. Fourth attempt: combine everything into a single `register()` that handles both modes. Each fix created a new edge case. Each edge case required another commit. The final solution looks obvious in hindsight. It always does.
The cross-session recall bug
Once the plugin loaded, I discovered that working memory wasn't persisting across sessions. The agent would remember things within a conversation, but start a new one and it was back to square one. The bug was in how `working_memory` scope was handled: it was being created fresh for each session instead of being recalled from the previous one. The fix required changes in three files: `beam.py` for storage, `provider.py` for retrieval, and `tools.py` for the API.
Then there was the subagent problem. Hermes sometimes spawns subagents for parallel tasks. Each subagent was trying to write to the same database, causing lock contention and occasional corruption. I ended up blocking writes in subagent context entirely, which isn't elegant but at least doesn't break things.
Why plugin systems are harder than they look
The thing about plugins is that you're not just writing code for your system. You're writing code that has to survive in someone else's environment, with their assumptions, their file structure, their lifecycle. You don't control when your code gets loaded. You don't control what else is running. You don't even control the working directory.
By the end of that week, Mnemosyne had a proper plugin system, a MemoryProvider mode, and enough defensive code to handle most of the weird ways Hermes could load it. The plugin.yaml file moved to the repo root. The install script handled directory detection. The `register()` function worked in both standalone and plugin mode. It wasn't pretty, but it was robust. And I learned something: integration is where projects live or die. You can have the best memory system in the world, but if nobody can plug it in, it doesn't matter.