Memory scope

A scope is a set of fields that 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.

The six fieldsCopy Anchor Link

Every field is optional. An empty scope is valid on add, but every add call must include the scope object. The table lists the six fields, what each one means, and its rules.

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 uses scopeCopy Anchor Link

Search combines every non-empty scope field with AND. A memory must match every field.

If no conversation matches participant_ids, search returns an empty list.

Build a scopeCopy Anchor Link

Pass the scope in the options of add. This example stores a memory for one user inside one conversation.

from smritea import MemoryScope

scope = MemoryScope(
    actor_id="alice",
    actor_type="user",
    conversation_id="conv-1",
)
client.add("Alice prefers vegetarian food", scope=scope)

To search across the conversations that two actors share, put both IDs in participant_ids on the scope. Do not add conversation_id to this scope.

from smritea import MemoryScope

scope = MemoryScope(participant_ids=["alice", "bob"])
results = client.search("What did they decide?", scope=scope)
print(len(results))

Rules that cause errorsCopy Anchor Link

• Send actor_id and actor_type together. Sending one alone fails validation.
• Do not send participant_ids with conversation_id. The server answers 400 with the code VALIDATION_FAILED.
• add ignores participant_ids, and Smritea does not store it.
• On add, a conversation_id needs an actor_type. Without it, the server answers 400 with VALIDATION_FAILED.

Who is askingCopy Anchor Link

Search also takes speaker_actor_id. It names the actor who asks the question. It never filters results. Use it to say who is speaking when the query refers to the speaker, for example with a first-person pronoun.

Conversation IDs in resultsCopy Anchor Link

Smritea returns conversation IDs in an internal form that starts with cnv_. Search accepts either the form you sent or the internal form.

Related pagesCopy Anchor Link

• Scope memories per user, agent and conversation
• How Smritea stores memory