MemoryStackMemoryStack/Documentation
    Back to Documentation

    User Isolation & Multi-Tenancy

    Memory OS provides enterprise-grade data isolation, ensuring each user's memories are completely separate and secure.

    What is User Isolation?

    User isolation means that each user's memories are completely separate from every other user's memories. When User A searches for memories, they only see their own - never User B's.

    This is critical for privacy, security, and building multi-tenant applications where many users share the same infrastructure.

    ❌

    Without Isolation

    User A searches "preferences"
    ⚠️ Sees: Their preferences + User B's + User C's

    Privacy nightmare! Users can see each other's data.

    ✅

    With Isolation

    User A searches "preferences"
    ✓ Sees: Only their own preferences

    Perfect! Each user's data is completely private.

    How It Works

    Memory OS uses a user_id parameter to automatically filter all operations. Every memory is tagged with its owner, and the system ensures you can only access your own data.

    The user_id Parameter

    from memorystack import MemoryStackClient

# Initialize client
memory = MemoryStackClient(api_key="your_api_key")

# Create memory with user_id for isolation
memory.add(
    "User prefers dark mode",
    user_id="user_123"  # ← This isolates the memory
)

# Search - only returns memories for user_123
results = memory.search(
    "preferences",
    user_id="user_123"
)
# ✓ Only sees their own memories

    Key Point: The user_id is applied to every operation automatically. You don't need to filter manually - the SDK handles it for you.

    1

    Memory Creation

    When you create a memory, it's automatically tagged with the user_id from your client.

    Database: memory_id=123, user_id="user_123", content="..."
    2

    Automatic Filtering

    All queries (search, list, get) automatically filter by your user_id.

    SQL: SELECT * FROM memories WHERE user_id = 'user_123'
    3

    Access Control

    You can only update or delete memories that belong to you. Attempts to access other users' memories are rejected.

    ❌ Error: "Memory not found" (if trying to access another user's memory)

    B2B Multi-Tenancy

    For B2B applications, you often need hierarchical isolation: organizations contain teams, teams contain users. Memory OS supports this with flexible scoping.

    Hierarchical Structure

    Organization Level

    Memories shared across the entire organization

    user_id="org_acme_corp"

    Team Level

    Memories shared within a specific team

    user_id="team_engineering"

    User Level

    Private memories for individual users

    user_id="user_sarah_123"

    Implementation Example

    from memorystack import MemoryStackClient

# Initialize client once
client = MemoryStackClient(api_key="your_key")

# Store personal memory (user-scoped)
client.add(
    "Sarah prefers Python for backend work",
    user_id="user_sarah_123",
    metadata={"type": "preference"}
)

# Store team knowledge (team-scoped)
client.add(
    "Team uses microservices architecture",
    user_id="team_engineering",
    metadata={"type": "fact"}
)

# Store org-wide policy (org-scoped)
client.add(
    "Company policy: All APIs must use OAuth2",
    user_id="org_acme_corp",
    metadata={"type": "policy"}
)

# Search within specific scope
user_prefs = client.search("preferences", user_id="user_sarah_123")
team_facts = client.search("architecture", user_id="team_engineering")
org_policies = client.search("policy", user_id="org_acme_corp")

    Security Guarantees

    Database-Level Isolation

    All queries include user_id in the WHERE clause. It's impossible to accidentally query another user's data.

    WHERE user_id = 'user_123'

    API-Level Validation

    Every API request validates the user_id. Attempts to access unauthorized data are rejected before reaching the database.

    401 Unauthorized

    Encrypted at Rest

    All memories are encrypted in the database. Even if someone gains database access, they can't read the data.

    AES-256 encryption

    Audit Logging

    All access is logged with user_id, timestamp, and operation. You can audit who accessed what and when.

    Full audit trail

    Common Patterns

    Pattern 1: SaaS Application

    Each customer gets their own isolated memory space. Use their account ID as the user_id.

    # Use customer's account ID
client = MemoryStackClient(api_key="your_key")
client.add("Customer preference", user_id=f"customer_{customer.account_id}")

    Pattern 2: Multi-Agent System

    Each agent has its own memory space, plus access to shared team memories.

    client = MemoryStackClient(api_key="your_key")

# Agent's private memories
client.add("Agent note", metadata={"agent_id": agent_id, "scope": "personal"})

# Team's shared memories
client.add("Team knowledge", metadata={"team": team_id, "scope": "team"})

    Pattern 3: Session-Based Isolation

    Isolate memories by session for temporary contexts or experiments.

    client = MemoryStackClient(api_key="your_key")

# Session-specific memories
client.add("Session context", user_id=f"session_{session_id}")

# Search within session
results = client.search("context", user_id=f"session_{session_id}")

    Best Practices

    ✅ Do

    • • Use consistent user_id format across your app
    • • Include tenant/org prefix for B2B apps
    • • Validate user_id before creating client
    • • Use descriptive prefixes (user_, team_, org_)
    • • Log user_id for debugging and auditing

    ❌ Don't

    • • Use the same user_id for multiple users
    • • Share API keys between different tenants
    • • Store sensitive data in user_id itself
    • • Reuse user_id after account deletion
    • • Hardcode user_id values in your code

    Next Steps

    Memories

    Learn about the memory data model

    Multi-Agent Example

    See team memory isolation in action

    Start Building

    Get started with the Python SDK