Core concepts

User-scoped memory

User-scoped memory means every user gets a private memory boundary. The Memory Key on a request decides which vault MemoryRouter can retrieve from and write to.

Memory Keys

A Memory Key starts with mk_. It authenticates the request and points to a memory vault.

mk_user_a → Vault A
mk_user_b → Vault B

Use one stable Memory Key per end user when building a multi-user product.

Vaults

A vault is the storage and retrieval boundary for memory. Memories in one vault are not searched by requests authenticated with another key.

Retrieval

Retrieval searches the user's vault for relevant memories. The goal is high-signal continuity, not dumping the entire history into context.

Retrieval can happen two ways:

• Proxy mode: MemoryRouter retrieves memory before it calls the provider.
• Local inference mode: Your app calls POST /v1/memory/prepare and injects the returned context before calling the provider directly.

Storage

Storage writes useful new context into the same user's vault. Existing upload APIs can also backfill memories from transcripts, profiles, notes, or support history.

Storage can happen two ways:

• Proxy mode: MemoryRouter stores useful context after the provider response.
• Local inference mode: Your app calls POST /v1/memory/ingest with the completed exchange.

Provider pass-through

MemoryRouter can use provider keys stored in the dashboard, or you can pass provider keys per request. In pass-through mode, X-Memory-Key identifies the vault and the provider key authenticates with the model provider.

Provider pass-through is optional. If your app already owns provider calls, use local inference mode and keep provider traffic out of MemoryRouter.

Key mode suffixes

Suffixes control memory behavior without changing code:

These are useful for ingestion, read-only tools, and debugging.