Core concepts

Multi user isolation

Per user and per agent memory, enforced at recall and on every derived surface.

llms.txt

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.

LevelSeparatesHow it is kept separate
AccountAPI keyYour 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-userEnd-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 scopeAgents serving a user.The primary owner axis, enforced everywhere recall and derivation happen.
Globalno idsNothing, 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.

Python
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 $200

Same thing with the hosted client (pip install mentedb):

Python
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)

Python
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.

SubsystemHow it stays separate
Recall & contextA scoped query returns the user's own memories plus global, never another user's.
Agent profileBuilt only from that agent's own memories, and owned by that agent (see below).
Entity linkingEntities link within one owner; one user's "Falcon" never merges with another's.
Community detectionClusters and summaries are built per owner.
ConsolidationNear-duplicate memories only merge within one owner, never across.
Contradiction & inferenceA memory is only compared against the same owner's memories, plus global.
DecayPer 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_id to 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_id and agent_id are 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.