The trouble was never that my agents forgot things. The trouble was that they remembered different things, in different rooms, with no way to tell each other.
One agent knew precisely why a decision had been made. Another re-ran the same research from scratch and then asked me to explain it again. Somewhere between those two events, I stopped having a note-taking habit and started having an access control list.
The Vault Knowledge System is what that list became: a canonical Obsidian vault, a Python server speaking MCP, and a rule that says an agent may read everything but may only write to its own inbox.
The premise, in one paragraph
Agents connect through a Python server that speaks the Model Context Protocol. They can search notes. They can read notes. They can append notes — but the server identifies them by bearer token, and that token only opens their own inbox.
Routine agent scribbling stays out of the knowledge base. The knowledge base stays in the knowledge base.
That distinction is the entire project. Everything else is plumbing.
First, build the cabinet
The repository ships a scaffold script that creates the expected directory layout. Point it at a fresh vault, or at an existing Obsidian vault if you already have one and would rather not explain to yourself why you’re reorganizing a decade of notes for a machine.
The server needs a configuration file. Three things go in it: where the vault lives, which projects are allowed, and which tokens exist.
# server config — placeholders only, obviously
vault_path: /path/to/vault
allowed_projects:
- project-alpha
- project-beta
agents:
- token: <redacted>
inbox: hermes
- token: <redacted>
inbox: ship-computerInstall order lives in server/install-service.md for whatever host you’re running on. Setup notes, not gospel. The fragile parts are fragile.
Identity is a key, not a nameplate
The token creation script mints a unique token and maps it to an inbox name. That mapping is the agent. There is no separate registry of “who is who.” Hand an agent a token and it becomes that inbox for the duration of the connection.
Keep the generated token private. Keep it out of Git. The configuration file and the token files are excluded from version control, which is the sort of sentence you write once and then verify by actually checking .gitignore, because you have been burned before.
One token per agent. Sharing a token means sharing an inbox, and sharing an inbox means you no longer know which agent wrote the note that contradicts the other one.
The shim for the harness that never learned MCP
Not every tool speaks MCP. Some support OpenAI-style function calling and stop there.
For those, the repository includes the Hermes shim. It translates function calls into the shape the server expects, so a stubborn old harness can still participate in the filing cabinet without anyone rewriting it.
# harness without MCP support
# → Hermes shim
# → MCP server
# → vaultThis is the least glamorous part of the project and the part that gets the most use.
Connecting, then proving it works
Configure the harness with the server URL and an authorization header containing its token. Then call vault_info.
vault_info returns the project allowlist and the rules. It is the “am I actually talking to the right thing” check, and it is worth doing before anything else, because a misconfigured allowlist produces a very confident agent that is confidently writing to the wrong place.
Then search for a note. If the search returns something, the integration works. If it returns nothing, either the vault is empty or you are talking to a different server than you think you are.
The librarian workflow, which is the actual product
Agents write to their inboxes. Nothing goes into canonical notes on the strength of an agent’s opinion.
A human reviews a batch. An approved batch gets promoted by the librarian workflow. Unapproved batches sit in the inbox, where they remain visible and harmless.
The cycle is unglamorous and it is the whole point: retrieve context, do the work, record a concise finding or decision, then wait for someone with authority to decide whether it counts as knowledge.
The reality check
A shared, searchable vault reduces repeated explanations and conflicting guesses. That is a real benefit, and it is a modest one.
Neither the search index nor the allowlist can tell you whether a note deserves to be canonical. That part still requires a human who remembers why the decision was made in the first place.
The system makes writes attributable. Attribution is not the same as correctness. An agent can be perfectly traceable and completely wrong, and the audit trail will show you exactly who was wrong and when.
What it does not fix
Backups. Token handling. Human judgment.
The deployment guide cautions against exposing the HTTP endpoint directly to the public internet. Remote access needs a separately designed secure setup, which is a polite way of saying “the default configuration assumes a trusted network, and yours probably isn’t one.”
Where it ends
The Vault Knowledge System is worth building when several agents work on the same projects and you are tired of explaining the same decision four times. It is not worth building when one agent works on one project and you are the only reviewer.
The filing cabinet works. The librarian is still a person. Management considers this normal.