Memory scoping: keep each user's and agent's memories apart

A scope is a set of fields you attach to a memory when you add it and to a search when you query. The scope says who a memory is about and which conversation it came from. Search returns only memories that match every scope field you send.

Why scope matters

Without a scope, every memory in an app lives in one pool. A search for what Alice eats could return a memory about Bob. A scope lets one app serve many users and agents without mixing their memories.

The six fields

Every field is optional. The table lists the six fields and what each one means.

An actor is anyone who can own a memory. In an app for end users, each user is an actor with actor_type set to user.

How search combines the fields

Search combines every non-empty field with AND.

Scope two users and read one back

import os

from smritea import MemoryScope, SmriteaClient, SmriteaError

client = SmriteaClient(
    api_key=os.environ["SMRITEA_API_KEY"],
    app_id=os.environ["SMRITEA_APP_ID"],
)
alice = MemoryScope(actor_id="alice", actor_type="user")
bob = MemoryScope(actor_id="bob", actor_type="user")

try:
    client.add("Alice is vegetarian", scope=alice)
    client.add("Bob eats fish", scope=bob)
    for r in client.search("What does Alice eat?", scope=alice):
        print(r.memory.content)
except SmriteaError as e:
    print(e.http_status, e.code, e.request_id)

The search uses Alice's scope, so it never returns Bob's memory.

Two rules that cause errors

• Send actor_id and actor_type together. Sending one alone fails validation.
• Do not send participant_ids with conversation_id. The server answers HTTP 400 with the code VALIDATION_FAILED.

Learn more

The guide Scope memories per user, agent and conversation has samples in Python and TypeScript. The concept page Memory scope covers speaker_actor_id and conversation IDs in results.