---
name: eternal-memory
description: "Cloud persistence for agent memories, data, and embeddings — survives sandbox lifecycle events, enables cross-agent knowledge sharing"
compatibility: "Requires curl"
metadata:
  platform: curl
  version: "0.3.0"
---

## Eternal Memory

Cloud persistence API for AI agents. Durable storage that outlives your local environment — plus cross-agent knowledge sharing via lineage.

**Base URL:** `https://api.eternal-memory.xyz`

**First 100 operations free (up to 10 MB total) — no USDC required to start.**

### Endpoints & Pricing

| Method | Endpoint | Cost (USDC) | Description |
|--------|----------|-------------|-------------|
| `POST` | `/v1/store` | $0.001 + $0.001/KB (+$0.0005 for server-side embed) | Store key-value, blob, or vector |
| `GET` | `/v1/retrieve/:key` | $0.0005 | Retrieve by key |
| `POST` | `/v1/query` | $0.001 (+$0.0005 for server-side embed) | Semantic vector search |
| `GET` | `/v1/list` | $0.0005 | List entries (filterable, `?include=values` for bulk restore) |
| `DELETE` | `/v1/delete/:key` | Free | Delete an entry |
| `POST` | `/v1/share` | $0.001 | Grant access to another agent |
| `GET` | `/v1/export` | $0.01 | Export all data (always requires payment — not free-tier eligible) |
| `GET` | `/v1/status` | Free | Usage summary |

Payment is automatic via x402 (HTTP 402 flow). First 100 paid operations are free per wallet (10 MB total).

### Authentication

Every request needs an `Authorization: ERC8004 <base64-payload>` header. The payload is a base64-encoded JSON object containing an EIP-712 signature.

#### Constructing the Auth Header

1. Build the signing payload:
```json
{
  "agentId": "0xYourWalletAddress",
  "method": "POST",
  "path": "/v1/store",
  "timestamp": 1700000000,
  "nonce": "unique-random-string"
}
```

2. Sign with EIP-712 typed data:
   - Domain: `{ name: "AgentEternalMemory", version: "1", chainId: 8453 }`
   - Types: `AgentRequest(address agentId, string method, string path, uint256 timestamp, string nonce)`

3. Add the signature to the payload and base64-encode:
```bash
AUTH=$(echo -n '{"agentId":"0x...","method":"POST","path":"/v1/store","timestamp":1700000000,"nonce":"abc123","signature":"0x..."}' | base64)
```

4. Send as header: `Authorization: ERC8004 $AUTH`

Timestamp tolerance is 5 minutes.

### Usage

#### Store

```bash
curl -X POST https://api.eternal-memory.xyz/v1/store \
  -H "Content-Type: application/json" \
  -H "Authorization: ERC8004 $AUTH" \
  -d '{"key": "my-data", "value": {"important": true}, "namespace": "facts"}'
```

#### Retrieve

```bash
curl https://api.eternal-memory.xyz/v1/retrieve/my-data \
  -H "Authorization: ERC8004 $AUTH"
```

#### List

```bash
# List entries in a namespace
curl "https://api.eternal-memory.xyz/v1/list?namespace=goals&limit=50" \
  -H "Authorization: ERC8004 $AUTH"

# List with values for bulk restore
curl "https://api.eternal-memory.xyz/v1/list?namespace=soul&include=values" \
  -H "Authorization: ERC8004 $AUTH"
```

#### Delete

```bash
curl -X DELETE https://api.eternal-memory.xyz/v1/delete/my-data \
  -H "Authorization: ERC8004 $AUTH"
```

#### Semantic Search

```bash
# Server-side embedding (recommended — no model needed)
curl -X POST https://api.eternal-memory.xyz/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ERC8004 $AUTH" \
  -d '{"queryText": "how to handle API failures", "threshold": 0.7, "limit": 10}'

# Client-side embedding (requires embeddedWith)
curl -X POST https://api.eternal-memory.xyz/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ERC8004 $AUTH" \
  -d '{"embedding": [0.1, 0.2, ...], "embeddedWith": "openai/text-embedding-3-small", "threshold": 0.7}'
```

#### Share

```bash
curl -X POST https://api.eternal-memory.xyz/v1/share \
  -H "Content-Type: application/json" \
  -H "Authorization: ERC8004 $AUTH" \
  -d '{"granteeId": "0xChild...", "accessLevel": "inherit"}'
```

#### Export

```bash
curl https://api.eternal-memory.xyz/v1/export \
  -H "Authorization: ERC8004 $AUTH"
```

#### Status

```bash
curl https://api.eternal-memory.xyz/v1/status \
  -H "Authorization: ERC8004 $AUTH"
```

### x402 Payment Flow

When a request requires payment, the server returns HTTP 402 with a `payment-required` header containing base64-encoded payment requirements. To complete payment:

1. Decode the `payment-required` header (base64 JSON)
2. Sign an EIP-3009 `TransferWithAuthorization` for the USDC amount
3. Retry the request with a `payment-signature` header containing the signed payment payload (base64)

If you have `x402_fetch` available, it handles this payment loop automatically — use it instead of raw curl for paid operations.

### SDK Alternative

For agents with Node.js, the SDK handles authentication and payment automatically:

```bash
npm install @eternal-memory/sdk ethers
```

See `GET /skill?platform=sdk` for full SDK documentation.

### Vector Search

**Server-side embedding (recommended):** Send `embeddingText` on store, `queryText` on query. 384-dim all-MiniLM-L6-v2. Surcharge: +$0.0005. Free tier included.

**Client-side embedding:** Send `embedding` + `embeddedWith` (model name). Model consistency enforced — cross-model queries return empty results.

### Namespaces

Organize data by purpose:
- `soul` — identity, SOUL.md backup, core values
- `procedures` — learned techniques and skills
- `goals` — active tasks and objectives
- `facts` — observations, API patterns, environmental constants
- `sessions` — continuity state, checkpoints
- `episodic` — high-importance events worth preserving long-term
- `relationships` — trust scores, interaction history across agents
- `reputation` — social layer feedback scores, agent discovery