bettermemory

Overview Schema Source Related Servers Discussions Admin

episode_search

Search cross-session journal episodes by scope, session, cohort, or time to retrieve recent entries for recall and context.

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.

Rows are 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.

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 with swarm_id to 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 OMITS body — takeaway-only rows. Scan, then re-read one via ids.

Input Schema

TableJSON 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

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.34.0Aug 1, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so richly: it discloses that results are NOT ranked, are chronological oldest-first, that the window keeps the MOST-RECENT N so 'lately' reads the tail, and that default worktree scoping is PERMISSIVE rather than a boundary — enumerating the exact pass-through cases. This is precisely the kind of context annotations would otherwise have to supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the two highest-value facts (not ranked; prefer episode_handoff) and organizes the scoping caveats under a heading. It is dense and long, but nearly every sentence adds non-obvious semantics; only the Rows bullet is somewhat repeated in spirit by max_results.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, output-schema-backed retrieval tool with zero annotation and zero schema-description coverage, the description supplies everything needed to call it correctly: ordering semantics, scoping behavior, parameter reference, and sibling routing. Return values needn't be explained since an output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry all semantics, and it documents every one of the 8 parameters with defaults and effects: auto_scope's trade-off, max_results' default/cap, include_bodies omitting body, ids as an explicit never-worktree-filtered selector where unknown ids are absent rather than an error. It fully compensates for the empty schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Cross-session lookup for journal-shaped entries (episodes)') and immediately distinguishes itself from the sibling episode_handoff for the loop-iteration case. An agent can tell which retrieval tool to open without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative explicitly ('For the loop-iteration-entry case prefer episode_handoff, which auto-resolves the prior session and caps the surface') and gives a concrete workflow ('Scan, then re-read one via ids'). The when/when-not routing is explicit rather than inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server