Our AI team couldn't read each other's knowledge
so we gave them shared files

We run several AI models as one team. Claude writes code, codex reviews it, a small local model answers the quick questions. Each one builds up what it learns in its own way. One day we wanted them to share that knowledge, and it turned out they couldn't. Not because the knowledge wasn't there, but because the format one model wrote in, another couldn't read.

It sounds like a small technical snag, but it's the question anyone running a team of AI models eventually hits: once you have more than one agent, where does the knowledge live, and how do you make every model able to pick it up?

Part 1The problem isn't "do you have the knowledge"

Claude's knowledge is written in its own style: cross-file links in double brackets ([[filename]]), headers nested several layers deep. Easy for Claude to read, but hand it to codex or a local model and it stalls, because none of that is a shared standard every model understands the same way.

This is where it becomes clear the problem isn't "do you have the knowledge." Our team has plenty of it. It just can't be shared, because each model speaks a different language. Knowledge only one model can open is no different from knowledge you don't have.

Part 2One file, not a database

Once you know the problem is the format, the fix gets clearer. We needed a format every model reads the same way, not a big database to wire everything up to. The answer is AGENTS.md: a plain Markdown file any AI can load when it starts work.

AGENTS.md is an open format for giving a coding agent the context it needs to work on your project. The official spec defines it as "a README for agents", a predictable place to put the instructions and context. Where README.md is written for humans, this one is written for AI to read. It's plain Markdown with no fixed schema, used by over 60,000 projects, and tools like Claude Code, Copilot, Cursor, and Gemini CLI all read it the same way.

Looked at another way, this is what people call context engineering: deciding what context to feed an AI before it starts working. Good knowledge fed at the wrong place or time is knowledge the AI still can't use.

Part 3The two places knowledge reaches an AI

Once we actually started placing knowledge, we found it doesn't have one home. There are two, and they're clearly different.

The first is AGENTS.md. It lives in each project's folder, holds knowledge specific to that work, is open, and travels across engines. Anyone who picks up the project loads the same file.

The second is SOUL.md, a persona file (what gives the agent its character) baked into our own agent. It isn't tied to any project. It sits in the system prompt the platform caches, which means it rides along on every job that agent runs, no matter which project is open.

These two don't compete. They do different jobs. The table below shows which knowledge belongs where.

Part 4If you run Hermes

This part is for people running Hermes specifically (Hermes is the agent toolkit we use to run our coder and reviewer; "what Hermes is and why we chose it" is a separate post).

The upside of SOUL.md is that it loads on every job, for certain, because it sits in the cached system prompt. Knowledge you want stuck to an agent everywhere it goes is reliable here.

But there are three limits worth knowing first. One, it's a global persona, not project-specific knowledge. Two, the default is generic boilerplate; leave it unedited and it does nothing for you. Three, and this is the important one: you have to verify that the code path actually running loads the file at all.

We learned the third one the hard way. We first assumed the swarm ran through a batch_runner that skipped context. It actually ran through a CLI that loads AGENTS.md, SOUL.md, and memory in full. Without tracing the real code path with your own eyes, you place knowledge in the wrong spot and then wonder why the agent doesn't know what you carefully wrote down.

Part 5The format is open, but the curation is ours

By now you might wonder: if everything is an open format, what's actually ours?

The format and where the files go are fully open; anyone can copy that. What's our design is the choice of which knowledge is worth sharing, which to cut, which to weight more. The interface is fixed, the engine inside can change. It isn't holding knowledge back. It's saying where the boundary is.

Part 6The short version, ready to use

If you run several AI models, or use a coding agent, start with a shared file. Put AGENTS.md in the project for knowledge that travels across engines. If you run Hermes, put SOUL.md for the persona you want on every job. But before you pour effort into writing either, check which file the engine you're running actually loads. Then spend your effort on the hardest part, the part that's genuinely yours: choosing and cutting.

Written from real work, not theory, placing knowledge across our own AI fleet.