M3 Memory

Overview Schema Source Related Servers Discussions Admin

memory_supersede

Replace a specific memory by full UUID with a new version, or retire it into an existing active memory to clean duplicates; the old memory is closed, not deleted.

Instructions

Replace one specific memory, by its full id, with a new version. Use it when you know which memory a new fact replaces; memory_write's automatic contradiction check may link the wrong one or none. Non-destructive: the old memory is closed, not deleted (still retrievable by id, in memory_history and in as_of search, linked new -> old by a 'supersedes' edge); it only leaves default search. Pass content to create the successor (type, title, importance and scope you omit are inherited), or replacement_id (a full UUID) to retire old_id into an EXISTING active memory without creating one: the way to clean up duplicates. Exactly one of the two. old_id must be the full UUID; a prefix is rejected (full UUID required for mutation safety; memory_get accepts a prefix). To remove a memory use memory_delete.

Input Schema

Name	Required	Description	Default
`type`	No	Memory type of the replacement. Omit to inherit the old memory's type. One of: auto, belief, chat_log, code, config, conversation, decision, event_extraction, fact, fact_enriched, home, home_automation, infrastructure, knowledge, linux_only, local_device, log, macos_only, message, migration-log, network_config, note, observation, plan, preference, procedure, reference, scratchpad, security, session_note, session_summary, snippet, summary, synthesis, task, to_do, user_fact, windows_only.
`embed`	No	Embed the replacement for semantic search.
`scope`	No	Isolation scope of the replacement. Omit to inherit the old memory's scope.
`store`	No	Named store for this call only: main, or a [stores.<name>] in m3_config.toml.
`title`	No	Title of the replacement. Omit to inherit the old memory's title.
`old_id`	Yes	FULL UUID of the memory being superseded (not an 8-char prefix — a prefix is rejected for mutation safety). Must exist and not already be deleted/superseded.
`source`	No	Provenance tag.	agent
`content`	No	Body of the NEW replacement memory (max 50000 chars). Omit when passing replacement_id.
`timeout`	No	Per-call timeout in seconds; <=0 disables.
`user_id`	No	Data subject id.
`variant`	No	Pipeline identifier for A/B variant tracking.
`agent_id`	No	Owning agent id. Injected by the orchestrator.
`database`	No	SQLite file for this call only (legacy; prefer store). SQLite backend only.
`metadata`	No	JSON-encoded metadata object for the replacement.	{}
`model_id`	No	Originating model id.
`embed_text`	No	Override text used for embedding; falls back to content when empty.
`importance`	No	0.0-1.0 relevance of the replacement. Omit (leave at -1) to inherit the old memory's importance.
`valid_from`	No	ISO-8601 validity start of the replacement; also the point at which the old memory's validity is closed. Defaults to now.
`change_agent`	No	Agent causing the supersede (audit).
`replacement_id`	No	FULL UUID of an EXISTING active memory to retire old_id into; nothing is created. Mutually exclusive with content.

Schema Changelog

Changes observed during successful MCP inspections.

Changed43 schema fields changedv0.1.21Oct 22, 2026

addedInput schema / properties / agent_id / description

Added value: +"Owning agent id. Injected by the orchestrator."

removedInput schema / properties / agent_id / title
```
Removed value: -"Agent Id"
```
addedInput schema / properties / change_agent / description
```
Added value: +"Agent causing the supersede (audit)."
```
removedInput schema / properties / change_agent / title
```
Removed value: -"Change Agent"
```
addedInput schema / properties / content / default
```
Added value: +""
```

addedInput schema / properties / content / description

Added value: +"Body of the NEW replacement memory (max 50000 chars). Omit when passing replacement_id."

removedInput schema / properties / content / title
```
Removed value: -"Content"
```
removedInput schema / properties / database / default
```
Removed value: -""
```

addedInput schema / properties / database / description

Added value: +"SQLite file for this call only (legacy; prefer store). SQLite backend only."

removedInput schema / properties / database / title
```
Removed value: -"Database"
```

addedInput schema / properties / embed / description

Added value: +"Embed the replacement for semantic search."

removedInput schema / properties / embed / title
```
Removed value: -"Embed"
```

addedInput schema / properties / embed_text / description

Added value: +"Override text used for embedding; falls back to content when empty."

removedInput schema / properties / embed_text / title
```
Removed value: -"Embed Text"
```

addedInput schema / properties / importance / description

Added value: +"0.0-1.0 relevance of the replacement. Omit (leave at -1) to inherit the old memory's importance."

removedInput schema / properties / importance / title
```
Removed value: -"Importance"
```

addedInput schema / properties / metadata / description

