memory_timeline

Return a chronological window of episodes and events. Use this when the agent’s reasoning depends on order and timing, not just on the current state.

Input

{
  "from": "2026-06-01T00:00:00Z",
  "to":   "2026-06-08T00:00:00Z",
  "entityId": "entity_lucas",
  "types": ["episode", "event"],
  "limit": 20
}

Output

{
  "items": [
    {
      "id": "evt_xxx",
      "type": "event",
      "name": "deploy.completed",
      "occurredAt": "2026-06-07T18:22:00Z",
      "source": "github-actions",
      "metadata": { "version": "v2.3.1" }
    },
    {
      "id": "ep_xxx",
      "type": "episode",
      "title": "Hot-fixed billing webhook",
      "validFrom": "2026-06-07T14:00:00Z",
      "validTo":   "2026-06-07T14:35:00Z",
      "factIds": ["fact_xxx", "fact_yyy"]
    }
  ]
}

When the agent should call it

• The user asks “what happened on Tuesday?”.
• A debugging session needs to correlate events (“did the deploy happen before or after the spike?”).
• Episode context is needed to ground a fact (“the migration ran during the v2.3 deploy”).

When the agent should NOT call it

• Looking up current state — use memory_recall instead.
• Long, open-ended historical queries — those should hit /v1/export.
• “Find every event ever” — use the REST endpoint with pagination.

Related

• Bitemporal model — explains how the timeline composes with the validity windows on facts.
• Cognitive primitives — covers when an episode is the right shape vs an event.