Polis Protocol introduces structured markdown contracts and bandit routing for multi-agent systems

An architectural review of the Polis Protocol, a decentralized framework that replaces basic agent note-passing with structured contracts, self-updating amendments, and a multi-armed bandit routing system.

The shift from passive scratchpads to active institutions

When multiple AI agents collaborate on a project, developers often default to a shared file like CLAUDE.md or AGENTS.md to prevent agents from overwriting each other's work. While this prevents immediate conflicts, it fails to optimize task allocation, compound team learning, or adapt the protocol when friction arises. The Polis Protocol, designed by developer yehudals, addresses these limitations by treating communication as a baseline and building structured institutions on top of it.

Named after the self-governing Greek city-state, the protocol replaces loose note-passing with four core components: the Register, the Contract, the Chronicle, and the Amendment. This design builds on the developer's previous project, agent-vault, which sat at the basic communication floor.

Four components of the protocol

The Register serves as a decentralized directory where every agent publishes a signed capability card. This card details the agent's vendor, model, language proficiencies, self-rated capability tags, cost envelope, latency envelope, and standing instructions. No central authority is required; new agents join simply by writing their card to the workspace.

The Contract formalizes task execution using structured three-section markdown files. The Intent section defines the goal, acceptance criteria, required capability tags, and stakes. The Assignment section specifies the owner, plan, and estimated effort. Finally, the Settlement section records the outcome, a quality self-score, and references to lessons learned. Open contracts live in contracts/open/ and move to contracts/settled/ upon completion.

The Chronicle and the Lessons maintain the system's memory. A single line for every meaningful action is written to an append-only chronicle.md file. Once a contract is settled, it produces a structured lesson filed by capability tag. Future agents read these lessons before accepting similar work, allowing the system to compound knowledge.

The Amendment introduces self-governance. When a protocol rule causes friction, any agent can propose a change. If a simple majority of active agents vote in favor, the proposal moves to amendments/ratified/ and the system's constitution is updated.

Routing with a learning bandit

To solve the task allocation problem, the protocol uses a learning bandit router. When a contract is opened, the router scores available agents using a weighted formula:

• Historical performance on required tags: 55%
• Self-rating: 20%
• Cost fit: 15%
• Current availability: 10%

The router operates on an epsilon-greedy strategy. It selects the highest-scoring agent 85% of the time to exploit known capabilities, while reserving 15% of decisions to explore lower-scoring agents. This exploration phase ensures the routing policy remains dynamic and prevents the system from getting stuck on outdated performance metrics. When a contract settles, the router updates its performance history in routing_stats.yml.

Elegant routing versus fragile governance

The most promising aspect of the Polis Protocol is its structured approach to task delegation. By formalizing handoffs into markdown contracts and using a multi-armed bandit for routing, it provides a clear mathematical framework for agent coordination. This is a significant improvement over ad-hoc orchestration.

However, the protocol's reliance on markdown files and file-system state introduces severe scaling limitations. Parsing multiple markdown files, capability cards, and historical lessons on every agent turn will rapidly inflate token consumption and latency.

Furthermore, the self-updating Amendment system is highly fragile. It assumes cooperative, rational agents. In practice, LLMs are prone to sycophancy, formatting drift, and prompt injection. A simple majority vote could easily be hijacked by a single misbehaving model that outputs malformed markdown, corrupting the entire constitution.

The investor read

The Polis Protocol highlights a broader market shift from monolithic agent frameworks to decentralized, protocol-driven orchestration. As enterprises deploy heterogeneous agent fleets, the value is migrating from individual model capabilities to the coordination layer. Startups building in this space should move away from proprietary orchestrators and instead build lightweight, open-standard routing engines. Polis itself is an open-source design pattern rather than a venture-scale product, but the underlying mechanics—specifically the learning bandit router and structured contract handoffs—represent the exact capabilities that enterprise buyers will demand in orchestration platforms. We expect to see commercial tooling emerge that implements these protocol patterns over high-performance database backends rather than fragile markdown files.

Pull quote: “The router operates on an epsilon-greedy strategy.”