Memory Merging

Learn how the API automatically merges multiple memories into a single, deterministic result. Merging is scope-specific and always produces consistent results.

Multiple Memories Merge Automatically

When you store multiple memories with the same scope and domain, they're automatically merged when you read them.

Multiple Memories Merge

from memory_scope import MemoryScopeClient

client = MemoryScopeClient(api_key="your-api-key")

# Store multiple memories
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["pizza"]}
)

client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["sushi"]}
)

client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"dislikes": ["broccoli"]}
)

# Read memories - they're automatically merged
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

print(result.summary_struct)
# {
#   "likes": ["pizza", "sushi"],
#   "dislikes": ["broccoli"]
# }

print(f"Confidence: {result.confidence}")
# Confidence: 0.85

Automatic Merging

The API automatically merges all memories with the same scope and domain. You don't need to handle merging logic yourself.

Confidence Scores

Confidence scores indicate how complete the merged data is. Use them to make informed decisions about when to ask users for more information.

Using Confidence Scores

result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

confidence = result.confidence

if confidence < 0.5:
    # Low confidence - data may be incomplete
    # Ask user to provide more preferences
    show_preference_form()
    print("Low confidence - please provide more preferences")
elif confidence < 0.8:
    # Medium confidence - use data but show it's limited
    use_preferences(result.summary_struct)
    show_message("Limited preferences available")
else:
    # High confidence - use data confidently
    use_preferences(result.summary_struct)
    print("High confidence - using preferences")

Deterministic Results

Merging is deterministic - the same memories always produce the same merged result, regardless of when they were created or in what order.

Deterministic Merging

# Store memories in any order
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    value_json={"likes": ["pizza"]}
)

client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    value_json={"likes": ["sushi"]}
)

# Read - always gets same merged result
result1 = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate recommendations"
)

# Read again - same result
result2 = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate recommendations"
)

# Results are identical
assert result1.summary_struct == result2.summary_struct
print("Results are deterministic!")

Scope-Specific Merge Logic

Different scopes use different merge logic. Preferences merge lists, constraints merge rules, and facts merge by recency.

Scope-Specific Merge Logic

# Preferences: Lists are merged (union)
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    value_json={"likes": ["pizza"]}
)
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    value_json={"likes": ["sushi"]}
)
# Result: {"likes": ["pizza", "sushi"]}

# Constraints: Rules are merged (union)
client.create_memory(
    user_id="user123",
    scope="constraints",
    domain="dietary",
    value_json={"rules": ["vegetarian"]}
)
client.create_memory(
    user_id="user123",
    scope="constraints",
    domain="dietary",
    value_json={"rules": ["no nuts"]}
)
# Result: {"rules": ["vegetarian", "no nuts"]}

# Facts: Most recent value wins
client.create_memory(
    user_id="user123",
    scope="facts",
    domain="personal",
    value_json={"location": "San Francisco"}
)
client.create_memory(
    user_id="user123",
    scope="facts",
    domain="personal",
    value_json={"location": "New York"}
)
# Result: {"location": "New York"} (most recent)