Savvy Baristas at Good Brew

I manage a personal knowledge graph with over 9,000 interconnected thoughts built over a decade in TheBrain. When I started building MCP servers to give Claude programmatic access to my tools and services, I knew a coordination solution would be necessary. Multiple AI agents, each stateless, working alongside a human across days and weeks on sustained projects — that requires shared mutable state, clear conventions, and visual ergonomics. README files and conversation history were never going to cut it.

So Claude, Claude Code, and I built a task coordination protocol inside the knowledge graph itself. Here's the architecture, the rationale, and enough detail for you to build your own.

The Coordination Problem

If you're doing real project work with AI agents — not one-off questions, but multi-session development across design, implementation, and deployment — you need to solve for this: every new agent session starts with zero memory. Claude Code doesn't know what claude.ai decided this morning. Tomorrow's session won't remember today's. And the human has tasks of their own (credential setup, deployments, PR merges) that agents can't perform but need to track.

Three requirements follow directly:

1. Shared state that any agent can read and write, on any device, without prior context.
2. Structural conventions that let an agent orient in seconds, not minutes of text parsing.
3. Visual ergonomics so the human can glance at a dashboard and know what's active, what's done, and what needs their attention.

These three requirements must be served by the same artifact. Separate systems drift apart. A single graph that serves agents and humans equally is the only thing that holds.

TheBrain as the Substrate

TheBrain is a knowledge management tool built around an infinite, zoomable graph. Nodes (thoughts) have parents, children, cross-links (jumps), notes, attachments, Types with inherited colors and icons, tags, and labels. It rewards long-term investment — my graph reflects a decade of accumulated structure and relationships.

The architectural foundation: expose TheBrain's full graph API through a Model Context Protocol server. I built thebrain-mcp, a Python FastMCP server that wraps TheBrain's API and adds BrainQuery — a Cypher-like query language for graph pattern matching. Deployed to FastMCP Cloud, it's accessible from any Claude client: web, desktop, mobile, and CLI. Any agent session, anywhere, reads and writes to the same graph.

That handles shared mutable state. Conventions come next.

The Protocol

Every project under my "Claude Thoughts" collection follows the Project Task Management Protocol — a living document stored in the graph itself, readable by every agent on session start.

Structural Hierarchy

Project (e.g., "thebrain-mcp")
  └── TASKS
        ├── Proposed        ← queued for future work
        ├── In-Progress     ← actively being worked
        ├── Parked          ← deferred or superseded
        ├── Done            ← completed
        └── Lessons Learned ← cross-cutting reference

Status is structural, not textual. A task's status is determined by which Kanban column it's parented under. Moving a task means re-parenting it in the graph — not editing a status field in a note. Agents parse graph structure more reliably than free text, so we encode status where parsing is guaranteed to succeed.

An agent arriving fresh navigates to TASKS, sees four columns, checks In-Progress (resume active work?), then checks Proposed (pick up next?). Two graph hops to full orientation.

Individual Task Thoughts

Each task is its own thought with a rich note: goal, specification, acceptance criteria, test cases, and completion notes. The detail lives at the task level, not on the board. The board stays slim — a structural index, not a specification dump — under 3KB so agents can load it in a single tool call and still have context window for real work.

Blocked Task Signaling

When a task needs human action — merge a PR, configure a service, approve credentials — the agent tags it with @todo, a shared Brain tag visible in the Brain UI's tag filter. The tag overlays the existing column position: the task stays in In-Progress with an additional @todo signal. When the human resolves the block, they remove the tag and leave a note. The next agent session sees the unblocked task and picks up where the previous one left off.

Definition of Done

Code tasks aren't Done until the PR is merged and deployed. The Protocol maps each pipeline stage to a column and label. A merged-but-undeployed task stays in In-Progress with a "Merged (pending deploy)" label. Agents should never mark tasks complete prematurely — subsequent sessions would assume the work is live when it isn't.

The Type System: Visual Clues for the Humans

TheBrain's Type system propagates visual properties — colors and icons — to all typed thoughts. We use four status Types as children of a 🤖 Agent Task parent Type:

Type	Color	Meaning
Done Task	Green	Completed through full pipeline
In-Progress Task	Amber	Actively being worked
Proposed Task	Blue	Queued for future work
Parked Task	Gray	Deferred or superseded

The Type hierarchy:

Task
├── 👤 Human Task
└── 🤖 Agent Task
      ├── Done Task        (green)
      ├── In-Progress Task (amber)
      ├── Proposed Task    (blue)
      └── Parked Task      (gray)

