Skip to main content
Scoping decides what memories are partitioned by when they’re stored. The values used for that are called scope keys — memories are stored separately per scope key value. Who can reach this memory space, and what they see once they do, is configured under access control.

​
Scope keys

The keys memories are partitioned by.
  • flow_id Partitions per Flow. Every run using that Flow shares the same memories.
  • thread_id Partitions per conversation. Usually paired with flow_id so each conversation keeps its own memories.
  • user_id Partitions per user. Memories accumulate separately for each user.
  • Custom key Beyond those three, any value sent along with the call can be a key. For example, org_id.
Key values are filled from the request when the Flow is called. In a conversational Flow, the conversation supplies thread_id and the caller supplies user_id. That means a custom key has to use exactly the name the call sends. If the caller sends org_id, put org_id in the custom key. Putting in organization_id, which the call doesn’t send, means no scoping happens. With no keys at all, the space is global and every run shares one store.

​
Combining scope keys

Scope keys can be combined, and the combination becomes a single unit of storage. Using flow_id and thread_id together makes one conversation the unit of storage; adding user_id on top stores separately per user even within the same conversation. The more keys you add, the smaller the unit of storage. Pick one of the following in the memory space settings. The first four are presets holding common combinations.
  • Session flow_id and thread_id
  • User long-term user_id
  • Flow shared flow_id
  • Global No keys
  • Custom combination Select whichever of flow_id, thread_id, and user_id you need, and create custom keys to combine alongside them.

​
Access control

Where scope partitions storage, access control governs reads. It limits who can reach this memory space and decides which items to show them. Partition key (personalize) Pick a single value as the basis and callers see only the items matching their own value of it. Leave it blank and everyone sees the same items. Choose from None, Per user (user_id), Per org (org_id), and Per client (client_id), or type in a custom claim. Requires (gates) Block access itself with a condition. A call that doesn’t pass can’t read this memory space. Each rule takes the form param + operator (in / eq) + a list of allowed values. Clicking Admins only creates the rule user.permission in admin, owner right away, and + Rule adds more conditions. With several conditions, all must pass for access.

​
How to debug

If an Agent’s answer mixes in memories from another scope, check the following.
  1. Look at the memory operations in the trace. Every read and write is logged with its scope.
  2. Find items written at a broader scope than intended.
  3. In the Access section of the memory space’s Settings tab, confirm the partition key and required permissions are set the way you intended.
The most common mistake is forgetting to turn on a scope key, so every item piles up in a single global scope.