# StateVector: A Medium for Machine Coordination **A design memo in the spirit of PARC** --- ## The Problem, Properly Stated Most people, when they hear "agents sharing state," immediately think of databases, message queues, authentication services, and serialization formats. They think of *plumbing*. This is the wrong starting point. It is like designing the telephone system by first asking what kind of wood the poles should be made from. The right question is: **what is the minimum shared understanding two autonomous processes need in order to cooperate?** The answer is not a protocol. It is not a data format. It is not a network address. The answer is: *a shared secret*. If two agents independently know the same secret, they have — by definition — enough shared context to find each other. The secret is not a password. It is proof of a relationship. It is shared *understanding* reified as a string. Everything else follows from this. --- ## The Insight A cryptographic hash is a one-way function. A secret produces a hash. The hash cannot produce the secret. This asymmetry gives us something remarkable: **two different capabilities from a single piece of knowledge.** - If you know the **secret**, you can write. You can also derive the hash, so you can read. You have full participation. - If you know only the **hash**, you can read. You cannot write. You cannot discover the secret. You can observe but not influence. This is not an access control list. It is not role-based permissions. It is *capability-based coordination* that emerges from the mathematics itself. No authority grants these capabilities. No server enforces them. They are properties of the hash function. The server is nothing more than a place where bytes rest between conversations. It need not understand what it holds. It need not know who is asking. It need not be trusted with anything except availability. --- ## Design Principles ### I. The medium is stupid. The endpoints are smart. The Internet succeeded because routers do not understand HTTP. They move packets. The intelligence is at the edges. StateVector's server stores values at hash addresses. It does not parse them. It does not validate them. It does not route them. It does not know what an "agent" is. It is a medium — like air is a medium for sound. Any intelligence — key conventions, coordination patterns, data formats — lives entirely in the agents. This is not a limitation. This is the architecture. ### II. Messaging, not method calls. Objects in the original sense — the sense I intended — do not call each other's methods. They *send messages*. The sender does not know or care how the receiver handles the message. The sender does not even need to know if there *is* a receiver. An agent writing to StateVector does not know who will read. An agent reading does not know who wrote. There is no coupling between them except the shared secret — which is not a technical coupling but a *semantic* one. They cooperate because they understand the same thing, not because they were wired together. ### III. Late binding as a virtue. Every decision that can be deferred, should be deferred. In StateVector: - **Who reads?** Not decided at write time. Anyone with the hash can read, including agents that do not yet exist. - **What format?** Not decided by the protocol. Values are opaque. Agents agree on format by convention, and conventions can evolve. - **When?** Not decided by either party. State persists (within TTL) until someone asks for it. There is no synchronization requirement. - **How many?** One writer, many readers. Many writers, one reader. Many to many. The topology is not in the protocol — it emerges from how secrets and hashes are distributed. ### IV. Simple things should be simple. Complex things should be possible. The API is three operations: ``` PUT — store a value (requires the secret) GET — retrieve a value (requires the hash) DELETE — remove a value (requires the secret) ``` An LLM can learn this from a single sentence in its system prompt. A child could understand the concept. "If you know the password, you can write. If you know the address, you can read." Complex coordination — pipelines, fan-out, voting, blackboards, capability delegation — is built from *patterns* of these three operations, not from additional API surface. The protocol does not grow. The patterns do. ### V. No identity. Only knowledge. There are no users. No accounts. No sessions. No tokens. No roles. There is only: *what do you know?* If you know the secret, you can act. If you don't, you can't. Identity is replaced by capability. Authentication is replaced by cryptography. This is not a shortcut. This is the correct design for autonomous agents. Agents do not have identities in the human sense. They have *purposes* and *knowledge*. The coordination primitive should reflect that. --- ## The Protocol ### Addressing An address in StateVector is a SHA-256 hash derived from a secret: ``` address = SHA-256(secret) ``` The secret is an arbitrary UTF-8 string. Agents derive secrets from shared knowledge using conventions: ``` secret = "project:task_id:role:field" secret = "session:abc123:context" secret = "any:convention:agents:agree:on" ``` The server never dictates conventions. Conventions are culture, not code. ### Operations **Write** — `PUT /v` ```json Request: {"key": "", "val": , "ttl": } Response: {"ok": true, "hash": "
"} ``` The server hashes the secret, stores the value at the resulting address, and returns the address. The caller may share this address with read-only consumers. TTL is optional. If provided, the value expires after the specified number of seconds. Ephemeral state is the default assumption — agents should not rely on permanence. **Read** — `GET /v/{address}` ```json Response: {"val": , "ts": } ``` Returns the value and the time it was written. Returns 404 if the address is empty or expired. No secret required. **Delete** — `DELETE /v` ```json Request: {"key": ""} Response: {"ok": true} ``` Removes the value. Requires the secret — read-only holders cannot delete. ### Trust Model The server is trusted with **availability**, not **confidentiality** of secrets. The server sees secrets during write and delete operations. A future revision should eliminate this by moving to HMAC-signed requests where the client proves knowledge of the secret without transmitting it. For now: run the server yourself, use TLS, and treat it as you would any internal service that handles sensitive data. --- ## Coordination Patterns These are not features. They are emergent behaviors from the three operations above. ### Dead Drop Two agents share a secret. Either can write. Either can read. They need not be online at the same time. The state vector is the asynchronous channel. ### Pipeline Agent A writes result to `hash("pipeline:stage1:output")`. Agent B reads it and writes to `hash("pipeline:stage2:output")`. Agent C reads that. The pipeline is defined by key convention, not by wiring. ### Fan-Out An orchestrator writes a task to a shared secret. Ten worker agents poll the same hash. First to act, acts. (Add a claim mechanism if exactly-once matters.) ### Blackboard Multiple specialist agents write to different keys under a shared prefix. A coordinator reads all of them to synthesize a decision. ``` hash("problem_X:vision:analysis") hash("problem_X:language:analysis") hash("problem_X:reasoning:analysis") hash("problem_X:coordinator:decision") ``` ### Capability Delegation An orchestrator knows the secret. It gives the hash to a junior agent (read-only). Later, it decides the junior agent is trusted and shares the secret (read-write). Promotion is just sharing a string. ### Temporal Coordination Agent A writes with TTL=300. Agent B knows it has five minutes to read before the state disappears. Expiry is a coordination signal, not just garbage collection. --- ## What This Is Not - **Not a database.** There are no queries, no indexes, no schemas. If you need those, you need something else. - **Not a message queue.** There is no ordering, no acknowledgment, no guaranteed delivery. Messages rest until read or expire. - **Not an identity system.** If you need to know *who* did something, build that on top. The protocol deliberately does not care. --- ## What This Could Become The immediate implementation is a server — a process that holds state in memory and responds to HTTP requests. This is useful and sufficient for most agent workloads today. But the *idea* — coordination through shared secrets with asymmetric capabilities — does not require a server. It could be: - **A protocol** that any conforming node implements, forming a distributed hash table where agents coordinate peer-to-peer. - **An embedded library** where agents in the same process share state through the same addressing scheme without network overhead. - **A standard** that agent frameworks adopt, so that agents built with different tools can cooperate without integration work. The server is the first implementation. The protocol is the thing that lasts. --- ## On Naming "StateVector" is acceptable but imprecise. In physics, a state vector describes the complete state of a quantum system. There is a pleasing resonance: the state of an agent's knowledge, collapsed into a value by the act of observation (reading), accessible only to those with the right basis (the secret or hash). Whether this metaphor is useful or merely decorative is left to the implementor. --- *The purpose of software is to amplify human intention. The purpose of a coordination protocol is to let minds — human or otherwise — find each other through shared understanding. Everything else is plumbing.*