bettermemory

Overview Schema Source Related Servers Discussions Admin

memory_write

Create durable memories for coding agents, validating claims against the filesystem and git to flag stale or ungrounded facts.

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. Always returns {status:'pending', pending_id} regardless of config — ask the user in plain language, then memory_write_confirm or memory_write_cancel. Misattribution sticks; user gets the veto.
- 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 (the user gets the veto) or pass acknowledge_user_claim=True if the subject is someone else.
pending — category='user-inference' or require_write_confirmation. pending_reason distinguishes.
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, the description carries the full burden and disloses extensively: commit vs pending vs duplicate statuses, gate rejects and override remedies, user-inference veto, the grounding gate, supersedes linking, and the one-shot curation_hint. It also frames expected failures as safe: 'the gates below catch bad writes.'

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 front-loaded with core purpose and structured into parameter bullets and return-status bullets, making dense information navigable. Some gate detail is restated in statuses, but the length is justified for a 15-parameter write tool with no annotations.

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 a high-complexity mutation tool with no annotations, this covers invocation timing, parameter semantics, refusal modes, override flags, return statuses, and post-write curation. Even though an output schema exists, the extra status documentation removes ambiguity; nothing critical for correct invocation is missing.

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%, and the description compensates with rich meaning for nearly every parameter: content, scopes usage, category enum semantics, confidence/source, claims syntax, groundedness_check/source_transcript, supersedes, and the acknowledge/force overrides. This goes well beyond the schema's type/default information.

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?

Opens with 'Create a new memory' – a specific verb+resource that clearly distinguishes this from memory_update (modify) and memory_write_confirm/cancel (pending-write lifecycle). The first line also frames proactive use: 'Call PROACTIVELY when something durable enters the conversation.'

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?

Gives clear when-to-use guidance: 'Call PROACTIVELY when something durable enters the conversation' and 'agressive writing is safe.' It also gives scoping advice like avoiding the catch-all 'general'. It does not explicitly say when NOT to use memory_write in favor of memory_update or memory_show, though 'Create a new memory' and the supersedes semantics imply the boundary.

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

Deploy Server