Memory Search

Use POST /v1/memory/search when you want to retrieve memory already stored for a user, session, or project.

What this endpoint is for

A good first use case is: "I just wrote a preference or fact. Can I get it back in the right scope?"

This endpoint is also the easiest place to confirm that your project, user_id, and session_id model is behaving correctly.

Request and response

Minimal request

{
  "project": "retaindb-quickstart",
  "user_id": "demo-alex",
  "query": "How should I answer this user?"
}

Common first-run request

{
  "project": "retaindb-quickstart",
  "user_id": "demo-alex",
  "session_id": "session-001",
  "query": "How should I answer this user?",
  "include_pending": true,
  "profile": "fast",
  "top_k": 3
}

What a successful response includes

{
  "results": [],
  "count": 0,
  "trace_id": "trc_...",
  "latency_breakdown": {
    "cache_ms": 4,
    "embed_ms": 18,
    "vector_ms": 21,
    "lexical_ms": 3,
    "merge_ms": 2,
    "total_ms": 48
  }
}

Important fields:

• results: the matched memories
• trace_id: the request correlation id for debugging
• latency_breakdown: where RetainDB spent time

Good defaults

Start with these unless you know you need something else:

• profile: "fast"
• include_pending: true after recent writes
• top_k: 3 to 8

Try it

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",
    "session_id": "session-001",
    "query": "How should I answer this user?",
    "include_pending": true,
    "profile": "fast",
    "top_k": 3
  }'

What to check when results are empty

1. Did you use the same project, user_id, and session_id as the write?
2. Did you keep include_pending: true immediately after async writes?
3. Are you querying something semantically close to the stored content?

What to expect

• search should be fast enough to use inline in application flows
• cache-hit requests should be noticeably faster than cold requests
• latency_breakdown.total_ms is RetainDB time, not end-to-end LLM time

Security notes

Always scope by the correct project and caller context. A "good" result from the wrong tenant is a bug, not a success.

Next step

If you are validating read-after-write behavior, continue to read after write visibility. If you need to write memory in batches, use memory write and bulk write.