bettermemory

Overview Schema Source Related Servers Discussions Admin

memory_update

Refine an existing memory in place to correct stored facts, preserving its ID, creation date, and source while refreshing its updated timestamp.

Instructions

Body edits clear last_verified_at; scope-only edits preserve it. Bundling a scope rename with a body edit clears verification.

Refine an existing memory in place. Preferred over memory_remove + memory_write when correcting a stored fact — preserves id, created, and source; bumps updated.

Parameters (pass at least one):

id: required.
content: new body. Replacing the body clears last_verified_at, the verified-* attestations, and claims (the prior verification was for prose that no longer exists; call memory_verify again after, re-declaring claims). A body that reads as a claim ABOUT THE USER returns user_claim_warning unless the record is already user-inference; pass acknowledge_user_claim=True if the subject is someone else. A transient-state body returns transient_warning; acknowledge_transient=True overrides. An edit that SHRINKS the body and leaves it ending mid-sentence returns truncation_warning; pass acknowledge_truncation=True when the cut is deliberate.
scopes / links: REPLACE semantics — pass the full new list, or [] to clear.
confidence: low / medium / high.
category: accepts fact and ambient. user-inference is REJECTED here — file a claim about the user with memory_write.

Returns status="stale" when another agent updated the memory first; the hint says to re-fetch and retry. Each links entry is {type, target_id (a ULID), note?}. The types: supersedes (prefer this over the target), contradicts (both cannot be true), extends (adds nuance to it), depends_on (only makes sense in its context). docs/api.md carries the rest.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes
`links`	No
`scopes`	No
`content`	No
`category`	No
`confidence`	No
`acknowledge_transient`	No
`acknowledge_credential`	No
`acknowledge_truncation`	No
`acknowledge_user_claim`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.1.0Aug 10, 2026
- addedInput schema / properties / acknowledge_transient
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
Changed2 schema fields changedv3.40.0Aug 5, 2026
- addedInput schema / properties / acknowledge_truncation
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
- addedInput schema / properties / acknowledge_user_claim
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```
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?

No annotations are provided, so the description carries the full disclosure burden and it discharges it thoroughly: body edits clear last_verified_at and verified-* attestations, scopes/links use destructive REPLACE semantics, three distinct warnings (user_claim, transient, truncation) are each explained with their override flags, and the stale-status race condition is disclosed. The only unaddressed behavior is the acknowledge_credential flag (present in schema, absent in description), which is minor against this breadth.

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 the highest-stakes behavioral caveat (verification clearing) before the purpose statement, then flows through parameters, warnings, and return behavior in a logical order. Every sentence carries substantive information for a 10-parameter tool with no annotations. Slightly verbose (the links-types block and docs pointer could be trimmed), but the density is justified by complexity.

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?

For a complex tool (10 params, no annotations, output schema present), the description covers the destructive side effects, replacement semantics, warning/override protocol, stale handling, and link semantics. The output schema covers return structure, so the status="stale" explanation is bonus context. The acknowledge_credential omission and the tail reference to 'docs/api.md carries the rest' leave small but real gaps; otherwise the agent has nearly everything needed to call correctly.

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

Parameters4/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 extensively: id, content, scopes/links (with REPLACE semantics and [] to clear), confidence (allowed values), category (fact/ambient, user-inference rejected), and three acknowledge flags are all semantically explained. Links entry format and the four type values are spelled out. One genuine gap: acknowledge_credential is in the schema but never mentioned, leaving an agent uninformed about that flag's behavior.

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 description states a specific verb and resource ('Refine an existing memory in place') and immediately differentiates the operation from a composite alternative: 'Preferred over memory_remove + memory_write when correcting a stored fact.' It also carves out a distinct scope for category, rejecting 'user-inference' and routing that to memory_write. An agent can tell this apart from memory_write, memory_verify, and memory_remove without ambiguity.

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 guidance ('Preferred over memory_remove + memory_write when correcting a stored fact') with the reason (preserves id/created/source, bumps updated), and an explicit when-not ('user-inference is REJECTED here — file a claim about the user with memory_write'). The condition for choosing this over siblings is stated directly, leaving nothing to inference.

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

Deploy Server