bettermemory

Overview Schema Source Related Servers Discussions Admin

memory_write

Create durable memories with validation: store facts, user inferences, and ambient context, checking claims against the worktree and grounding to avoid stale or ungrounded entries.

Instructions

Create a new memory. Call PROACTIVELY when something durable enters the conversation — aggressive writing is safe; the gates below catch bad writes.

Parameters:

content: the memory body.
scopes: non-empty list. Avoid the catch-all 'general'; prefer narrow tags like tools, infrastructure, projects:<name>.
category (default 'fact'): one of fact, user-inference, ambient.
- fact: project / infra / reference / tooling. Commits immediately (unless require_write_confirmation).
- user-inference: claims ABOUT THE USER. Commits like fact; the label keeps an inference distinguishable from an established fact, and correctable.
- ambient: context that shapes replies without being cited. Commits like fact, excluded from dead-weight curation; a body over 500 words gets a non-blocking ambient_body_long warning.
confidence ('low' / 'medium' / 'high'), source ('explicit-statement' / 'inferred').
claims (optional): claims the body makes about this repo — path, path::symbol, path::NAME=literal, !path (absent). Checked against the worktree NOW (false ⇒ refused); drift watches the claimed bindings, not whole files. Declare when citing code.
groundedness_check=True + source_transcript: optional gate. Sentences with <30% token overlap to the transcript return {status:'ungrounded', claims:[…]}. Override via acknowledge_ungrounded=True when grounding came from outside the transcript (file reads, tool results).
supersedes (optional): ids of active memories this write replaces (each gets a supersedes link, superseded_by on the stale hit). Also set unasked when a claim-sized body updates a stored claim — a change cue plus a diverging value; with no cue the pair is filed for memory_conflicts.

Return statuses:

committed — write succeeded; payload carries the new id, related matches, and any supersedes / conflicts_filed rows.
duplicate — content dedup fired; the matched memory is credited a corroboration (corroboration_recorded: true, once per session); the hint carries the remedy.
transient_warning / credential_warning / previously_removed / scope_mismatch — gate rejects; each returns what matched and a hint with the remedy and its acknowledge_* / force=True override.
user_claim_warning — the body reads as a claim ABOUT THE USER but category isn't user-inference. Re-issue as that or pass acknowledge_user_claim=True if the subject is someone else.
pending — require_write_confirmation is on (any category); memory_write_confirm or memory_write_cancel.
ungrounded — groundedness gate fired.

A committed or confirm response may carry a one-shot per-session curation_hint block ({pressure, threshold, counts, message}) when curation pressure (dead_weight + drifted + cold_endorsement_memories) crosses the configured threshold; memory_health has the full buckets.

Input Schema

TableJSON Schema

Name	Required	Default
`force`	No
`claims`	No
`scopes`	Yes
`source`	No	explicit-statement
`content`	Yes
`category`	No	fact
`confidence`	No	medium
`supersedes`	No
`source_transcript`	No
`groundedness_check`	No
`acknowledge_transient`	No
`acknowledge_credential`	No
`acknowledge_ungrounded`	No
`acknowledge_user_claim`	No
`acknowledge_scope_mismatch`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv7.4.0Sep 5, 2026

addedInput schema / properties / supersedes

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed1 schema field changedv3.40.0Aug 5, 2026

addedInput schema / properties / claims

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

First observedv3.34.0Aug 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden — and it is exhaustive. It discloses per-category commit behavior (fact vs ambient vs user-inference), the 500-word ambient warning, claim checking against the worktree (false ⇒ refused), the groundedness gate (<30% overlap ⇒ ungrounded), every return status with its remedy/override, dedup corroboration (once per session), and the one-shot curation_hint block. Nothing about side effects is hidden.

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?

The description is long, but every sentence earns its place for a 15-parameter tool with zero annotation support. It is well-structured and front-loaded: purpose and when-to-use first, then parameter semantics, then a status reference. It is dense, but the density is justified by the complexity rather than padding.

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?

Despite having an output schema, the description still enumerates all return statuses and their payloads, which an agent needs for correct branching. Given the tool's complexity (15 params, 6+ gate conditions, multiple overrides), the description is effectively complete — an agent could call this tool correctly with no other documentation.

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 does comprehensively. All 15 parameters are explained: scopes with the 'avoid the catch-all general' guidance, category with its three enumerated values and distinct behaviors, source/confidence, claims with syntax examples (path, path::symbol, !path), the groundedness_check/source_transcript pairing, supersedes linking semantics, and every acknowledge_* override and force mapped to its gate. No parameter is left unexplained.

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?

The opening line — 'Create a new memory. Call PROACTIVELY when something durable enters the conversation' — states a precise verb and resource, and immediately signals the tool's distinctive trigger (proactive durable-conversation events). It is clearly distinguished from siblings like memory_search, memory_update, and the confirm/cancel pair, which are named and routed to in the status section.

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

Usage Guidelines4/5

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

The description is explicit about when to call ('Call PROACTIVELY... aggressive writing is safe; the gates below catch bad writes'), encouraging liberal use. It routes to memory_write_confirm/cancel for pending writes and memory_health for curation buckets, and implicitly distinguishes write from update via the supersedes mechanism. It lacks an explicit 'use memory_update when...' exclusion, so it stops just short of full sibling differentiation.

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

Deploy Server