Per-Record TTL

What you'll learn

How TTL works under the hood, the sweeper cycle, and patterns for using TTL correctly.

How TTL works

When you write a record with ttl_ms: 3600000, the engine injects _expires_at_ms into the payload before storing:

{
  "session_token": "tok_xyz",
  "_expires_at_ms": 1751903600000
}

A background sweeper runs every 60 seconds. It scans the strand, finds records where current_time_ms > _expires_at_ms, and writes tombstones for them. The sweeper holds a Weak<AgentRegistry> reference — it never prevents the process from shutting down cleanly.

Good use cases for TTL

Bad use cases for TTL

Do not use TTL for records you want to audit later. Once the tombstone is written, the original payload is logically hidden (though still on disk). For compliance data, keep records permanently and use soft-delete only when legally required.

Check if a record has expired

# Will return 404 if TTL has passed and sweeper has run
curl -s http://localhost:7475/v1/agents/sessions/records/<HASH> \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"

Write a short-TTL record and watch it expire

`bash # Expires in 65 seconds curl -s -X POST http://localhost:7475/v1/agents/sessions/write \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"payload": {"token": "short_lived"}, "ttl_ms": 65000}' \ | python3 -m json.tool

# Save the content_hash, wait 70 seconds, then try to fetch it sleep 70 curl -s http://localhost:7475/v1/agents/sessions/records/<HASH> \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" # → 404 Not Found `

Challenge

Create a password_reset_tokens agent. Write a token with 15-minute TTL. Verify it is readable immediately. Verify it returns 404 after the sweeper runs.

---