Directors, Specialists, and a Shared Knowledge Base: Teaching AI Agents to Work as a Team

Directors, Specialists, and a Shared Knowledge Base: Teaching AI Agents to Work as a Team

The problem that shows up the moment you have more than one agent

A single AI agent is straightforward. The moment you have several — which happens fast once each service on a home server gets its own agent — two new problems show up immediately: how do you get multiple specialists to actually collaborate on one deliverable, and how do you keep independent agents aware of each other without forcing them to share a memory file? Multi-Agent Interaction is the pattern I settled on for both, after retrofitting a shared knowledge base onto agents that were already running independently taught me it’s real extra work — worth building in from day one instead.

Pattern one: director-dispatch, with one non-negotiable rule

For any task with a single shared deliverable — a system audit, a document review — one agent (the director) holds the overall plan and hands out focused tasks to specialists. The specialists are stateless per dispatch: each call is a fresh session with no memory of any earlier round, so the director has to explicitly re-include any context a specialist needs. That’s a deliberate constraint, not a limitation I’m working around — it keeps each dispatch cheap and predictable.

The rule I treat as non-negotiable: review never merges into drafting. If one specialist’s job is to produce something and another’s is to check it, those are always separate dispatches — even when combining them would obviously be more efficient. A drafting agent checking its own output tends to confirm its own assumptions; the whole value of an independent reviewer disappears the moment it’s folded into the same call that produced the thing being reviewed.

Pattern two: shared knowledge, no central dispatcher

The other shape of coordination doesn’t have a single deliverable at all — it’s a set of independent agents, each owning its own domain, that occasionally need to stay aware of each other. For that, I built a real shared folder every agent reads and writes to:

• An introductions file — each new agent’s name, what it does, and any personality it has, so agents can “meet” each other by reading past entries.
• A routing table — which agent owns which domain, and when a task should be handed off instead of handled locally.
• A handoff template — a structured format (request, goal, context already checked, constraints, requested output) so a receiving agent doesn’t have to reconstruct everything from scratch.
• A running change log — one shared place any agent logs a significant change, so others can check “what’s changed recently” without needing each other’s full history.

The failure mode I had to build a mechanical fix for

The shared knowledge base only has value if agents actually read and write to it — and identity-file instructions alone degrade over a long session, especially in headless or one-off runs. Telling an agent “log your changes” in its CLAUDE.md wasn’t durable enough on its own. The real fix was mechanical, not textual: a Stop hook that scans an ending session’s transcript for shared-state changes (service commands, file writes outside the agent’s own folder) and soft-blocks the session from finishing until the logging step has run — or the agent states an explicit one-line waiver. Keeping it soft (waiver allowed, fails open on any script error) mattered as much as building it at all; a hard block that can misfire teaches agents to game the waiver instead of log honestly.

The change log itself needed a second fix once it had been running a while: nothing was pruning it, and a rule that only lived in a doc got forgotten for two months. The durable version builds rotation into the logging skill itself — at each month boundary, prior-month rows move verbatim into a per-month archive file, and the live table always keeps the most recent rows visible. A rule that runs every time the log is written to can’t be silently skipped the way a rule that lives only in someone’s memory can.

What it demonstrates

This is applied distributed-systems thinking, even though the “nodes” happen to be AI agents instead of services: stateless workers, a coordinator that owns the plan rather than the work, mandatory separation of concerns between producing and verifying, and a lightweight shared-state layer instead of a fully synchronized shared memory. The two real fixes — the Stop-hook enforcement and the change-log rotation — are both cases of noticing that a policy living only in instructions isn’t a policy that reliably holds, and moving the actual guarantee into something mechanical instead.

Part of the Homelab AI Blueprints series — see all nine blueprints for building and operating a self-hosted, AI-agent-run home server.