bettermemory

Overview Schema Source Related Servers Discussions Admin

episode_write

Record session journal entries for transient run-state, blockers, and iteration takeaways that durable fact storage rejects, then surface them via handoff or search.

Instructions

Append a journal-shaped entry for the current session — for run-state, iteration takeaways, 'what we tried'. Episodes are NOT durable facts; the durability gate that rejects transient memory_write content (TRANSIENT_PHRASE_MARKERS) does not apply here. Stored at /episodes//.md with a default 30-day TTL.

Use this for content memory_write would reject as transient:

'iteration N tried X, fell over at step 3'
'currently blocked on Y; next step is Z'
'this branch's release plan' (state that changes weekly)

Episodes are invisible to memory_search / memory_health / memory_list — they are a sibling tier, not a memory category. Surface them via episode_handoff at iteration entry or episode_search for cross-session lookup. Promote a takeaway to durable memory via episode_promote (routes through memory_write, durability gate fires as normal).

Parameters:

body: free-form markdown. Required, non-empty. Capped by max_content_bytes (default 1 MB).
swarm_id (optional): cohort id for multi-agent fan-in — a sub-agent passes the coordinator's session id so the coordinator can gather every sub-agent's takeaways via episode_search(swarm_id=…). A cross-cutting label, not a move: the episode still lives under this writer's own session, and it is distinct from episode_handoff's predecessor link.
takeaway (optional): one-sentence summary. Surfaced preferentially at episode_handoff; when None, handoff falls back to the first line of body. Capped by max_takeaway_bytes (default 4 KB).
scopes (optional): list of scope tags. Empty list is valid (handoff keys on session_id, not scope). Capped by max_scopes_per_write (default 64).

Both caps guard one thing: takeaway and scopes serialise into the YAML frontmatter (64 KB ceiling), so an over-cap value corrupts the file and the episode vanishes from every read surface despite the write returning committed.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`body`	Yes
`scopes`	No
`swarm_id`	No
`takeaway`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

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 burden and does so richly: default 30-day TTL, exact storage path (<root>/episodes/<session_id>/<ulid>.md), the 'committed' return value, and the critical failure mode where an over-cap value corrupts frontmatter and silently removes the episode from every read surface. That hidden-failure disclosure is exactly the kind of context an agent cannot infer.

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-loaded with purpose and usage before parameter detail, and the bulleted parameter block is easy to scan. It is long, and the closing paragraph on caps slightly restates the per-parameter cap notes, but nearly every sentence carries distinct information.

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?

An output schema exists, so return values need not be explained, yet the description still notes the 'committed' status. Combined with the tier model, TTL, storage location, and cap-failure caveat, an agent has everything needed to invoke this correctly and interpret the result.

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 compensate, and it documents all four parameters thoroughly — including subtle semantics like swarm_id being a cross-cutting label rather than a move, empty scopes being valid, the takeaway fallback to body's first line, and per-parameter caps. This goes well beyond a restatement of field names.

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 ('Append a journal-shaped entry for the current session') and immediately positions it as a distinct tier, explicitly contrasting with memory_write ('Episodes are NOT durable facts'). It also names sibling alternatives (episode_handoff, episode_search, episode_promote) so an agent can differentiate without opening any schema.

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?

Explicitly says when to use it ('content memory_write would reject as transient') and reinforces with three concrete examples of qualifying content. It also states what it is not (invisible to memory_search/memory_health/memory_list) and routes each adjacent need to the right sibling tool.

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

Deploy Server