APIUpdated 2026-05-30

Agent Memory API

REST routes for agent events, context bundles, handoffs, and handoff resume.

Applies to: RetainDB API v1

Base URL:

text

https://api.retaindb.com

All routes require Authorization: Bearer $RETAINDB_API_KEY or X-API-Key.

Use this API when an external agent runtime needs to record decisions, retrieve task memory, or hand work to another agent. Use Company Brain API when the agent needs indexed company knowledge from sources.

POST /v1/agent/memory/events

Record an agent work event.

bash

curl -X POST "https://api.retaindb.com/v1/agent/memory/events" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "app",
    "agent_id": "planner",
    "task_id": "checkout-redesign",
    "type": "decision",
    "summary": "Use hosted checkout in v1.",
    "details": {
      "reason": "Lower implementation risk."
    },
    "salience": 0.9,
    "write_mode": "async"
  }'

POST /v1/agent/memory/context

Return an agent-ready context bundle for a task.

bash

curl -X POST "https://api.retaindb.com/v1/agent/memory/context" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "app",
    "agent_id": "builder",
    "task_id": "checkout-redesign",
    "query": "What should I know before implementation?",
    "top_k": 8
  }'

POST /v1/agent/memory/handoffs

Create a handoff packet from one agent to another.

bash

curl -X POST "https://api.retaindb.com/v1/agent/memory/handoffs" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "app",
    "from_agent_id": "planner",
    "to_agent_id": "builder",
    "task_id": "checkout-redesign",
    "summary": "Build hosted checkout.",
    "context": "Use hosted checkout. Keep custom payment UI out of v1."
  }'

GET /v1/agent/memory/handoffs/:handoffId

Fetch a handoff packet.

bash

curl "https://api.retaindb.com/v1/agent/memory/handoffs/handoff_123" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

POST /v1/agent/memory/handoffs/:handoffId/resume

Resume or fork a handoff into a new session.

bash

curl -X POST "https://api.retaindb.com/v1/agent/memory/handoffs/handoff_123/resume" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "builder-session-001"
  }'

Response Shape

Successful responses include the created or retrieved event, context, or handoff fields plus trace metadata when available.

Example event response:

json

{
  "success": true,
  "event_id": "evt_...",
  "memory_job_id": "job_...",
  "trace_id": "trc_..."
}

Errors use RetainDB's standard error envelope:

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key or Authorization header"
  },
  "trace_id": "..."
}

Idempotency

For retryable event and handoff writes, send an Idempotency-Key header from your job or agent runtime. Use a deterministic value such as ${taskId}:${agentId}:${eventId}.

Scope Isolation

Always send the same project, agent_id, and task_id for a shared task. Add user_id and session_id when the task is also tied to a specific user or run.

Next: SDK Agent Task API or MCP Setup.

Was this page useful?

Your feedback helps us make the product easier to ship with.