# Memory API reference

[Product page](https://bmdpat.com/memory) | [OpenAPI JSON](https://bmdpat.com/openapi.json) | [For agents](https://bmdpat.com/developers)

## Before calling

Store JSON by namespace and key. Recall reads exact keys or lists up to 100 entries, newest update first. There is no semantic search or pagination.

Use a provisioned x-api-key or an authorized x402 payment. A nonempty API key takes precedence. This API does not issue keys. API-key and wallet identities have separate storage scopes; keep wallet address casing consistent.

Payment needs a funded wallet and a client that can sign the requested authorization. Read the 402 PAYMENT-REQUIRED header (base64 JSON), inspect the amount, network, asset and recipient, then send PAYMENT-SIGNATURE. X-PAYMENT is a legacy alias for the same V2 payload. Do not send conflicting aliases.

Payment settles before the operation runs. PAYMENT-RESPONSE is a payment receipt, not proof that memory was stored or returned. Confirmation time varies. A server error can occur after payment; automatic fulfillment recovery and refunds are not provided by this API.

On 409, do not submit another payment. Keep the transaction and network fields when present, check the transaction outcome, and contact pat@bmdpat.com if it remains unknown. A missing explorer result does not prove failure. Do not automatically repay after a timeout or 500 either.

Namespace accepts 1 to 128 UTF-16 code units. A required key accepts 1 to 256. A stored value can be any JSON value, including null, up to 10240 UTF-8 bytes after JSON.stringify. Extra properties are ignored.

For recall, omit key to list entries. An empty or non-string key also selects listing for compatibility. A missing exact key returns memory: null with HTTP 200.

For forget, use namespace and key query parameters. Legacy JSON bodies also work when neither query parameter is present. If either query parameter is present, both must be valid; values are not filled from the body. Deleting a missing key still returns forgotten: true.

These handlers do not enforce a published requests-per-minute allowance. No rate-limit headers or 429 contract are promised. Limit your own concurrency and stop payment retries when the outcome is unknown.

## Endpoints

### POST /api/memory/store

Store or update a memory entry by namespace + key. $0.001 per paid call, USDC on eip155:8453.

JSON example:

```json
{ "namespace": "my-agent", "key": "user-pref", "value": { "theme": "dark" } }
```

### POST /api/memory/recall

Recall a specific key or up to 100 entries, newest update first. $0.001 per paid call, USDC on eip155:8453.

JSON example:

```json
{ "namespace": "my-agent", "key": "user-pref" }
```

### DELETE /api/memory/forget

Delete a specific memory entry. $0.001 per paid call, USDC on eip155:8453.

JSON example:

```json
{ "namespace": "my-agent", "key": "user-pref" }
```

### GET /api/memory/stats

Get total memory count and active namespaces. $0.001 per paid call, USDC on eip155:8453.

No request body.

For DELETE, prefer URL query parameters: /api/memory/forget?namespace=my-agent&key=user-pref. The JSON example is the legacy alternative.

## Inspect requirements without paying

This request supplies no key or payment signature. It asks for the current payment requirements; it does not purchase memory.

```sh
curl -i https://bmdpat.com/api/memory/stats
```

Expected when the service is configured: HTTP 402 with PAYMENT-REQUIRED. Inspect the actual response. A server error is not permission to pay.

## Responses

200 carries the operation result. 400 means invalid input or payment data. 401 means rejected credentials. 402 carries payment requirements. 405 means wrong method. 409 means an uncertain payment; stop and reconcile it. 500 can occur after settlement. See OpenAPI for response shapes.