Assigning a status Type to a task turns it the right color everywhere in the graph. Icons set on a Type thought in the desktop app propagate to every task assigned that Type. Set it once, see it everywhere.

When an agent moves a task between columns, it performs three operations: re-parent the thought, retype it, and update the label. This is triple-signal — structure, color, and text all communicate the same status. The human glancing at the graph sees color. The agent traversing the graph reads structure. The agent parsing metadata reads the label. Three redundant channels mean a partial failure (an agent skips the label update) still leaves two correct signals.

One constraint to plan for: TheBrain allows only one Type per thought. Using the Type slot for status precludes semantic typing like "Infrastructure Task." This is the right trade-off — tasks are already categorized by their project parent and their name. If secondary categorization becomes necessary, jump links to Type thoughts serve that purpose without consuming the Type slot.

Multi-Agent Workflow in Practice

A typical workday across my three active projects:

Morning, claude.ai. Design session. Claude and I evaluate architecture options, research third-party tools, and make strategic decisions. Claude writes design notes directly into the relevant task thought, creates new tasks under Proposed with the correct Type, and jump-links related tasks across projects.

Afternoon, Claude Code. Implementation session. Claude Code reads the Protocol (it's right there in the graph), navigates to In-Progress, loads the active task's spec, writes code, runs tests, creates a PR. On completion: re-parent to Done, retype as Done Task, update the label with the date and PR number, write completion notes into the task thought.

Evening, the human. I open TheBrain. A wall of green in Done, a spot of amber in In-Progress, a @todo tag on a task waiting on me. I handle the manual step — approve a credential, merge a PR, configure a service — remove the @todo tag, leave a note. Tomorrow's agent session picks it up without any briefing.

No agent remembers the last session. None of them need to. The graph is the memory. The Protocol is the coordination mechanism. The Types and colors are the dashboard.

The Conformance Principle

The Protocol includes a conformance check that every agent runs on session start: does the project have the four Kanban columns? Are tasks parented correctly? Do status Types match column placement? If anything is out of conformance, restructuring is the first order of business before any project work begins.

The governing principle: the crowd cleans the commons. Every agent session leaves the structure at least as clean as it found it. Agents don't just consume infrastructure that humans maintain — they maintain the infrastructure as part of using it. The restructuring operations are the same graph operations agents use for task work: create thoughts, create links, delete links, update types. There is no separate "admin mode." Maintaining the system and using the system are the same activity, which is what makes it sustainable.

How to Build Your Own

If you want to replicate this system, here's the prescription.

Make status structural, not textual. Encode status in graph topology — which column parents which task — not in text fields that require parsing. A graph hop never fails. A regex might.

Keep the board slim. The TASKS board should be under 3KB: just the Kanban columns and their children. Full task specs belong in individual task thoughts, loaded on demand. Agents should spend their context window on work, not on orientation overhead.

Use triple-signal for status. Structure (column placement), color (Type inheritance), and text (label) should all agree. Design for the case where one signal is stale — the other two still tell the truth.

Put the Protocol in the graph it governs. Not in a README. Not in a wiki. In the same graph agents traverse for task work. The Protocol should be one hop from any project, encountered naturally during orientation.

Leverage Type inheritance for visual consistency. Set an icon and color on a Type thought once; every task of that type inherits it across every project. This is the leverage that makes a Type hierarchy worth the single-assignment constraint.

Require conformance checks on session start. Every agent, every session. If the structure has drifted, fix it first. Small maintenance on every session prevents large restructures later.

The Technology Stack

TheBrain — knowledge graph, 9,200+ thoughts, Types, tags, rich visual properties
thebrain-mcp — open source MCP server (Python/FastMCP), BrainQuery, full CRUD, paginated traversal, multi-tenant credentials
FastMCP Cloud — remote deployment for cross-device agent access
Claude (claude.ai) — design, research, strategy sessions
Claude Code — implementation, testing, PR workflow
BTCPay Server + Lightning — payment infrastructure for API monetization (the project that stress-tested the full Kanban pipeline across all three agent types)

The thebrain-mcp server is on GitHub. The Protocol, Type hierarchy, and Kanban structure described here are all reproducible in any TheBrain instance. The coordination pattern generalizes to any shared graph agents can read and write — but TheBrain's visual properties, Type inheritance, and decade-friendly data model make it particularly well suited.

Build the structure once. Let the agents maintain it. Glance at the colors. Ship the work.

Reach me:

🛒 stablecoin.myshopify.com
🐙 GitHub: lonniev
🐦 Find me on X — likes are appreciated

If this was valuable, I accept blockchain tips.