Core concepts
Multi user isolation
Per user and per agent memory, enforced at recall and on every derived surface.
Serving many users and agents from one app? MenteDB isolates memory at several levels so one user's data never reaches another's. Pass the owner ids on every turn and the engine enforces the rest, at recall time and across every derived surface (profile, entities, communities, consolidation, contradiction).
The isolation levels
Data is separated at four levels, each with a stronger mechanism. Pick the ones that match your tenancy.
| Level | Separates | How it is kept separate |
|---|---|---|
| AccountAPI key | Your customers / tenants. | A separate engine writing to separate storageper account, not a filter. Physically different databases, so one account cannot address another's data. Strongest. |
user_idthe end-user | End-users inside one account. | An owner axis on the memory, enforced at recall and on every derived surface. Orthogonal to agent_id. |
agent_idthe main scope | Agents serving a user. | The primary owner axis, enforced everywhere recall and derivation happen. |
| Globalno ids | Nothing, shared on purpose. | Memories stored with no owner are visible to everyone in the account. |
Account is the hardest boundary (separate databases, structurally impossible to cross). Inside one account, user_id and agent_id are orthogonal: a memory is owned by the pair (user_id, agent_id), so a query for one user never sees another user's memories, even under the same agent, and the engine enforces this at recall and across profile, entities, communities, consolidation, and contradiction, not just retrieval. Guarded by adversarial tests (tests/user_isolation.rs).
Always pass user_id and agent_id
agent_id is the main scope; user_id is an extra axis on top. Set both on every turn so a memory is owned by that (user_id, agent_id) pair.
If you omit them, the memory is stored with no owner (global) and becomes visible to every user in the account, that is how memories get polluted. Pass the ids on every call. And do not use project_context for isolation, it is an advisory tag, not a boundary.
Hosted (REST)
Give your assistant a stable agent_id and each end-user a stable user_id, and pass both on every turn.
import os, requests, uuid
API = "https://api.mentedb.com/v1/process_turn"
HEADERS = {"Authorization": f"Bearer {os.environ['MENTEDB_API_KEY']}"}
# One stable agent id for your assistant; a stable user id per end-user.
ASSISTANT = str(uuid.uuid5(uuid.NAMESPACE_URL, "myapp:support-assistant"))
def user_id(user_key):
return str(uuid.uuid5(uuid.NAMESPACE_URL, f"myapp:user:{user_key}"))
def turn(user_key, message, reply, turn_id):
resp = requests.post(API, headers=HEADERS, json={
"user_message": message,
"assistant_response": reply,
"turn_id": turn_id,
"user_id": user_id(user_key), # the end-user: extra isolation axis
"agent_id": ASSISTANT, # the agent: the main scope
})
return resp.json()["context"]
# Alice and Bob share one assistant but never see each other's memories.
turn("alice", "my API budget is $200/mo", "noted", 0)
turn("bob", "what is my API budget?", "", 0) # Bob's context will NOT contain Alice's $200Same thing with the hosted client (pip install mentedb):
from mentedb import MenteDBClient
client = MenteDBClient(api_key="mdb_...")
result = client.process_turn(
"what did we decide about the budget?",
"",
3,
user_id=user_id("alice"),
agent_id=ASSISTANT,
)Self-hosted (SDK)
from mentedb import MenteDB
db = MenteDB("./app-memory")
# Private to one user under one agent: pass both ids.
db.process_turn(
user_message="I prefer dark mode",
assistant_response="noted",
turn_id=0,
user_id=user_id("alice"),
agent_id=ASSISTANT,
)
# Shared with everyone: store with no ids (nil owner = global).
db.store("Support hours are 9 to 5 ET")
# Alice's next turn sees her own memory + the global one, never another user's.
result = db.process_turn(user_message="when is support open?", turn_id=1, agent_id=user_id("alice"))
for m in result.context:
print(m.content)What is isolated
Isolation is not only recall. Everything MenteDB derives from memories is scoped to the owner, so one user's data cannot bleed into another's through a side channel.
| Subsystem | How it stays separate |
|---|---|
| Recall & context | A scoped query returns the user's own memories plus global, never another user's. |
| Agent profile | Built only from that agent's own memories, and owned by that agent (see below). |
| Entity linking | Entities link within one owner; one user's "Falcon" never merges with another's. |
| Community detection | Clusters and summaries are built per owner. |
| Consolidation | Near-duplicate memories only merge within one owner, never across. |
| Contradiction & inference | A memory is only compared against the same owner's memories, plus global. |
| Decay | Per memory, so each user's memories age on their own access. |
The agent profile
During sleeptime enrichment MenteDB distills a compact profile, the owner's stable preferences, facts, and patterns, so future turns start from a summary instead of re-deriving it. The profile is scoped to the same owner as everything else: it is built from only that user's and agent's own memories and owned by that (user_id, agent_id), so it stays private to that user. Each user gets their own profile under each agent; global (nil owned) knowledge gets a shared one. Nothing another user said can ever appear in your users' profiles.
Best practices
- Always pass user_id and agent_id. Derive them deterministically from your own ids (for example
uuid5) so they are stable across turns and restarts. A missing id means global, and global is shared with everyone. - One account (API key) per tenant for the hardest boundary, then
user_id/agent_idto separate the many end-users inside one account. - Reserve global (no ids) for genuinely app-wide knowledge, policies, product facts, docs, that every user should see.
- Never use project_context for isolation. It is an advisory tag for organizing memories; only
user_idandagent_idare enforced boundaries. - Keep the ids stable per user. The same end-user should always map to the same
user_id, or their memories fragment across owners and recall gets worse.