Architecture Overview
Understand the main RetainDB building blocks so later API and SDK docs feel like one system instead of isolated features.
RetainDB is easiest to reason about when you stop thinking in endpoints first and think in system roles first.
The four parts that matter most
1. Project scope
Everything meaningful happens inside a project. Projects hold sources, memory, and retrieval scope.
2. Write paths
Writes enter the system through memory routes, session ingest, or source ingest and sync flows. Some of those writes are intentionally asynchronous so your application is not forced to wait for all downstream processing.
3. Retrieval paths
Retrieval happens through memory search, context query, and MCP tools that sit on top of the same underlying project context.
4. Integration surfaces
You can reach the same system through raw HTTP, the SDK, the dashboard, or MCP. Those surfaces feel different, but they should not produce different mental models.
Why the architecture matters to a first integration
A lot of confusing docs bugs are really architecture misunderstandings:
- a search looks empty because project scope is wrong
- a fresh write looks missing because the caller expects synchronous extraction
- a connector looks broken because the source was created but never synced
What to remember
If you only remember three things, remember these:
- scope first
- async is normal on writes
- verify the smallest working loop before you scale up
Next step
Go to memory model if you want the conceptual model for stored user context, or projects and sources if you are ready to build.
Was this page helpful?
Your feedback helps us prioritize docs improvements weekly.