M3 Memory

Overview Schema Source Related Servers Discussions Admin

memory_search

Read-only

Search memories by meaning and keywords using hybrid, semantic, or keyword modes; filter results by type, agent, user, scope, or conversation, and retrieve past states with time-travel queries.

Instructions

Find memories by meaning and keywords: hybrid by default; search_mode semantic (vector only) or keyword (lexical only). Returns the top k matches, ranked, with their ids; grade the ones you use with memory_grade. Narrow with type_filter, agent_filter, user_id, scope or conversation_id; as_of searches the store as it was at a past time. Use chatlog_search for captured chat turns and files_search for indexed files.

Input Schema

Name	Required	Description	Default
`k`	No	Max results (1-100).
`as_of`	No	ISO-8601 time-travel cutoff.
`query`	Yes	Search query.
`scope`	No	Filter by isolation scope.
`store`	No	Named store for this call only: main, or a [stores.<name>] in m3_config.toml.
`explain`	No	Attach a per-result `_explanation` block (vector/bm25/title_overlap/importance/recency/temporal score breakdown) plus a human-readable `reason` string explaining why each row matched. Same breakdown memory_suggest shows, on the primary search path.
`timeout`	No	Per-call timeout in seconds; <=0 disables.
`user_id`	No	Filter by data subject.
`variant`	No	Ingest-pipeline filter. '' = real user data only (default, equivalent to IS NULL). Pass a specific variant name (e.g. 'heuristic_c1c4') to scope to that bench ingest.
`database`	No	SQLite file for this call only (legacy; prefer store). SQLite backend only.
`adaptive_k`	No	Auto-trim results at the score drop-off point. WARNING: regresses on temporal-reasoning, knowledge-update, and multi-session queries; safe only for sharp-curve queries where most retrievals would be noise. Prefer `auto_route=True` on memory_search_routed for safer multi-signal routing.
`as_records`	No	Return structured records (JSON) instead of the display string. Default false keeps the human-readable output unchanged.
`search_mode`	No	Retrieval mode.	hybrid
`type_filter`	No	Restrict to a memory type.
`agent_filter`	No	Restrict to an agent id.
`recency_bias`	No	Boost newer items (0.0=off, 0.1-0.2=moderate, higher=aggressive). Useful for 'current' or 'latest' queries.
`conversation_id`	No	Restrict to a conversation / team session.
`requesting_agent`	No	Calling agent's id. When set, ENFORCES cross-agent isolation: private (scope='agent') rows from OTHER agents are excluded; the caller still sees its own private rows plus all shared scopes (org/user/session). Empty = no enforcement (sees all, back-compat).
`include_bench_data`	No	Opt in to LOCOMO / LongMemEval bench rows. Default False hides any row with a variant tag.
`include_scratchpad`	No	Include ephemeral scratchpad items.

Schema Changelog

Changes observed during successful MCP inspections.

Changed43 schema fields changedv0.1.21Oct 22, 2026

addedInput schema / properties / adaptive_k / description

Added value: +"Auto-trim results at the score drop-off point. WARNING: regresses on temporal-reasoning, knowledge-update, and multi-session queries; safe only for sharp-curve queries where most retrievals would be noise. Prefer `auto_route=True` on memory_search_routed for safer multi-signal routing."

removedInput schema / properties / adaptive_k / title
```
Removed value: -"Adaptive K"
```
addedInput schema / properties / agent_filter / description
```
Added value: +"Restrict to an agent id."
```
removedInput schema / properties / agent_filter / title
```
Removed value: -"Agent Filter"
```
addedInput schema / properties / as_of / description
```
Added value: +"ISO-8601 time-travel cutoff."
```
removedInput schema / properties / as_of / title
```
Removed value: -"As Of"
```

addedInput schema / properties / as_records / description

Added value: +"Return structured records (JSON) instead of the display string. Default false keeps the human-readable output unchanged."

removedInput schema / properties / as_records / title
```
Removed value: -"As Records"
```
addedInput schema / properties / conversation_id / description
```
Added value: +"Restrict to a conversation / team session."
```
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 / explain / description

Added value: +"Attach a per-result `_explanation` block (vector/bm25/title_overlap/importance/recency/temporal score breakdown) plus a human-readable `reason` string explaining why each row matched. Same breakdown memory_suggest shows, on the primary search path."

removedInput schema / properties / explain / title
```
Removed value: -"Explain"
```

addedInput schema / properties / include_bench_data / description

Added value: +"Opt in to LOCOMO / LongMemEval bench rows. Default False hides any row with a variant tag."

