openmem-mcp

Overview Schema Source Related Servers Discussions Admin

Search this session's stored context

smart_compact_search

Read-onlyIdempotent

Search every stored message in a session, including trimmed context, by full-text query or regex. Returns matching rows with excerpts and exact match counts for recall and counting questions.

Instructions

Search every stored message of this session, including messages trimmed from your context, and return matching rows with an excerpt. Use it when an [openmem: continuing session …] pointer says earlier messages were trimmed; pass that session_id (without one it searches recent sessions in this git root). Pass exactly one of query (full-text words) or pattern (regex). Roles default to user and tool. total_matches counts rows; line_matches is an exact count of matching lines across the whole session; use it for 'how many' questions, or smart_compact_sql for grouped counts. Rows citing a compressed result return blob_ids for smart_compact_get.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "smart_compact_search"
  }
}

Input Schema

Name	Required	Description
`mode`	No	hybrid merges full-text and embedding rankings (default when the session has vectors); lexical is full-text only
`role`	No	Roles to search: "user", "assistant", "tool", a list of them, or "all" (default ["user", "tool"])
`limit`	No	Max rows (default 8)
`query`	No	Words to find (case-insensitive whole words; rows with more words rank first). Omit when passing pattern
`context`	No	Neighbouring rows of the same conversation to return before and after each hit, 0-5 (default 0)
`pattern`	No	JavaScript regex source, at most 200 characters; tested against each row's first 20000 characters and against every line. Omit when passing query
`in_context`	No	true: only rows still in your context; false: only trimmed rows (default both)
`session_id`	No	Session id from the [openmem: continuing session …] pointer
`ignore_case`	No	Match pattern case-insensitively (default false)

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.8.0Oct 31, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior: it reaches into trimmed messages, falls back to recent sessions in the git root when session_id is absent, and distinguishes total_matches (rows) from line_matches (exact line count) for 'how many' questions.

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 purpose then trigger, and nearly every clause carries new information. Minor redundancy in restating role defaults that the schema already declares, and the single dense paragraph packs several distinct concerns together.

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?

With 9 optional parameters and no output schema, the description covers the trigger, mutual exclusivity, counting semantics, and the blob_id handoff to smart_compact_get — enough for an agent to call it correctly and interpret results without further probing.

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 a cross-parameter constraint the schema does not state as such ('exactly one of query or pattern') and the session_id fallback semantics ('without one it searches recent sessions in this git root'). The role defaults are repeated from the schema rather than added to.

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 ('search every stored message of this session') plus a distinguishing scope ('including messages trimmed from your context') and the return shape ('matching rows with an excerpt'). It separates itself from smart_compact_sql and smart_compact_get by naming when each applies.

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 trigger ('use it when an [openmem: continuing session …] pointer says earlier messages were trimmed'), an alternative for aggregation ('or smart_compact_sql for grouped counts'), and an exclusion rule ('pass exactly one of query or pattern').

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