User-Scoped Memory in Deep Agents: What It Is and Why You Need It

                    One AI Agent
                         |
          +--------------+--------------+
          |              |              |
       Alice            Bob          Charlie
          |              |              |
     Alice's memory  Bob's memory  Charlie's memory

- Likes concise answers
- Prefers Python

- Likes detailed explanations
- Prefers TypeScript

namespace=lambda current_runtime: (
    current_runtime.context.user_id,
)

User A -> Agent -> preferences.md
User B -> Agent -> preferences.md

User A: Be concise.
User B: Give detailed explanations.
User C: Use Python.
User D: Use TypeScript.

Conversation 1 ─┐
Conversation 2 ─┼──> Alice's long-term memory
Conversation 3 ─┘

MEMORY_PATH = "/memories/preferences.md"

@dataclass(frozen=True)
class UserContext:
    user_id: str

user-alice
user-bob

namespace=lambda current_runtime: (
    current_runtime.context.user_id,
)

user-alice -> namespace ("user-alice",)
user-bob   -> namespace ("user-bob",)

Store
│
├── ("user-alice",)
│   └── /preferences.md
│
└── ("user-bob",)
    └── /preferences.md

uv run user_scoped_memory.py

"""Runnable user-scoped long-term memory example.

Run with ``uv run user_scoped_memory.py`` after setting ``NVIDIA_API_KEY`` in
the environment or in a ``.env`` file.

Each invocation supplies a user ID through the graph context. The backend uses
that ID as the store namespace, so users can share one agent without sharing
their preference files.
"""

import os
from dataclasses import dataclass

from dotenv import load_dotenv
from langchain_nvidia_ai_endpoints import ChatNVIDIA
from langgraph.store.memory import InMemoryStore
from requests.exceptions import Timeout

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from deepagents.backends.utils import create_file_data


MEMORY_PATH = "/memories/preferences.md"
STORE_MEMORY_PATH = "/preferences.md"


@dataclass(frozen=True)
class UserContext:
    user_id: str


def build_model():
    """Create the chat model used by the demo."""
    if not os.getenv("NVIDIA_API_KEY"):
        raise RuntimeError(
            "Set NVIDIA_API_KEY in the environment or a .env file before "
            "running this example."
        )

    model_name = os.getenv(
        "NVIDIA_MODEL",
        "nvidia:nvidia/nemotron-3-ultra-550b-a55b",
    ).removeprefix("nvidia:")

    timeout_seconds = int(
        os.getenv("NVIDIA_TIMEOUT_SECONDS", "180")
    )

    max_completion_tokens = int(
        os.getenv("NVIDIA_MAX_COMPLETION_TOKENS", "1024")
    )

    return ChatNVIDIA(
        model=model_name,
        timeout=timeout_seconds,
        max_completion_tokens=max_completion_tokens,
        model_kwargs={"parallel_tool_calls": False},
    )


def seed_memory(store: InMemoryStore) -> None:
    """Create an isolated preference file for each demo user."""
    preferences = {
        "user-alice": """## Preferences
- Likes concise bullet points.
- Prefers Python examples.
""",
        "user-bob": """## Preferences
- Likes detailed explanations.
- Prefers TypeScript examples.
""",
    }

    for user_id, content in preferences.items():
        store.put(
            (user_id,),
            STORE_MEMORY_PATH,
            create_file_data(content),
        )


def build_backend(store: InMemoryStore) -> CompositeBackend:
    """Route memory to the namespace belonging to the current user."""
    return CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                store=store,
                namespace=lambda current_runtime: (
                    current_runtime.context.user_id,
                ),
            ),
        },
    )


def build_agent(store: InMemoryStore):
    return create_deep_agent(
        model=build_model(),
        memory=[MEMORY_PATH],
        backend=build_backend(store),
        context_schema=UserContext,
        store=store,
        name="user-scoped-memory-demo",
    )


def invoke_for_user(
    agent,
    user_id: str,
    thread_id: str,
    prompt: str,
) -> str:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": prompt}]},
        config={"configurable": {"thread_id": thread_id}},
        context=UserContext(user_id=user_id),
    )

    return result["messages"][-1].content


def main() -> None:
    load_dotenv()

    store = InMemoryStore()
    seed_memory(store)
    agent = build_agent(store)

    prompt = (
        "How do I read a CSV file? Use only the preferences stored in "
        f"{MEMORY_PATH}. State which language and response style you used."
    )

    print("Alice's isolated memory")

    try:
        print(
            invoke_for_user(
                agent,
                user_id="user-alice",
                thread_id="alice-memory-thread",
                prompt=prompt,
            )
        )
    except Timeout:
        print(
            "The NVIDIA model timed out. The memory store is configured "
            "correctly; try NVIDIA_MODEL=meta/llama-3.2-3b-instruct or "
            "increase NVIDIA_TIMEOUT_SECONDS."
        )

    print("\nBob's isolated memory")

    try:
        print(
            invoke_for_user(
                agent,
                user_id="user-bob",
                thread_id="bob-memory-thread",
                prompt=prompt,
            )
        )
    except Timeout:
        print(
            "The NVIDIA model timed out. The memory store is configured "
            "correctly; try NVIDIA_MODEL=meta/llama-3.2-3b-instruct or "
            "increase NVIDIA_TIMEOUT_SECONDS."
        )


if __name__ == "__main__":
    main()

One Agent
   |
   +-- User ID A -> Memory A
   |
   +-- User ID B -> Memory B
   |
   +-- User ID C -> Memory C