Added value: +"JSON-encoded metadata object for the replacement."

removedInput schema / properties / metadata / title
```
Removed value: -"Metadata"
```
addedInput schema / properties / model_id / description
```
Added value: +"Originating model id."
```
removedInput schema / properties / model_id / title
```
Removed value: -"Model Id"
```

addedInput schema / properties / old_id / description

Added value: +"FULL UUID of the memory being superseded (not an 8-char prefix — a prefix is rejected for mutation safety). Must exist and not already be deleted/superseded."

removedInput schema / properties / old_id / title
```
Removed value: -"Old Id"
```

addedInput schema / properties / replacement_id

Added value: +{
+  "default": "",
+  "description": "FULL UUID of an EXISTING active memory to retire old_id into; nothing is created. Mutually exclusive with content.",
+  "type": "string"
+}

addedInput schema / properties / scope / description

Added value: +"Isolation scope of the replacement. Omit to inherit the old memory's scope."

removedInput schema / properties / scope / title
```
Removed value: -"Scope"
```
addedInput schema / properties / source / description
```
Added value: +"Provenance tag."
```
removedInput schema / properties / source / title
```
Removed value: -"Source"
```

addedInput schema / properties / store

Added value: +{
+  "description": "Named store for this call only: main, or a [stores.<name>] in m3_config.toml.",
+  "type": "string"
+}

removedInput schema / properties / timeout / default
```
Removed value: -30
```

addedInput schema / properties / timeout / description

Added value: +"Per-call timeout in seconds; <=0 disables."

removedInput schema / properties / timeout / title
```
Removed value: -"Timeout"
```

addedInput schema / properties / title / description

Added value: +"Title of the replacement. Omit to inherit the old memory's title."

removedInput schema / properties / title / title
```
Removed value: -"Title"
```

addedInput schema / properties / type / description

Added value: +"Memory type of the replacement. Omit to inherit the old memory's type. One of: auto, belief, chat_log, code, config, conversation, decision, event_extraction, fact, fact_enriched, home, home_automation, infrastructure, knowledge, linux_only, local_device, log, macos_only, message, migration-log, network_config, note, observation, plan, preference, procedure, reference, scratchpad, security, session_note, session_summary, snippet, summary, synthesis, task, to_do, user_fact, windows_only."

removedInput schema / properties / type / title
```
Removed value: -"Type"
```
addedInput schema / properties / user_id / description
```
Added value: +"Data subject id."
```
removedInput schema / properties / user_id / title
```
Removed value: -"User Id"
```

addedInput schema / properties / valid_from / description

Added value: +"ISO-8601 validity start of the replacement; also the point at which the old memory's validity is closed. Defaults to now."

removedInput schema / properties / valid_from / title
```
Removed value: -"Valid From"
```

addedInput schema / properties / variant / description

Added value: +"Pipeline identifier for A/B variant tracking."

removedInput schema / properties / variant / title
```
Removed value: -"Variant"
```

changedInput schema / required

Previous value: -[
-  "old_id",
-  "content"
-]New value: +[
+  "old_id"
+]

removedInput schema / title

Removed value: -"memory_supersedeArguments"

Addedv0.1.9Jul 28, 2026
Removedv0.1.7Jul 27, 2026
Changed1 schema field changedv0.1.2Jul 6, 2026
- addedInput schema / properties / timeout
```
Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
```
First observedv0.1.0Jun 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare destructiveHint=false, and the description substantiates why: the old memory is closed, not deleted, remains retrievable by id, in memory_history, and as_of search, with a 'supersedes' edge. Adds rich context (mutation-safety UUID rule, inheritance defaults) well beyond the annotations.

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 the core action and when-to-use, then the non-destructive semantics, then the content/replacement_id branch. Dense semicolon-heavy paragraph is efficient though bordering on long; nearly every clause earns its place.

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 20-parameter mutation tool with no output schema, the description covers the key decision points an agent needs: which sibling to use, mutual exclusivity, inheritance defaults, and non-destructive outcomes. Nothing critical is missing.

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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: exactly-one-of content/replacement_id, inheritance of omitted fields, the cleanup-duplicates use of replacement_id, and the full-UUID vs prefix rule. Slightly redundant with schema notes on mutual exclusivity but net additive.

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 (replace/supersede) and resource (one specific memory, by full id) with a new version. Explicitly distinguishes from memory_write's automatic contradiction check, so an agent can tell the two apart.

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 an explicit when-to-use condition ('when you know which memory a new fact replaces') and a when-not/alternative ('memory_write's automatic contradiction check may link the wrong one or none'), plus routing to memory_delete for removal. Nothing left 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

memory_supersede

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools