episode_search
Retrieve past episodes from memory across sessions using filters like scope, time, session, or swarm ID. Returns most recent matches to review conclusions and takeaways.
Instructions
Cross-session lookup for journal-shaped entries (episodes). NOT ranked — episodes are chronological and the filter set (scope / since / session_id) is the discovery surface. For the loop-iteration-entry case prefer episode_handoff, which auto-resolves the prior session and caps the surface.
Returns {id, session_id, created, takeaway, body, scopes, swarm_id} per row, oldest-first inside the most-recent-max_results window: over the cap it keeps the MOST-RECENT N, so 'what did I conclude lately?' reads the tail, not the head. session_id is present because this surface spans sessions (unlike episode_handoff); swarm_id (may be null) is the multi-agent cohort tag — pass a coordinator's session id to gather every sub-agent's takeaways in one read.
WORKTREE SCOPING: by default (auto_scope=True) the bare discovery walk (no swarm_id / parent_session_id) drops episodes whose captured git worktree differs from yours. PERMISSIVE, not a boundary, and weaker than the strict equality episode_handoff applies — it passes an episode through when there is nothing to compare (none captured, or you outside any git checkout), when the recorded worktree is gone from disk, and when you are in a LINKED worktree of the checkout that wrote it, so under agent fan-out the primary checkout's episodes stay visible. An EXPLICIT swarm_id / parent_session_id / ids is never worktree-filtered: naming a cohort or session is deliberate cross-worktree intent.
Parameters (full reference in docs/api.md):
scopes(optional): keep only episodes whose scope list intersects this filter.parent_session_id(optional): restrict to one session's directory. Composes withswarm_idto narrow a fan-in.swarm_id(optional): fan-in filter — episodes tagged with this cohort id, across all sessions.since(optional ISO-8601): created at-or-after this instant.auto_scope(default True): worktree-scope the bare walk (see WORKTREE SCOPING). False sweeps every worktree sharing the root.max_results(default 20, cap 200): surfaces the most-recent N.ids(optional): only these episode ULIDs — explicit selector, never worktree-filtered; unknown ids are absent, not an error.include_bodies(default True): False OMITSbody— takeaway-only rows. Scan, then re-read one viaids.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| since | No | ||
| scopes | No | ||
| swarm_id | No | ||
| auto_scope | No | ||
| max_results | No | ||
| include_bodies | No | ||
| parent_session_id | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |