APIUpdated 2026-05-25
Memory API
Write, search, update, and delete RetainDB memories over HTTP.
Applies to: RetainDB API v1
Memory routes are the low-level HTTP surface behind user and session memory.
Pick the right route
| Goal | Route |
|---|---|
| Store one fact or preference | POST /v1/memory |
| Store many known memories | POST /v1/memory/bulk |
| Search remembered user/session state | POST /v1/memory/search |
| Ingest a conversation transcript | POST /v1/memory/ingest/session |
| Check async write status | GET /v1/memory/jobs/:jobId |
| Read memories for a user or session | GET /v1/memory/profile/:userId, GET /v1/memory/session/:sessionId |
Routes
POST /v1/memoryPOST /v1/memory/bulkPOST /v1/memory/searchPOST /v1/memory/ingest/sessionGET /v1/memory/jobs/:jobIdGET /v1/memory/profile/:userIdGET /v1/memory/session/:sessionIdGET /v1/memory/:memoryIdPUT /v1/memory/:memoryIdDELETE /v1/memory/:memoryId
Write memory
bash
curl -X POST "https://api.retaindb.com/v1/memory" \
-H "Authorization: Bearer $RETAINDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "app",
"user_id": "user_123",
"content": "User prefers concise answers.",
"memory_type": "preference",
"write_mode": "async"
}'Typical accepted response:
json
{
"success": true,
"mode": "async",
"trace_id": "trc_..."
}Search memory
bash
curl -X POST "https://api.retaindb.com/v1/memory/search" \
-H "Authorization: Bearer $RETAINDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "app",
"user_id": "user_123",
"query": "How should I reply?",
"include_pending": true,
"top_k": 5
}'Typical search response:
json
{
"results": [
{
"memory": {
"id": "mem_...",
"content": "User prefers concise answers.",
"memory_type": "preference"
},
"score": 0.82
}
],
"count": 1,
"trace_id": "trc_..."
}Defaults
- Use
write_mode: "async"unless you need synchronous confirmation. - Use
include_pending: trueimmediately after recent writes. - Keep scope identifiers stable.
- Prefer small, high-signal memories over raw full transcripts.
Common mistakes
| Symptom | Likely cause | Fix |
|---|---|---|
| Empty search after write | Different project or user_id | Reuse the exact same identifiers |
| Fresh write not visible | Async write still processing | Search with pending visibility or retry |
| Good memory for wrong user | Caller scope is not enforced server-side | Attach scope after your own auth check |
| Slow prompts | Sending too much memory to the model | Lower top_k or use the SDK formatted context |
Next: Raw HTTP quickstart.
Was this page helpful?
Your feedback helps us prioritize docs improvements weekly.