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 with user_id
memory = MemoryStackClient(
    api_key="your_api_key",
    user_id="user_123"  # ← This isolates all operations
)

# Create memory - automatically tagged with user_123
memory.create_memory(
    content="User prefers dark mode",
    memory_type="preference"
)

# Search - only returns memories for user_123
results = memory.search_memories(
    query="preferences"
)
# ✓ 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

class MultiTenantMemoryService:
    def __init__(self, api_key: str):
        self.api_key = api_key
    
    def get_user_client(self, user_id: str):
        """Get client for individual user memories"""
        return MemoryStackClient(
            api_key=self.api_key,
            user_id=f"user_{user_id}"
        )
    
    def get_team_client(self, team_id: str):
        """Get client for team-shared memories"""
        return MemoryStackClient(
            api_key=self.api_key,
            user_id=f"team_{team_id}"
        )
    
    def get_org_client(self, org_id: str):
        """Get client for organization-wide memories"""
        return MemoryStackClient(
            api_key=self.api_key,
            user_id=f"org_{org_id}"
        )

# Usage
service = MultiTenantMemoryService(api_key="your_key")

# Store personal memory
user_memory = service.get_user_client("sarah_123")
user_memory.create_memory(
    content="Sarah prefers Python for backend work",
    memory_type="preference"
)

# Store team knowledge
team_memory = service.get_team_client("engineering")
team_memory.create_memory(
    content="Team uses microservices architecture",
    memory_type="fact"
)

# Store org-wide policy
org_memory = service.get_org_client("acme_corp")
org_memory.create_memory(
    content="Company policy: All APIs must use OAuth2",
    memory_type="policy"
)

    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
memory = MemoryStackClient(
    api_key="your_key",
    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.

    # Agent's private memories
agent_memory = MemoryStackClient(
    api_key="your_key",
    user_id=f"agent_{agent_id}"
)

# Team's shared memories
team_memory = MemoryStackClient(
    api_key="your_key",
    user_id=f"team_{team_id}"
)

    Pattern 3: Session-Based Isolation

    Isolate memories by session for temporary contexts or experiments.

    # Session-specific memories
memory = MemoryStackClient(
    api_key="your_key",
    user_id=f"session_{session_id}"
)

# Clean up when session ends
memory.delete_all_memories()  # Removes all session memories

    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