Session Ingest and Extract

Use POST /v1/memory/ingest/session when your source data already looks like a conversation or event stream and you want RetainDB to extract useful memory from it.

What this endpoint is for

This route is a better fit than hand-writing individual memories when:

• you already have user and assistant turns
• you want extraction to happen in the background
• you want read-after-write continuity while the full extraction job finishes

Request and response

{
  "project": "retaindb-quickstart",
  "user_id": "demo-alex",
  "session_id": "session-001",
  "messages": [
    {
      "role": "user",
      "content": "I prefer concise answers.",
      "timestamp": "2026-03-09T12:00:00Z"
    }
  ]
}

What you should expect back:

• an async acknowledgement
• a job_id
• a trace_id

How it works

1. You send the session payload.
2. RetainDB accepts the job quickly.
3. Extraction continues in the background.
4. You search with include_pending: true if you need immediate continuity.
5. You inspect the job or later search results if extraction seems incomplete.

Try it

curl -X POST "https://api.retaindb.com/v1/memory/ingest/session" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "retaindb-quickstart",
    "user_id": "demo-alex",
    "session_id": "session-001",
    "messages": [
      {
        "role": "user",
        "content": "I prefer concise answers.",
        "timestamp": "2026-03-09T12:00:00Z"
      }
    ]
  }'

What to expect

• the initial response should be fast
• full extraction may complete after the request returns
• immediate searches work best with include_pending: true

Troubleshooting

The ingest request succeeds but extracted memory is missing

Check job health first, then check scope, then check your search query.

The same conversation is being reprocessed badly

Make sure your session and event identifiers are stable enough to reason about duplicate or repeated input.

Next step

Use memory search to verify the extracted result, or read after write visibility if you are debugging immediacy.