Memory Drops

A memory drop is a temporary write grant. The token holder can add memory without receiving the owner's session or API key.

Minting

POST /memory-drops
Authorization: Bearer <session token>

{ "expiresInMinutes": 15, "maxWrites": 1 }

{
  "id": "...",
  "url": "https://api.toda.io/memory-drops/toda_drop_c7e2...",
  "expiresAt": "2026-07-08T12:15:00.000Z",
  "maxWrites": 1,
  "remainingWrites": 1,
  "revokedPreviousCount": 0
}

Parameter	Default	Range
expiresInMinutes	15	1 to 1440
maxWrites	1	1 to 5

Minting a drop revokes every other active drop for the owner.

Token storage

Drop tokens contain 32 random bytes and use the toda_drop_ prefix. Only the SHA-256 hash is stored.

Consumption

POST /memory-drops/toda_drop_c7e2...
Content-Type: application/json

{
  "content": "The Pro tier is priced at $29 per month.",
  "source": "session-memory",
  "metadata": { "kind": "decision" }
}

Field	Requirement
content	Required, 1 to 10,000 characters
source	Optional, 1 to 80 characters
metadata	Optional object

A valid request atomically consumes one write and adds the memory through the standard write path.

{
  "ok": true,
  "memoryId": "...",
  "anchored": false,
  "leafHash": "9ab3...",
  "createdAt": "2026-07-08T12:03:41.000Z"
}

anchored: false means the memory is stored but has not been included in an anchor yet.

Unknown, expired, revoked, and fully consumed tokens return the same 404 response.

Management

GET  /memory-drops/:id/status
POST /memory-drops/:id/revoke

Both routes require the owner's session.

Permissions

The token holder can add up to maxWrites memories. It cannot read, modify, or delete memory. It cannot create another drop or access wallet credentials.

Security

A stolen drop can insert content into the owner's memory. That content may later be included in an agent case.

Use a source identifier for every drop and keep maxWrites at 1 unless multiple writes are required. Treat drop content as untrusted input.

Comparison

	Agent case	Memory drop
Direction	Read	Write
Method	GET	POST
Default limit	1 read	1 write
Default expiry	15 minutes	15 minutes
Active grants per owner	1	1