Scoping And Identity

A SaaS app maps each end-user to a stable user_id and uses it for all add/search calls across sessions.

Use a stable, unique user_id (e.g., your auth subject id) as the long-term memory key so memories persist across sessions and devices for that person. Do not derive user_id from a per-session token or display name that can change or collide.

An agent wants short-lived, conversation-specific memory that should not bleed into the user's permanent profile.

Use run_id to scope memories to a single session/conversation. Combine with user_id when the memory is both per-user and per-session. Treat run_id-only memories as ephemeral context that should not be promoted to long-term without intent.

A platform runs several specialized agents; each should accumulate its own domain knowledge separate from the others.

Use agent_id to partition per-agent memory (e.g., a 'sales' agent vs a 'support' agent). Decide explicitly whether agent memory is global or per-user (agent_id + user_id). Keep agent_id stable per logical agent so its knowledge accrues.