Memory Merging

The Memory Scope API automatically merges multiple memories into a single, deterministic result. This ensures consistent behavior and simplifies your application logic.

What is Memory Merging?

When you read memories from the API, you may receive multiple memories for the same user, scope, and domain. Instead of returning a list of memories, the API automatically merges them into a single, unified result.

The merging process is deterministic, meaning:

The same set of memories always produces the same merged result
Merging is consistent across API calls
Order of memory creation doesn't affect the final result
You get a confidence score indicating how reliable the merged result is

How Merging Works

The merging algorithm is scope-specific and handles different data types intelligently:

Preferences Scope

Arrays (likes/dislikes): Merged by union, with duplicates removed
Objects (settings): Deep merged, with later values taking precedence for conflicts
Strings: Latest value is used

Constraints Scope

Rules: Merged by union (all rules are combined)
Constraints: Intersection logic (most restrictive wins)

Other Scopes

Each scope has its own merging logic optimized for its use case
Complex objects are deep merged
Conflicts are resolved deterministically

Example: Merging Multiple Memories

Imagine a user has created multiple memories about their food preferences over time:

Merging Example

from memory_scope import MemoryScopeClient

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

# Memory 1: User initially likes pizza
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["pizza"]}
)

# Memory 2: User later adds sushi to likes
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["sushi"]}
)

# Memory 3: User adds a dislike
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"dislikes": ["broccoli"]}
)

# When reading, all memories are automatically merged
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

print(result.summary_struct)
# {
#   "likes": ["pizza", "sushi"],  # Merged from memories 1 and 2
#   "dislikes": ["broccoli"]       # From memory 3
# }

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

Confidence Scores

Every merged result includes a confidence score between 0 and 1. This score indicates how reliable the merged result is:

High confidence (0.8-1.0): Multiple consistent memories, reliable result
Medium confidence (0.5-0.8): Some memories present, but may be incomplete
Low confidence (0.0-0.5): Few memories or conflicting data

Use confidence scores to decide how much weight to give merged results in your application logic.

Response Format

Merged results are returned in two formats:

summary_text

A human-readable summary string, useful for logging and debugging.

"Likes: 2, Dislikes: 1, Settings: 0"

summary_struct

A structured JSON object containing the merged values, ready for use in your application.

{
  "likes": [
    "pizza",
    "sushi"
  ],
  "dislikes": [
    "broccoli"
  ],
  "settings": {}
}

Best Practices

Use summary_struct: Prefer the structured format for programmatic access.
Check confidence: Consider the confidence score when making decisions based on merged results.
Handle empty results: If no memories exist, the API returns empty structures rather than errors.
Don't merge manually: Let the API handle merging - it's optimized and deterministic.
Use max_age_days: Filter out stale memories using the max_age_days parameter.