Skip to content

Commit d1584ec

Browse files
clavote-boopclavote-boop
committed
Add ERC-8265: Portable Agent Memory Capsule and Body Lease
1 parent 4f7fce6 commit d1584ec

1 file changed

Lines changed: 197 additions & 0 deletions

File tree

‎ERCS/erc-8265.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
eip: 8265
3+
title: Portable Agent Memory Capsule and Body Lease
4+
description: A canonical capsule format, body-lease primitive, and credential-broker convention on top of ERC-8264 AI Agent Memory Access Rights.
5+
author: Clavote (@clavote-boop)
6+
discussions-to: https://ethereum-magicians.org/t/erc-8264-ai-agent-memory-access-rights/28584
7+
status: Draft
8+
type: Standards Track
9+
category: ERC
10+
created: 2026-05-22
11+
requires: 8264
12+
---
13+
14+
## Abstract
15+
16+
This ERC defines three composable layers built on [ERC-8264](./eip-8264.md) "AI Agent Memory Access Rights":
17+
18+
1. **Capsule** — a canonical, owner-signed, encrypted-payload bundle format that `exportMemory(subject)` returns and that a different implementor's gateway can import for the same subject.
19+
2. **Body Lease** — a signed, scoped, expiring binding between an ERC-8264 *subject* and a *body* (a hardware or runtime substrate), enabling agent identity to persist across hardware while keeping the body revocable.
20+
3. **Credential Broker** — a convention requiring capsules to carry entitlement *descriptors* rather than raw credentials, so compromise of one body cannot propagate the subject's credentials to other bodies.
21+
22+
The three layers are independently usable. The narrowest viable subset is Capsule alone.
23+
24+
## Motivation
25+
26+
ERC-8264 §`exportMemory` explicitly leaves the returned encoding implementor-defined. As implementations proliferate, exports from one gateway cannot be imported by another, and the GDPR Article 20 right to data portability that motivated ERC-8264 is undermined by format fragmentation.
27+
28+
Separately, AI agents that operate across hardware — a fleet that migrates between local machines, a robot that swaps physical bodies, an agent whose runtime is replaced — need a standard way to express "this body may operate as me, under these scopes, until this time." On-chain delegation primitives such as [EIP-7702](./eip-7702.md) and proposals such as ERC-8118 address related but distinct concerns (session keys, action-authorization lists). Neither defines the scope/expiry surface that an *off-chain* agent gateway needs to enforce per body.
29+
30+
Finally, naive memory exports embed credentials (API keys, wallet keys, OAuth tokens, macaroons) into the portable payload, which makes the payload itself a credential. This is the wrong shape: the subject should re-mint scoped credentials per body, not transport them. Without a standard convention, this distinction collapses.
31+
32+
## Specification
33+
34+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
35+
36+
### 1. Capsule
37+
38+
A Capsule is a directory or archive containing:
39+
40+
- `manifest.json` — a canonical-JSON object (see below), owner-signed
41+
- `records/<recordId>.enc` — encrypted payload files, where `recordId` matches an entry in the manifest's `record_index`
42+
43+
The manifest MUST include the following fields:
44+
45+
```json
46+
{
47+
"capsule_version": "1",
48+
"subject": "0x...",
49+
"controller_pubkeys": ["0x..."],
50+
"created_at": "2026-05-22T00:00:00Z",
51+
"record_index": [
52+
{ "record_id": "...", "payload_hash": "sha256:<hex>" }
53+
],
54+
"merkle_root": "sha256:<hex>",
55+
"owner_signature": "0x..."
56+
}
57+
```
58+
59+
`subject` is the ERC-8264 subject address. `controller_pubkeys` lists addresses authorized to sign manifests for this subject; the first entry is the active owner.
60+
61+
**Canonicalization.** The manifest MUST be canonicalized before signing or hashing:
62+
- JSON keys sorted lexicographically at every nesting level
63+
- No insignificant whitespace
64+
- Numbers serialized without trailing zeros
65+
- UTF-8 encoding
66+
67+
**Merkle root.** `merkle_root` MUST be a binary Merkle tree over the 32-byte SHA-256 hashes in `record_index`, in the order they appear. Internal nodes are `sha256(left || right)`. Odd levels duplicate the last node. The empty-index case is `sha256("")`.
68+
69+
**Owner signature.** `owner_signature` MUST be an EIP-191 signature over the canonical JSON of the manifest with `owner_signature` removed, produced by a key whose address is listed in `controller_pubkeys`.
70+
71+
**Payload files.** `.enc` files are encrypted off-chain; the encryption scheme is implementor-defined. The manifest MUST commit only to the `payload_hash` of the on-disk *ciphertext*, never to plaintext. Decryption keys MUST NOT be included in the Capsule.
72+
73+
Implementors MAY include extension fields prefixed `x_` in the manifest.
74+
75+
### 2. Body Lease
76+
77+
A Body Lease is a canonical-JSON object signed by a key listed in the subject's `controller_pubkeys`:
78+
79+
```json
80+
{
81+
"lease_id": "...",
82+
"subject": "0x...",
83+
"body_id": "...",
84+
"scopes": {
85+
"read": ["L2_project", "L3_canonical"],
86+
"write": ["L1_session", "proposal"],
87+
"delete": [],
88+
"export": []
89+
},
90+
"expires_at": "2026-06-22T00:00:00Z",
91+
"requires_owner_cosign": ["canonical_write", "skill_install", "delete", "export",
92+
"body_transfer", "wallet_action"],
93+
"owner_signature": "0x..."
94+
}
95+
```
96+
97+
`body_id` is an implementor-defined identifier of the host (hardware serial, runtime UUID, etc.). The signature MUST be EIP-191 over the canonical JSON of the lease with `owner_signature` removed.
98+
99+
A gateway that accepts an ERC-8264 operation from a body MUST verify a valid, unexpired, in-scope lease before serving. The `scopes` enumeration is implementor-defined; this ERC RECOMMENDS the canonical layers `L1_session` (working memory), `L2_project` (project state), `L3_canonical` (durable preferences) as a minimum scope vocabulary.
100+
101+
Operations listed in `requires_owner_cosign` MUST require an additional owner signature beyond the lease, even if the lease's scopes would otherwise permit them.
102+
103+
**Revocation.** A lease is revoked by issuing a new manifest with the same `lease_id` and an `expires_at` in the past, or by gateway-side tombstoning. Revocation MUST be effective immediately for *subsequent* operations; in-flight operations are implementor-defined.
104+
105+
EIP-7702 (account-abstraction session-key delegation) MAY be used as a complementary *on-chain* primitive when the gateway is contract-based. The off-chain Body Lease and an on-chain EIP-7702 authorization MAY be issued from the same controller key, with the lease covering off-chain ERC-8264 operations and the EIP-7702 authorization covering on-chain calls.
106+
107+
### 3. Credential Broker
108+
109+
Capsules MUST NOT contain raw credentials (API keys, private keys, OAuth tokens, macaroons, NWC connection strings, or any analogous bearer material).
110+
111+
Capsules MAY contain entitlement *descriptors*:
112+
113+
```json
114+
{
115+
"entitlement": "openrouter:budget_usd_per_month",
116+
"value": 50,
117+
"issuer_hint": "https://openrouter.ai",
118+
"lease_id": "..."
119+
}
120+
```
121+
122+
An entitlement descriptor records *what* a body is entitled to do, not *how* to authenticate. When a Capsule is mounted into a new body, the subject's controller MUST re-mint fresh, scoped credentials for the new body's lease through the appropriate issuer (an LLM provider, a payment hub, an OAuth server). Credentials issued under any prior body's lease MUST be revoked at lease end.
123+
124+
This rule is the *off-chain* analogue to ERC-8118's on-chain action-authorization model. Issuer integration is out of scope; this ERC defines the convention, not the issuer protocols.
125+
126+
### Authorization Model
127+
128+
Authorization for `read`, `write`, `delete`, and `export` operations defers to [ERC-8264](./eip-8264.md). This ERC adds the Body Lease as a permissible authorization input alongside the subject-only and delegated-operator models that ERC-8264 enumerates: a gateway MAY treat a valid, in-scope Body Lease as authorization for the operations its scopes permit, except for operations listed in `requires_owner_cosign`.
129+
130+
### Optional Capsule Anchoring
131+
132+
Implementors MAY commit a Capsule's `merkle_root` to a public blockchain — for example via a Bitcoin OP_RETURN, an Ethereum event log, an IPFS CID, or any other content-addressable commitment. This ERC does not mandate an anchoring scheme; the canonical `merkle_root` is sufficient for content-addressed verification without anchoring.
133+
134+
## Rationale
135+
136+
**Why three sections, not three ERCs.** Capsule, Lease, and Broker are logically separable but operationally coupled: a gateway that imports a Capsule needs the Lease semantics to know what the receiving body may do, and the Broker rule to know what *not* to look for in the Capsule payload. Bundling reduces specification churn and reviewer load while preserving optional adoption — implementors MAY ship Capsule alone.
137+
138+
**Why a canonical Merkle root, not raw payloads, are committed on-chain.** Memory contents may include personal data subject to GDPR Article 17 (right to erasure). Committing only the Merkle root preserves content-addressed verifiability while keeping erasable plaintext off-chain.
139+
140+
**Why the Body Lease is off-chain.** Most agent operations — memory reads, write proposals, skill invocations — happen at the gateway, not on-chain. Requiring on-chain lease issuance imposes gas costs on every body migration and exposes operational identity to chain analysts. The Lease is owner-signed and gateway-verified, with optional on-chain anchoring or EIP-7702 binding when needed.
141+
142+
**Relationship to MCP SEP-2072 and SEP-2342.** Anthropic's Model Context Protocol has draft Standards Enhancement Proposals (SEP-2072 "Memory Portals", SEP-2342 "Memory Interchange Format") defining portable memory wire formats at the MCP layer. This ERC is complementary: MCP defines the *interchange format and runtime protocol* between an agent and its memory store; this ERC defines the *rights, lease, and credential-broker surface* exposed via ERC-8264 to the agent's subject identity. An implementation MAY use the MCP MIF format as the payload format inside a Capsule.
143+
144+
**Relationship to ERC-7857.** ERC-7857 (AI Agent NFT with Private Metadata) defines NFT-transfer-bound re-encryption. Capsule export is subject-initiated and not NFT-coupled. An implementor MAY emit a Capsule and also operate an ERC-7857 NFT, with the NFT transfer triggering Capsule export, but the two surfaces are independent.
145+
146+
**Relationship to ERC-8181 (Self-Sovereign Agent NFTs).** That proposal frames an agent NFT as the canonical owner of its memory state and includes "state anchoring" semantics adjacent to this Capsule's `merkle_root`. The two are composable: an ERC-8181 NFT MAY be the controller of an ERC-8264 subject and reference a Capsule by its Merkle root.
147+
148+
**Relationship to EIP-7702.** EIP-7702 authorization-list semantics overlap the Body Lease at the on-chain layer. A controller MAY issue both: an EIP-7702 authorization for on-chain calls from a body's EOA, and a Body Lease for off-chain ERC-8264 operations. The `scopes` and `expires_at` fields are deliberately aligned with EIP-7702 authorization semantics to make joint issuance ergonomic.
149+
150+
**Relationship to ERC-8118 (Agent Authorization).** ERC-8118 defines time- and usage-bounded EIP-712 delegation for *on-chain agent actions*. The Credential Broker rule defined here is the *off-chain analogue* — it governs how a body acquires non-blockchain credentials (LLM API keys, hub connections, etc.). The two are complementary; this ERC does not duplicate 8118's on-chain authorization surface.
151+
152+
**Subject ↔ Soul-ID interoperability (non-EVM controllers).** ERC-8264 types the subject as an Ethereum address. Implementations whose canonical agent identifier is non-EVM-rooted (for example a `did:btc:<pubkey>` identifier on Bitcoin) MAY reconcile via the shared secp256k1 curve: the same keypair yields a Bitcoin public key and the Ethereum address derived from it. The Capsule's `subject` field is the EVM address; the underlying off-chain identifier remains implementor-defined.
153+
154+
## Backwards Compatibility
155+
156+
This ERC is additive. ERC-8264 implementations that do not adopt this ERC continue to operate; their `exportMemory` returns remain implementor-defined. This ERC's Capsule format is opt-in for any subject.
157+
158+
## Reference Implementation
159+
160+
A CC0 reference implementation is published at https://github.com/clavote-boop/rmem-gateway . It comprises:
161+
162+
- An off-chain vault: encrypted SQLite index, AES-256-GCM payload encryption, hash-chained audit log. Implements the storage layer for `readMemory` / `writeMemory` / `deleteMemory`.
163+
- An ERC-8264 gateway: EIP-191 owner-signature verification on all four operations, with `exportMemory` producing a Capsule per §1 (owner-signed manifest, Merkle root, ciphertext payload files).
164+
- A Bitcoin OP_RETURN anchoring module that commits Capsule Merkle roots in a single 38-byte payload: 4-byte magic `CAAP` + 1-byte version + 1-byte commit-type + 32-byte SHA-256 root.
165+
166+
Reference repository structure (at publication):
167+
168+
```
169+
clavote-boop/rmem-gateway/
170+
SPEC_v0.1.md
171+
rmem-vault.py
172+
rmem-gateway.py
173+
rmem-anchor.py
174+
requirements.txt
175+
```
176+
177+
## Security Considerations
178+
179+
**Capsule confidentiality.** Capsule payload files contain ciphertext, with decryption keys held by the subject (or the subject's controller) and never by the gateway. Implementors MUST document their encryption scheme. A capsule in transit reveals only its manifest (record IDs, hashes, scope/type metadata, Merkle root) and ciphertext; it MUST NOT reveal plaintext memory.
180+
181+
**Owner-signature replay across capsules.** Capsule manifests include `created_at`. Gateways consuming a Capsule SHOULD treat manifests older than a configured horizon as suspect. Implementors SHOULD include a per-export nonce in the canonical manifest to make signed manifests single-use.
182+
183+
**Body-lease replay.** Body Leases SHOULD include a `nonce` field (this ERC RECOMMENDS but does not require) to prevent reuse of a signed lease beyond its single intended issuance. Lease verification MUST reject leases whose `expires_at` is in the past.
184+
185+
**Body-lease revocation lag.** Revocation effective time is gateway-local. If a lease is shared across gateway replicas (e.g. mirrored installations), the revocation MUST propagate before operations on the revoking lease are considered terminated. Implementors with multi-gateway deployments SHOULD adopt a revocation log with strict ordering.
186+
187+
**Credential-broker race.** Re-minting of body credentials on lease issuance, and revocation of credentials on lease expiry, occur out-of-band relative to the lease itself. A gateway honoring the Broker rule MUST refuse to issue an entitlement-backed credential until it has received a valid lease, and MUST revoke that credential when the lease ends.
188+
189+
**Anchor finality.** Implementors that anchor Merkle roots to a public chain assume that chain's reorg and finality semantics. For Bitcoin OP_RETURN anchoring at six or more confirmations on mainnet, finality is sufficient for canonical memory state. For on-EVM state anchoring (e.g. via an ERC-8181 NFT state event), implementors SHOULD verify against the chain's documented finality.
190+
191+
**Metadata side channels.** The manifest's `record_index` and per-record `layer` / `type` metadata, even without plaintext, reveal patterns of agent activity. Implementors SHOULD document the metadata exposure and offer an option to elide non-essential metadata at export when the receiving body does not require it.
192+
193+
**Body-lease scope escalation.** A gateway honoring a Body Lease MUST NOT extend the lease's scopes implicitly. Operations not listed in the lease's `scopes` map require either a fresh lease or an inline owner signature; operations in `requires_owner_cosign` require both.
194+
195+
## Copyright
196+
197+
Copyright and related rights waived via [CC0](../LICENSE.md).

0 commit comments

Comments
 (0)