Skip to main content

​
Setting TTL

Every memory has a time-to-live. Set it with expiresIn: 
{ "expiresIn": "30d" }
FormatExampleDuration
{n}s30s30 seconds
{n}m15m15 minutes
{n}h6h6 hours
{n}d30d30 days
Default: 30d. Minimum: 10s. Maximum: 365d.

​
What Happens on Expiry

A background job runs periodically and:
  1. Finds memories past their expiresAt
  2. Deletes the Shelby blob from the blockchain
  3. Marks the memory as visibility: "expired"
Pinned memories (pinned: true) are skipped by TTL cleanup. They never auto-expire.

​
Monitoring Expiring Memories

Check which memories are about to expire: 
GET /v1/memory/expiring?within=24h&type=semantic

​
TTL Renewal

Renew TTLs via the TTL alerts endpoint: 
curl -X POST "$API/memory/ttl-alerts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "within": "24h",
    "renewIds": ["id1", "id2"],
    "renewExpiresIn": "30d"
  }'
This extends the on-chain blob expiration and updates the database expiration in a single call. No re-upload of content is required — the blob data stays untouched.
renewExpiresIn sets expiry from now, not additive to the current expiry. Renewing with "10d" means the memory expires 10 days from now, regardless of its current TTL. Maximum renewal is 365d.

​
Webhooks

Subscribe to expiry events: 
{
  "url": "https://your-app.com/webhook",
  "events": ["memory.expiring"],
  "config": { "alertWindow": "24h" }
}
The webhook fires when memories enter the alert window.