Read-After-Write Visibility

RetainDB writes are often asynchronous on purpose. That is good for application latency, but it creates an obvious first-time question:

"If the write returned quickly, when will search see it?"

The short answer is: usually right away if you query the same scope and keep include_pending=true.

The model

There are two states to think about after a write:

1. Pending overlay

Right after a write is accepted, RetainDB can surface the new content from a short-lived pending layer.

This is what lets profile, session, and search endpoints feel immediate while background extraction is still running.

2. Processed memory

After extraction finishes, the memory is available from the normal processed store and no longer relies on the pending overlay.

What you need to do

When validating a fresh integration, use the same identifiers on the write and the read:

• project
• user_id
• session_id when applicable

And keep:

{
  "include_pending": true
}

That flag is the difference between “this looks instant” and “I think the API lost my write.”

Where include_pending matters

You will usually see it on:

• POST /v1/memory/search
• GET /v1/memory/profile/:userId
• GET /v1/memory/session/:sessionId

A practical first-run loop

1. Write a memory for one user or session.
2. Search or fetch the profile using the exact same scope.
3. Keep include_pending=true.
4. Confirm the result appears.
5. Poll the background job if your write returned a job id.

Example

Write:

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",
    "content": "Alex prefers direct answers with short paragraphs"
  }'

Immediate read:

curl -X POST "https://api.retaindb.com/v1/memory/search" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "retaindb-quickstart",
    "user_id": "demo-alex",
    "query": "How should I answer Alex?",
    "include_pending": true
  }'

Why fresh reads look empty

Usually it is one of these:

1. The read used a different project.
2. The read used a different user_id or session_id.
3. include_pending was disabled.
4. You are checking the wrong endpoint for the kind of memory you wrote.

What to expect

• A write can be acknowledged before full extraction completes.
• Pending results are a bridge, not a separate long-term store.
• Once processing finishes, the same memory should be visible through the normal processed path.

Next step

If you want the exact search request to pair with this behavior, read memory search. If you want to inspect pending profile or session state directly, go to profiles, sessions, and jobs.