Memory Write and Bulk Write

Use POST /v1/memory to write a single memory and POST /v1/memory/bulk when you already know you need multiple writes in one call.

When to use each route

Use POST /v1/memory when:

• you are adding one fact or preference at a time
• you are starting with a simple integration
• you want the easiest possible first write path

Use POST /v1/memory/bulk when:

• you are ingesting several related memories together
• you want fewer round trips
• you are backfilling or importing known data

Single write request

{
  "project": "retaindb-quickstart",
  "user_id": "demo-alex",
  "session_id": "session-001",
  "content": "Alex prefers concise, direct answers.",
  "memory_type": "preference",
  "write_mode": "async"
}

Bulk write request

{
  "project": "retaindb-quickstart",
  "memories": [
    {
      "user_id": "demo-alex",
      "session_id": "session-001",
      "content": "Alex prefers concise, direct answers.",
      "memory_type": "preference"
    },
    {
      "user_id": "demo-alex",
      "session_id": "session-001",
      "content": "Alex is evaluating an annual plan.",
      "memory_type": "event"
    }
  ],
  "write_mode": "async"
}

Defaults that work well

• keep write_mode async unless you have a strong reason not to
• search with include_pending: true right after writes
• keep identifiers stable and application-owned

Try it

curl -X POST "https://api.retaindb.com/v1/memory" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "retaindb-quickstart",
    "user_id": "demo-alex",
    "session_id": "session-001",
    "content": "Alex prefers concise, direct answers.",
    "memory_type": "preference",
    "write_mode": "async"
  }'

Two mistakes that make writes look broken

Writing with unstable identifiers

If user_id changes between requests, the write may succeed but later searches will look empty.

Searching immediately without pending overlay

Async writes are the recommended default. Search with include_pending: true if you want immediate continuity.

Security notes

Never let the caller invent tenant scope. Authenticate the caller first, then attach the correct project and user/session identifiers.

Next step

After your first write, verify it with memory search or session ingest and extract if your source data already arrives as a conversation stream.