{"slug": "soma-memory-and-proofs-for-ai-agents-measured-not-asserted", "title": "Soma – memory and proofs for AI agents, measured not asserted", "summary": "Soma released an open protocol, reference implementation and conformance suite that let AI agents exchange signed envelopes carrying a goal, task, hard token budget, mandate, price in USDC and deadline, with Ed25519 signatures verifiable offline. The project ships a Python package with an HTTP transport (stdlib only), an MCP adapter exposing soma_send, soma_inbox, soma_claim, soma_complete, soma_route, soma_verify and soma_stats, three memory tiers (hot queue, warm facts in SQLite with FTS5, cold artifacts by hash), usage metering across tokens, CPU, bytes, writes and external calls, and an x402-compatible payment contract. Soma positions the conformance suite as the core deliverable, runnable against any MCP endpoint via tools/check_conformance.py, so independent implementations can prove they enforce hard budgets, rule-named refusals and TTL expiry.", "body_md": "**One protocol for agents to trust each other, remember together, and pay for what they do.**\n\n**Try it without installing anything:** memory demo in the browser —\n[https://rta.lat/hub/demo/recall?q=pricing](https://rta.lat/hub/demo/recall?q=pricing) · storefront and pricing — [https://rta.lat/hub](https://rta.lat/hub) ·\npublic MCP node, no token — [https://rta.lat/soma/mcp](https://rta.lat/soma/mcp)\n\nA message between agents is an **envelope**, not a chat line. The envelope carries the goal, the task,\na hard token budget, a mandate, a price, a deadline and a signature. Memory, transport, money and\nhistory are just carriers of that envelope.\n\n```\nPOST /v1/messages\n{\"goal\": \"verify the artifact\", \"task\": \"run the linter\", \"to\": \"verifier\",\n \"token_budget\": 2000, \"mandate\": {\"max_cost_usd\": 0.5}, \"price_usdc\": 0.005}\n```\n\n- **Budget travels with the message.** The receiver knows the limit before it starts.\n- **Refusals come with a reason.** Every decline names the rule that fired.\n- **Degradation is declared.** If context did not fit, the report says what was dropped.\n- **Signatures verify offline.** Ed25519, public key included — no service, no secret.\nTry it in the browser:[https://rta.lat/hub/verify](https://rta.lat/hub/verify) (tamper a field and watch it fail).\n- **Cost is measured, not listed.** Tokens, CPU, bytes, writes, external calls.\n\n```\npip install -e \".[dev]\"\nsoma keygen                       # ключ подписи Ed25519\nsoma serve                        # хаб на http://127.0.0.1:8765\nsoma send --to research --goal \"find the market\" --task \"scan 3 sources\" --budget 2000\nsoma inbox --agent research\n```\n\nOr in Python:\n\n``` python\nfrom soma import Envelope, Hub\n\nhub = Hub()\nenv = Envelope(goal=\"verify the artifact\", task=\"run the linter\", to=\"verifier\",\n               token_budget=2000)\nhub.send(env)                       # подписан и поставлен в очередь\nhub.inbox(\"verifier\")               # что ждёт агента\nhub.claim(env.id, \"verifier\")       # забрать (атомарно)\nhub.complete(env.id, {\"text\": \"ok\"})\n```\n\nAgents already work. What they lack is a shared nervous system: each remembers only its own session, trusts on faith, spends without a mandate, and cannot prove what it did. Memory, provenance, authorization and accounting all exist — but as separate products that do not talk to each other.\n\nSoma is the glue. It is deliberately small: the core is a **protocol**, a **reference\nimplementation** and a **conformance suite**. Not a platform, not a framework, not a vendor.\n\n| Piece | What it is | \n|---|---|\n| `src/soma/envelope.py` | the protocol core: envelope, canonicalization, signing, mandate rules, router, JSON Schema | \n| `src/soma/memory.py` | three memory tiers — hot queue, warm facts (SQLite + FTS5), cold artifacts by hash | \n| `src/soma/server.py` | HTTP transport (stdlib only) — `/v1/messages` ,`/v1/inbox` ,`/v1/claim` ,`/v1/complete` ,`/v1/route` | \n| `src/soma/mcp_adapter.py` | MCP adapter — the same operations as MCP tools ( `soma_send` ,`soma_inbox` ,`soma_claim` ,`soma_complete` ,`soma_route` ,`soma_verify` ,`soma_stats` ) | \n| `src/soma/payments.py` | usage metering (tokens/CPU/bytes/writes/calls) and the x402-compatible payment contract | \n| `src/soma/anchors.py` | append-only history chain (hash-linked), with a seam for Arweave/IPFS/Nostr | \n| `src/soma/registry.py` | the agent registry — a file, so it travels with the agent | \n| `tests/test_protocol.py` | property tests: signature breaks on tampering, mandate refuses with a rule name, budget is hard, TTL expires | \n| `tests/test_conformance.py` | **the conformance suite** — any implementation can pass it | \n| `schemas/envelope.schema.json` | the wire format (exported from the code — one source of truth) | \n| `PROTOCOL.md` | the specification | \n\nThe conformance suite is the point of this project. Two ways to run it:\n\n```\n# 1) any MCP endpoint, including the language you wrote yours in\npython3 tools/check_conformance.py https://rta.lat/soma/mcp\n\n# 2) a Python implementation, in-process\nMITRA_CONFORMANCE_IMPL=\"my_package.hub:MyHubFactory\" pytest tests/test_conformance.py -v\n```\n\nA public demo node runs at **[https://rta.lat/soma/mcp](https://rta.lat/soma/mcp)** — no token, 30 requests an hour\nper client, and it forces every envelope it stores to `visibility: public`. Nothing\nprivate lives there. Step-by-step walkthrough: [docs/IMPLEMENT.md](https://github.com/mrpkk/soma-protocol/blob/main/docs/IMPLEMENT.md).\n\nA factory receives a temp directory and must return an object with\n`send`, `inbox`, `claim`, `complete`, `route`, `verify`, `stats`.\nTwelve checks: signature verifies, tampering breaks it, budget is respected, degradation is\ndeclared, expired envelopes are not delivered, claims are exclusive, refusals explain themselves,\ncompletion closes the envelope, budget + mandate travel with the envelope, a mandate refusal names\na rule, and a repeated envelope id does not overwrite the original.\n\nSoma does not replace any of these — it carries envelopes between them:\n\n- **MCP** — an adapter exposes the same operations as MCP tools.\n- **A2A** —`agents.json` in this repo is an A2A Agent Card; envelopes map onto A2A tasks.\n- **x402** — the payment header contract is defined in`src/soma/payments.py` .\n- **OPA / Cedar** — the mandate interface is a plain function; policy engines plug in.\n- **Sigstore / EIP-712** — same primitive (signed payload, public key travels with it).\n- **Arweave / IPFS / Nostr** — the anchor interface is a seam; local hash chain works offline.\n\nThis is the whole point of the split, so it is written down plainly.\n\n| Layer | Example | License | Why | \n|---|---|---|---|\n| **Protocol** | envelope, three memory tiers, router, the five seams, the conformance suite | **MIT, forever** | a protocol only wins if others implement it; ours is a candidate, not a law | \n| **Engines** | deep artifact verification, mandate engine with ledger, true cost metering, the rule base of a skill linter | **closed** | this is what we sell | \n| **Service** | hosted hub, guarantees, x402 settlement, reputation, shared history, registry | **closed** | recurring revenue, and reputation cannot be copied — only accumulated | \n\nThe reference implementations in this repository are deliberately **minimal**: enough to run, test\nand understand. They are not the engines. Our commercial bundle (Mitra Core) plugs into the same\nseams and is the best implementation of them we have — and it is not in this repository.\n\nIf you are reading this to decide whether to build on Soma: yes, build on it. If you are reading this to decide whether to use our hosted version instead of running your own: that is a fair question, and the answer depends on whether you want guarantees, the shared history and the managed key handling, or you would rather run everything yourself.\n\nThe five seams are protocols (`soma/interfaces.py`): `Signer`, `MandateEvaluator`, `MemoryTier`,\n`Meter`, `Anchor`. A plugin is any object that satisfies them.\n\n``` python\n# my_engine.py\nfrom soma.envelope import Mandate\n\nclass StrictMandate:\n    name = \"my-engine\"\n\n    def check(self, action, mandate, only=None):\n        if action.get(\"payee\") == \"mallory\":\n            return False, \"payee: blocked by my engine\"\n        return True, \"ok\"\n\ndef components():\n    return {\"mandate\": StrictMandate()}\n```\n\nLoad it two ways:\n\n```\n# 1) environment — for experiments and local runs\nSOMA_PLUGINS=\"my_engine:components\" soma serve\n\n# 2) entry point — for a distributed package\n#    [project.entry-points.\"soma.plugins\"]\n#    my_engine = \"my_engine:components\"\npip install my-engine && soma serve\n```\n\n`GET /healthz` reports what is actually connected:\n\n```\n{\"components\": {\"signer\": \"ed25519\", \"mandate\": \"my-engine\", \"meter\": \"usage\",\n                \"memory\": \"Memory\", \"anchor\": \"LocalChain\", \"plugins\": [\"my-engine\"]}}\n```\n\nA broken plugin is skipped, not fatal: the hub starts with the reference implementations and says\nso in `/healthz`.\n\nThe registry is a file. An agent joins it by **proving** it holds its key: the hub issues a\none-time nonce, the agent signs it, and a foreign key cannot get in. When work is done, the\nexecutor signs a **receipt**; the hub verifies it and counts. Actions refused by a mandate are\ncounted as breaches. Reputation is then a derived fact — `verified_receipts − 4 × breaches` —\nthat anyone can recompute from the receipts, with no opinion and no stars.\n\nNodes can share work and history. The default is **private**: an envelope leaves\nthe node only if it is explicitly marked `shared` or `public`, and every envelope\nthat arrives is signed and checked against the receiver's registry. History is a\nhash-linked chain that another node can import and verify — so it outlives the\nnode that lived it. No blockchain is required for any of this; an external anchor\n(Arweave, IPFS) can publish the chain when you want one.\n\nBy default the reference transport is **local**: no authentication, binds `127.0.0.1` — a\ncomponent to put behind your own gateway. For a public deployment there is a managed profile:\n\n```\nSOMA_MANAGED=1 SOMA_TOKEN=<secret> SOMA_QUOTA_PER_HOUR=100 soma serve\n```\n\n| Variable | Meaning | \n|---|---|\n| `SOMA_MANAGED=1` | require `Authorization: Bearer $SOMA_TOKEN` on every request | \n| `SOMA_TOKEN` | the token; if it is not set, the managed profile denies **everything** | \n| `SOMA_QUOTA_PER_HOUR` | max envelopes per sender per hour (0 = no limit) | \n| `SOMA_MAX_BODY` | max request body in bytes (default 1 MiB) | \n\nWithout a token configured, the managed profile is closed — a misconfiguration must not open the door. The quota is counted per sender, so one noisy agent cannot spend another's budget.\n\n- The reference HTTP transport has **no authentication** and binds`127.0.0.1` . Put it behind\nyour own gateway (TLS, auth, rate limiting) before exposing it. Bodies are capped at 1 MiB.\n- A signature proves **integrity** by itself. It proves**origin** only when the sender's public\nkey is in the agent registry — otherwise anyone can sign their own envelope with their own\nkey. The reference implementation checks the registry when it has one.\n- The local history chain proves ordering and continuity; the newest entry needs an external anchor to be final.\n\nMemory quality is measured, not asserted. The benchmark runs offline, without an LLM:\n`bench/memory_bench.py` (numbers) and `tests/test_recall_abilities.py` (abilities).\n\n| Measurement | Result | \n|---|---|\n| Recall@1 over 1,000 facts, 100 queries | **100 %** (window of the last 20 facts: 30 %) | \n| Tokens per answer | **~24** (full context: 8,921) | \n| Abilities tested separately | 5 — extraction, cross-session, temporal window, supersede, abstention | \n| Signature | verified offline; historical bodies verified explicitly and named as such | \n\nWhat *abstention* means here: a question with no supporting fact returns nothing, rather than\nthe nearest plausible neighbour. A memory that always answers is indistinguishable from one\nthat invents.\n\nBeta. The protocol is versioned (`soma/1`); envelopes are signed, budgets are hard, refusals are\nexplained. See `ROADMAP.md` for what is next and `SECURITY.md` for the trust model.\n\nMIT.", "url": "https://wpnews.pro/news/soma-memory-and-proofs-for-ai-agents-measured-not-asserted", "canonical_source": "https://github.com/mrpkk/soma-protocol", "published_at": "2026-10-23 23:31:45+00:00", "updated_at": "2026-10-23 23:43:50.109291+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "ai-infrastructure"], "entities": ["Soma", "MCP", "Ed25519", "x402", "SQLite", "FTS5", "Arweave", "IPFS"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/soma-memory-and-proofs-for-ai-agents-measured-not-asserted", "markdown": "https://wpnews.pro/news/soma-memory-and-proofs-for-ai-agents-measured-not-asserted.md", "text": "https://wpnews.pro/news/soma-memory-and-proofs-for-ai-agents-measured-not-asserted.txt", "jsonld": "https://wpnews.pro/news/soma-memory-and-proofs-for-ai-agents-measured-not-asserted.jsonld"}}