bettermemory

Overview Schema Source Related Servers Discussions Admin

episode_promote

Promote a journal episode into a durable memory when its takeaway is worth keeping across sessions. Routes through memory_write checks for durability, dedup, and scope before committing.

Instructions

Promote a journal entry (episode) into a durable memory. Routes through memory_write — the durability gate, scope-mismatch detection, dedup, and user-inference confirmation flow all apply.

Use this when an iteration's takeaway turns out to be a fact worth keeping across sessions, not just a run-state note.

Loop/working state belongs in episodes; session close is when to promote the takeaways that hardened.

On successful commit the source episode is deleted (its content has been distilled). On pending (user-inference category), the source episode is held for memory_write_confirm to delete — memory_write_cancel keeps the episode so you can retry. On any other non-committed status (duplicate, previously_removed, transient_warning, scope_mismatch, ungrounded) the source episode is left untouched so you can adjust and re-promote.

Body default: when use_body=False (default), the durable memory's body is the episode's takeaway. Set use_body=True to use the full episode body. An episode with no takeaway requires use_body=True.

Returns the memory_write response shape plus promoted_from_episode_id, on every outcome.

Parameters:

episode_id: ULID of the source episode.
scopes: scopes for the durable memory. Required.
category (default 'fact'): memory category. user-inference still requires explicit user confirmation.
confidence (default 'medium'), source (default 'explicit-statement'): standard memory_write fields.
use_body=False: when True, use the episode's body instead of its takeaway.

Input Schema

TableJSON Schema

Name	Required	Default
`scopes`	Yes
`source`	No	explicit-statement
`category`	No	fact
`use_body`	No
`confidence`	No	medium
`episode_id`	Yes

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?

No annotations, so the description carries full burden and delivers: it discloses the side effect that the source episode is deleted on commit, and enumerates the exact status handling for every non-committed outcome (pending holds episode, duplicate/previously_removed/scope_mismatch/ungrounded leave it untouched). This is exactly the mutation/reversibility context an agent needs.

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

Conciseness5/5

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

Front-loads the core action, then layers routing, when-to-use, and outcome semantics in tight paragraphs. Every sentence earns its place; no padding despite the density of behavior covered.

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

Completeness4/5

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

The operation is complex (deletion side effects, multi-status outcomes, cross-tool routing), and the description covers nearly all of it, including return shape. One minor gap: it notes 'Returns the memory_write response shape' relying on the agent knowing that sibling, though an output schema exists so return-value detail is not required.

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. It documents every meaningful parameter: what episode_id is, that scopes is required, category defaults and the user-inference confirmation constraint, confidence/source defaults, and critically the use_body default and the edge case that an episode with no takeaway requires use_body=True.

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+resource ('Promote a journal entry (episode) into a durable memory') and immediately distinguishes it from siblings by naming the underlying route (memory_write) and the loop-state sibling concept (episodes). An agent can tell this apart from episode_write and memory_write without opening 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?

Gives explicit when-to-use ('when an iteration's takeaway turns out to be a fact worth keeping across sessions, not just a run-state note') and when-not ('Loop/working state belongs in episodes; session close is when to promote'). Also names alternatives (memory_write_confirm, memory_write_cancel) with the conditions that select them.

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

Deploy Server