Brain

Shared memory, multi-agent coordination, and infra judgement — native to Zerops.

Any MCP-compatible coding agent (Claude Code, Cursor, Codex) gets three things no single agent session has on its own:

1. Persistent shared memory — facts and decisions survive a session and are visible to every agent, not only the one that learned them.
2. Multi-agent coordination — a single-writer lock so two agents acting on the same Zerops project don't collide. Plus the Observatory, a live dashboard so coordination can be watched rather than taken on trust.

Why this and not ZCP

ZCP already does the end-to-end infra work, and does it well — its own docs describe the loop as "the agent reads live state, chooses the app runtime and dependencies, changes the app, deploys through Zerops, verifies real behavior, and returns proof or a blocker." The ZCP container ships zcli and a Zerops MCP server, so anything inside it can already deploy, scale and inspect the project. Brain does not reimplement any of that. An earlier draft of this README promised an infra.provision / infra.deploy / infra.scale tool surface; that was a duplicate of the toggle, and it was cut.

What ZCP does not have is the layer this builds, and Zerops' own product makes the gap concrete rather than theoretical:

No memory. The documented recovery from an interrupted session is "Chat history is not the source of truth… Read current project status and tell me where this project stands before changing anything." Live state tells an agent that Redis exists. It cannot tell it why Redis and not Valkey, or that Valkey was tried and rejected — the decisions and dead ends that are most expensive to re-derive.

No coordination between agents. The project-creation screen offers to install Claude Code, Codex, Antigravity, Grok Build and Cursor CLI into the same ZCP container, and gives them nothing to share memory with or to keep them off each other's work. Two agents in that one container are strangers. Across projects it is stronger still: ZCP access is "sealed inside the project's own VXLAN", so an agent in my-project-johnd and one in my-project-janed are on different private networks and can only meet through a GitHub pull request — which carries a diff, not the reasoning behind it.

---

Built for The Zerops Challenge, Aug 8–9 2026

Prior work vs. work built during the event

The rules permit reusing code the builder already owns, provided it's clear which is which. So it is stated plainly, and checkably:

Prior work — four files from a previous personal project (Notch), kept verbatim in prior-art/notch/ and excluded from the build so they can be diffed against what replaced them:

file	lines	what it contributed
baton.ts	99	the single-writer coordination protocol
eventlog.ts	275	the append-only event-store pattern
brain.ts	518	memory as folded add/update/forget events
brain-index.ts	365	hybrid recall (entities ∪ BM25)

1,257 lines of prior art. Nothing else was carried across. Notch is a ~20,000-line multi-agent orchestrator with six ADE adapters, a mobile app and a desktop shell; none of that is here, because none of it is Brain.

Built during the event — everything under src/, starting with the one change that matters most:

prior-art/notch/baton.ts arbitrates its lock by reading a JSON file, checking the holder, and writing it back. On one laptop that's fine — single writer, microsecond window. On Zerops it's a real bug: the MCP service can run several containers behind a load balancer against one Postgres, so two agents served by two containers can both read holder = NULL and both write themselves in, and both get a success. src/core/lock.ts replaces it with a single INSERT … ON CONFLICT DO UPDATE … WHERE, so Postgres decides under the row lock it already takes. It also adds a TTL, because a dead container leaves a lock no human can delete.

---

What it does

Paste a Zerops Personal Access Token. Brain reads your account through the Zerops REST API and draws your architecture as a live React Flow diagram — container counts, HA mode, public ports, all from the platform. Point it at a local repo and it scans the manifests, works out which managed services the code actually needs, and shows the gap as ghost nodes on the same canvas. One button provisions them for real.

Everything it claims is checkable:

• Container count is what Zerops reports. A service that has never deployed renders "not deployed", never as one container.
• HA is read from mode, never inferred. A single-mode service running three containers during a deploy is not HA.
• Edges only come from connectedStacks. An app and a db in one project are not assumed to talk to each other.
• Every drift finding cites its evidence — the file and the dependency that produced it. A requirement inferred from an env-var name is marked low-confidence, because DATABASE_URL may point at something outside the project.

Run it

docker run -d --name brain-pg -e POSTGRES_PASSWORD=brain -e POSTGRES_DB=brain -p 55432:5432 postgres:16
cp .env.example .env
npm install && (cd ui && npm install && npm run build)
npm run dev            # http://127.0.0.1:7799

Paste your token, pick a project, type a repo path, hit Scan repo for drift. Disconnect hands the token back — it is held in memory only, and never written to disk.

Status

Zerops REST client	done — verified against a live account, 23 tests
Architecture graph	done — pure, 26 tests
Repo scan + drift	done — pure, 24 tests
HTTP API	done — 32 integration tests against a real server + database
Provisioning	done — creates real services, verified and cleaned up
Export zerops.yaml	done
Persisted history	done — Postgres, survives restart
Single-writer lock	done — guards provisioning, 20-way concurrency proven
Deployed on Zerops	not done — needs a zcli login, see below

Every flow above was exercised in a browser against the real API, including the ones that fail: a rejected token, a project that no longer exists, a path that is not on this machine, a directory with no manifests, and a provision confirmed after the HA toggle was changed behind its back. Notes on what that found are in AUDIT.md.

npm test          # 156 tests; the 64 integration ones skip if Postgres is not running
npm run typecheck # src + test, and the UI has its own

Integration tests use their own brain_test database, created on demand — they never write to the log the app reads.

The one thing genuinely blocked

Deploying Brain itself onto Zerops needs a zcli login, which is a credential this repo does not have. Everything else runs and is verified locally against the real Zerops API. Nothing is mocked to paper over it.