Skip to main content

Memory Lifecycle Guide

Masar's memory system lets your agent build expertise from experience. Instead of starting from zero every time, the agent recalls what worked before, follows proven patterns, and improves with each task.

The Four Operations​

Store​

After completing a task, store the episode with its full context:

client.memory.store(
    domain="helpdesk",
    context="Customer needed a ticket routing system with SLA tracking",
    schema=completed_schema,
    actions_taken=["add_entity_Ticket", "add_trait_Triage", "add_sla_states"],
    outcome="success",
    metadata={"steps": 14, "duration_ms": 8200}
)

Store both successes and failures. Failed episodes teach the agent what to avoid.

Recall​

Before starting a new task, recall similar experiences:

memories = client.memory.recall(
    context="Build a support ticket system with priority routing",
    domain="helpdesk",
    limit=5
)

if memories.pattern:
    print(f"Found pattern: {memories.pattern.name}")
    print(f"Recommended steps: {memories.pattern.steps}")

Recall returns two things: a pattern (the distilled approach that worked across multiple similar tasks) and episodes (specific past instances ranked by similarity).

Compress​

As episodes accumulate, compress them into patterns:

result = client.memory.compress(domain="helpdesk")
print(f"Extracted {result.patterns_extracted} patterns from {result.episodes_compressed} episodes")

Compression groups similar episodes together and extracts the common sequence of actions. Run it periodically (weekly, or after every 50 episodes). The original episodes remain accessible, but recall prioritizes the compressed patterns.

Forget​

Remove outdated or low-value episodes:

client.memory.forget(
    domain="helpdesk",
    older_than_days=180,
    min_relevance=0.2
)

Forgetting keeps memory focused. Episodes that were never recalled, or that led to failures without teaching anything new, get pruned. Patterns extracted from those episodes persist even after the source episodes are forgotten.

How Memory Improves Over Time​

Week 1: The agent has no memory. Every task uses full planning from scratch.

Week 4: 30 episodes stored. Recall starts finding matches. The agent skips planning for routine tasks and jumps straight to a known pattern.

Month 3: After compression, 8 patterns cover 90% of requests. The agent handles most tasks in under 3 seconds of planning time, down from 15 seconds.

Month 6: The agent's success rate on first attempt goes from 70% to 95%. Failures are concentrated in genuinely novel task types, which then become new patterns.

Best Practices​

  • Scope domains narrowly: "helpdesk" and "ecommerce" as separate domains, not one "all-tasks" domain
  • Store context generously: The more context in the episode, the better recall matching works
  • Compress regularly: Weekly compression keeps recall fast and patterns fresh
  • Monitor with stats: Use GET /memory/stats to track growth and plan compression

Next Steps​