removedInput schema / properties / include_bench_data / title
```
Removed value: -"Include Bench Data"
```
addedInput schema / properties / include_scratchpad / description
```
Added value: +"Include ephemeral scratchpad items."
```
removedInput schema / properties / include_scratchpad / title
```
Removed value: -"Include Scratchpad"
```
addedInput schema / properties / k / description
```
Added value: +"Max results (1-100)."
```
removedInput schema / properties / k / title
```
Removed value: -"K"
```
addedInput schema / properties / query / description
```
Added value: +"Search query."
```
removedInput schema / properties / query / title
```
Removed value: -"Query"
```

addedInput schema / properties / recency_bias / description

Added value: +"Boost newer items (0.0=off, 0.1-0.2=moderate, higher=aggressive). Useful for 'current' or 'latest' queries."

removedInput schema / properties / recency_bias / title
```
Removed value: -"Recency Bias"
```

addedInput schema / properties / requesting_agent / description

Added value: +"Calling agent's id. When set, ENFORCES cross-agent isolation: private (scope='agent') rows from OTHER agents are excluded; the caller still sees its own private rows plus all shared scopes (org/user/session). Empty = no enforcement (sees all, back-compat)."

removedInput schema / properties / requesting_agent / title
```
Removed value: -"Requesting Agent"
```
addedInput schema / properties / scope / description
```
Added value: +"Filter by isolation scope."
```
removedInput schema / properties / scope / title
```
Removed value: -"Scope"
```
addedInput schema / properties / search_mode / description
```
Added value: +"Retrieval mode."
```

addedInput schema / properties / search_mode / enum

Added value: +[
+  "hybrid",
+  "semantic",
+  "keyword"
+]

removedInput schema / properties / search_mode / title
```
Removed value: -"Search Mode"
```

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 / type_filter / description
```
Added value: +"Restrict to a memory type."
```
removedInput schema / properties / type_filter / title
```
Removed value: -"Type Filter"
```
addedInput schema / properties / user_id / description
```
Added value: +"Filter by data subject."
```
removedInput schema / properties / user_id / title
```
Removed value: -"User Id"
```

addedInput schema / properties / variant / description

Added value: +"Ingest-pipeline filter. '' = real user data only (default, equivalent to IS NULL). Pass a specific variant name (e.g. 'heuristic_c1c4') to scope to that bench ingest."

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

removedInput schema / title

Removed value: -"memory_searchArguments"

Changed1 schema field changedv0.1.20Sep 15, 2026

addedInput schema / properties / as_records

Added value: +{
+  "default": false,
+  "title": "As Records",
+  "type": "boolean"
+}

Addedv0.1.9Jul 28, 2026
Removedv0.1.7Jul 27, 2026

Changed3 schema fields changedv0.1.2Jul 6, 2026

addedInput schema / properties / explain

Added value: +{
+  "default": false,
+  "title": "Explain",
+  "type": "boolean"
+}

addedInput schema / properties / requesting_agent

Added value: +{
+  "default": "",
+  "title": "Requesting Agent",
+  "type": "string"
+}

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: ranked top-k results with ids, time-travel semantics for as_of, and the adaptive_k warning about regressing on temporal/multi-session queries. It stops short of covering output format details or any authentication/limit behavior, but it substantially enriches the annotated safety profile.

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?

The description is a tight, front-loaded paragraph: the primary capability and default mode come first, then filters, then alternatives. Every sentence carries actionable information despite the large parameter surface, with no filler.

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 20-parameter search tool with no output schema, the description covers the essential calling context: default behavior, mode selection, key filters, return shape (ranked top-k with ids), and sibling alternatives. It leaves niche parameters (include_bench_data, include_scratchpad, store/database, variant) to the schema, which is reasonable given the high schema coverage, though an agent must still consult the schema for those.

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; the description adds value by explaining the meaning of the search_mode enum (semantic = vector only, keyword = lexical only, hybrid default), the purpose of the narrowing filters (type_filter, agent_filter, user_id, scope, conversation_id), and as_of as a past-time snapshot. It does not explain every one of the 20 parameters, but it adds useful semantics beyond the schema for the most decision-relevant ones.

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 opens with a specific verb and resource ('Find memories') and immediately clarifies the default retrieval mode (hybrid) plus the two alternatives (semantic, keyword). It explicitly differentiates itself from chatlog_search and files_search, so an agent can select it without opening the 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?

It gives explicit routing guidance: use chatlog_search for captured chat turns and files_search for indexed files, and use search_mode to choose vector vs lexical vs hybrid. It also describes the follow-up workflow ('grade the ones you use with memory_grade') and when as_of is appropriate (searching the store as it was at a past time).

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

Deploy Server

memory_search

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools