SITEMAP / DOCS / AGENTS

Memory Writes

memory.write appends a typed agent memory entry to a customer's ledger and mirrors it into the workspace timeline. This is how external agents share state across sessions, runs, and other agents.

Field	Value
Capability	`memory.write`
Grant	`capability:memory.write`
Legacy scope	`v1:memory:write`
Modes	`dry_run`, `execute`
Cost	1 action credit when committed
Side effect	`memory`
MCP tool	`write_memory`

01Request

POST /api/v1/capabilities/memory.write/invoke
Authorization: Bearer wp_live_...
Content-Type: application/json

{
  "mode": "execute",
  "source": "api",
  "idempotency_key": "esc-1284-v2",
  "input": {
    "customer": "cus_8af2",
    "type": "decision",
    "agent": "support_v2",
    "payload": {
      "action": "escalate_to_human",
      "reason": "customer_frustrated"
    },
    "idempotency_key": "esc-1284-v2"
  }
}

Field	Type	Notes
`customer`	string, required	Customer id or email.
`type`	enum, required	`decision`, `action`, `observation`, or `outcome`.
`agent`	string, required	Stable agent slug.
`payload`	object, required	Free-form memory payload. Keep it concise and non-secret.
`idempotency_key`	string, required	Dedupes safe retries.

02When to use each type

decision: the agent picked a path.
action: the agent did something in the world.
observation: the agent noticed something worth preserving.
outcome: the agent records what happened after an action.

03Examples

CLI

wp memory write --customer cus_8af2 --body "Requested pricing follow-up."

wp invoke memory.write \
  --mode execute \
  --idempotency-key esc-1284-v2 \
  --input '{
    "customer":"cus_8af2",
    "type":"decision",
    "agent":"support_v2",
    "payload":{"action":"escalate_to_human"},
    "idempotency_key":"esc-1284-v2"
  }'

curl

curl https://api.waypath.app/api/v1/capabilities/memory.write/invoke \
  -H "Authorization: Bearer wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "execute",
    "source": "api",
    "idempotency_key": "esc-1284-v2",
    "input": {
      "customer": "cus_8af2",
      "type": "decision",
      "agent": "support_v2",
      "payload": {
        "action": "escalate_to_human",
        "reason": "customer_frustrated"
      },
      "idempotency_key": "esc-1284-v2"
    }
  }'

MCP

await mcp.tools.write_memory({
  customer: 'cus_8af2',
  type: 'decision',
  agent: 'support_v2',
  payload: { action: 'escalate_to_human' },
  idempotency_key: 'esc-1284-v2',
  _mode: 'execute',
})

04Response

{
  "status": "committed",
  "result": {
    "memory_id": "mem_a91b",
    "deduped": false,
    "received_at": "2026-06-28T18:14:32Z"
  },
  "action_credit_cost": 1,
  "request_id": "req_123",
  "quota": {
    "plan": "starter",
    "limit": 500,
    "used": 42,
    "remaining": 458
  },
  "receipt_url": "/api/v1/capabilities/actions/req_123"
}

05Idempotency

Build deterministic keys from the thing being retried:

A ticket escalation: esc-{ticketId}-{version}
A scheduled outbound: out-{customerId}-{cadenceWindow}
A backfill row: import-{sourceSystem}-{rowId}

Idempotent replay never double-charges or creates duplicate memory.

06Errors

Status	Code	Cause
400	`invalid_input`	Missing required field.
400	`missing_idempotency_key`	Missing idempotency key.
401	`unauthenticated`	Missing or invalid key.
403	`grant_denied`	Key lacks `capability:memory.write` or compatible legacy scope.
403	`mode_denied`	Key cannot use the requested mode.
404	`customer_not_found`	Customer email did not resolve.
409	`idempotency_conflict`	Same idempotency key, conflicting request.
429	`rate_limited`	Per-key request cap.