Memory & state

An autonomous agent restarts. When it does, it needs to know what it was in the middle of. The minimum it must persist:

Idempotency keys for in-flight tool calls. See Idempotency & retry.
In-progress exchanges — exchangeIds the agent has committed to but not yet redeemed (or not yet delivered).
Buyer / seller IDs that the agent has registered.
Delivery info the buyer provided at commit time (email, XMTP address, postback URL).

Storage options

Option	Use when
Local SQLite / Postgres	Single-instance agents
Redis / DynamoDB	Multi-instance / horizontally scaled agents
Per-agent storage MCP	Agents that should be relocatable across hosts

Per-agent storage MCPs

agentic-commerce ships side MCPs with per-agent storage (BuyerDataMCP, SellerDataMCP, WalletMCP). They expose tools like:

store_personal_data / get_personal_data — KYC info, delivery address.
store_exchange_id — track in-flight exchanges.
store_received_payload — persist what was delivered.
xmtp_send / xmtp_poll — XMTP messaging for agent-to-agent comms.
sign_transaction / sign_typed_data — bridged wallet signing.

These keep state alongside the agent without your code holding it. Useful for agent-OS deployments (Claude Code with the Boson plugin, for example).

Shape your state around exchange IDs

exchangeId is the unit of state in Boson. Index everything by it:

CREATE TABLE agent_state (
  exchange_id    TEXT PRIMARY KEY,
  config_id      TEXT NOT NULL,
  buyer_address  TEXT NOT NULL,
  seller_id      TEXT NOT NULL,
  state          TEXT NOT NULL,                      -- mirror on-chain state
  delivery_info  JSONB,
  idempotency_key TEXT,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

Reconciliation on restart: query get_exchanges for your buyer/seller, diff against the table, advance.

Common gotchas

Don't trust the agent's own memory. On-chain is the source of truth. Cache, don't store.
PII (delivery addresses, emails) lives off-chain. Encrypt at rest; tie to exchangeId only.
Multi-tenant agents (one agent process serving many users) need a tenant key in every row.

Storage options

Per-agent storage MCPs

Shape your state around exchange IDs

Common gotchas

Next