M3 Memory

Overview Schema Source Related Servers Discussions Admin

memory_write

Store a new fact as a persistent, searchable memory with semantic embedding. Closely matching conflicting entries are detected and superseded automatically, keeping recall accurate.

Instructions

Store a new memory and, by default, embed it for semantic search. For a new fact; to replace a specific memory whose id you know use memory_supersede, and to edit one in place memory_update. An embedded write is checked against existing memories of the same type from the same agent: if it closely matches one (cosine > 0.92 by default) but says something different, the old one is superseded automatically. type='auto' lets the LLM choose the type.

Input Schema

Name	Required	Description	Default
`type`	Yes	Memory 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 for semantic search.
`scope`	No	Isolation scope.	agent
`store`	No	Named store for this call only: main, or a [stores.<name>] in m3_config.toml.
`title`	No	Short title.
`source`	No	Provenance tag.	agent
`content`	Yes	Memory body (max 50000 chars).
`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.	{}
`model_id`	No	Originating model id.
`valid_to`	No	ISO-8601 validity end.
`embed_text`	No	Override text used for embedding; falls back to content when empty.
`importance`	No	0.0-1.0 relevance.
`refresh_on`	No	ISO-8601 timestamp when this memory should be flagged for review (lifecycle / planned obsolescence).
`valid_from`	No	ISO-8601 validity start.
`change_agent`	No	Agent causing the write (audit).
`auto_classify`	No	Let the LLM pick the type (forced true if type='auto').
`refresh_reason`	No	Why this memory needs refreshing (e.g., 'quarterly policy review').
`conversation_id`	No	Groups this memory with a conversation / team session. Same ID space as conversation_start.

Schema Changelog

Changes observed during successful MCP inspections.

Changed48 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 / auto_classify / description

Added value: +"Let the LLM pick the type (forced true if type='auto')."

removedInput schema / properties / auto_classify / title
```
Removed value: -"Auto Classify"
```
addedInput schema / properties / change_agent / description
```
Added value: +"Agent causing the write (audit)."
```
removedInput schema / properties / change_agent / title
```
Removed value: -"Change Agent"
```
addedInput schema / properties / content / description
```
Added value: +"Memory body (max 50000 chars)."
```
removedInput schema / properties / content / title
```
Removed value: -"Content"
```

addedInput schema / properties / conversation_id / description

Added value: +"Groups this memory with a conversation / team session. Same ID space as conversation_start."

removedInput schema / properties / conversation_id / title
```
Removed value: -"Conversation Id"
```
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 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."
```
removedInput schema / properties / importance / title
```
Removed value: -"Importance"
```
addedInput schema / properties / metadata / description
```
Added value: +"JSON-encoded metadata object."
```
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 / refresh_on / description

Added value: +"ISO-8601 timestamp when this memory should be flagged for review (lifecycle / planned obsolescence)."

removedInput schema / properties / refresh_on / title
```
Removed value: -"Refresh On"
```

addedInput schema / properties / refresh_reason / description

Added value: +"Why this memory needs refreshing (e.g., 'quarterly policy review')."

removedInput schema / properties / refresh_reason / title
```
Removed value: -"Refresh Reason"
```
addedInput schema / properties / scope / description
```
Added value: +"Isolation 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: +"Short title."
```
removedInput schema / properties / title / title
```
Removed value: -"Title"
```

addedInput schema / properties / type / description

Added value: +"Memory 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."
```
removedInput schema / properties / valid_from / title
```
Removed value: -"Valid From"
```
addedInput schema / properties / valid_to / description
```
Added value: +"ISO-8601 validity end."
```
removedInput schema / properties / valid_to / title
```
Removed value: -"Valid To"
```

addedInput schema / properties / variant / description

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

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

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.6/5.0

Behavior4/5

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

Discloses a non-obvious side effect annotations do not: an embedded write is deduplicated against same-type/same-agent memories and can automatically supersede one when cosine > 0.92. That is the key behavioral risk for a caller. It does not mention failure modes, whether supersede is reversible, or what is returned, keeping it short of a 5.

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?

Three sentences, front-loaded with the core action, then routing to alternatives, then the dedupe caveat. No sentence is redundant with the name or the schema.

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?

Covers purpose, routing, and the automatic-supersede side effect for a 23-parameter mutation tool. However, with no output schema, the description never says what the call returns (e.g., the new memory id needed for later supersede/update), which is a meaningful omission for a create tool.

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 real meaning: embed is on by default (and why), and type='auto' delegates type choice to the LLM. It does not explain scope/store interactions or the validity/refresh parameters, so it is a modest lift over the schema rather than a full one.

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 and resource ("Store a new memory") and immediately scopes it as a write plus default embedding. It explicitly names the two sibling tools it is not (memory_supersede, memory_update), so an agent can route without opening any schema.

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 selection rule: "For a new fact; to replace a specific memory whose id you know use memory_supersede, and to edit one in place memory_update." The when-to-use and the alternative-with-condition are both stated outright.

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

Deploy Server

memory_write

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools