Skip to main content

Memory API

The Memory API gives your agent long-term experience. Store completed episodes, recall similar past experiences, compress patterns from repeated tasks, and forget outdated information.

Episode Lifecycle​

An episode flows through four stages: store (save the experience), recall (find similar past experiences), compress (extract patterns from clusters), and forget (remove stale data).

POST /memory/store​

Stores a completed episode with its context, actions, and outcome.

curl -X POST https://api.masar.almadar.io/memory/store \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "helpdesk",
    "context": "Customer reported database timeout on checkout",
    "schema": {"name": "App", "orbitals": [...]},
    "actions_taken": ["add_retry_logic", "add_timeout_config", "add_error_state"],
    "outcome": "success",
    "metadata": {"duration_ms": 4500, "llm_calls": 3}
  }'

Response:

{
  "episode_id": "ep_abc123",
  "domain": "helpdesk",
  "stored_at": "2026-03-19T10:30:00Z"
}

POST /memory/recall​

Finds similar past episodes and returns matched patterns.

curl -X POST https://api.masar.almadar.io/memory/recall \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "User seeing timeout errors during payment",
    "domain": "helpdesk",
    "limit": 5
  }'

Response:

{
  "pattern": {"name": "timeout-resolution", "steps": ["add_retry_logic", "add_timeout_config", "add_error_state"]},
  "episodes": [
    {"episode_id": "ep_abc123", "similarity": 0.92, "outcome": "success"},
    {"episode_id": "ep_def456", "similarity": 0.87, "outcome": "success"}
  ],
  "total_matches": 5
}

POST /memory/compress​

Triggers pattern extraction across stored episodes. Run periodically to keep memory efficient.

curl -X POST https://api.masar.almadar.io/memory/compress \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "helpdesk"}'

Response:

{
  "patterns_extracted": 3,
  "episodes_compressed": 47,
  "memory_reduction": 0.62
}

POST /memory/forget​

Removes episodes older than a threshold or below a relevance score.

{"domain": "helpdesk", "older_than_days": 90, "min_relevance": 0.3}

GET /memory/stats​

Returns memory usage statistics for a domain.

Response:

{
  "domain": "helpdesk",
  "total_episodes": 142,
  "patterns": 8,
  "oldest_episode": "2025-11-01T08:00:00Z",
  "storage_used_mb": 12.4
}

Next Steps​