Skip to main content
Glama
MontyGovernance

memocat-mcp

by MontyGovernance
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Search Memories

montycat_semantic_search
Read-onlyIdempotent

Search stored memories by meaning, keyword, or both, returning top-ranked matches with relevance scores to recall facts and context for RAG and agent memory.

Instructions

Search stored memory by MEANING, by KEYWORD, or both.

Use this to recall relevant facts, documents, or past context for RAG and agent memory. Returns the top matches ranked by relevance, each with its key, a score, and the stored value.

Ranking modes (mode):

  • "semantic" (default) — vector similarity. Finds a memory whose wording differs from the query. Scores are cosine similarity in [-1, 1].

  • "keyword" — BM25 over the stored text. Use it when the query contains an exact term that must appear: an identifier, error code, or file name. BM25 scores are unbounded and comparable only within one query.

  • "hybrid" — runs both and fuses them with reciprocal rank fusion. The safest default when a query mixes meaning with an exact term. Scores are normalized to [0, 1]. Keyword and hybrid need a Montycat Semantic engine >= 1.3.4; older engines reject the request rather than silently returning semantic-only results.

Narrowing is separate from ranking: filters, since, and until restrict WHICH memories are ranked — a hard AND over indexed fields — and never change the order within that set. Combine them freely: "what did we decide about the index" + since yesterday + filters={"project": "montycat"} is one call. A filter matching nothing returns [].

Args: query: Natural-language description of what to recall. May be empty when vector supplies a precomputed query embedding. mode: Ranking strategy — "semantic", "keyword", or "hybrid". vector: Optional precomputed query embedding, for the vector half of "semantic" and "hybrid". It must match the keyspace's enrolled embedding space and dimensions; when set, the engine does not embed query. scope: Owner/user id to scope recall to (searches only that owner's memory, keyspace mem_). Use "shared" for the common keyspace. keyspace: Explicit keyspace override (advanced; bypasses scope). limit: Max number of results (default 5). min_score: Optional relevance floor; drops weak matches. The valid range follows the mode: [-1, 1] semantic, [0, 1] hybrid, >= 0 keyword. filters: Optional metadata constraints, e.g. {"project": "x"} — only memories whose indexed fields equal these values are ranked. timestamp_field: Native Timestamp index field to constrain, e.g. "event_time". Defaults to the auto-stamped "_created_at". Use the index field name, not "timestamps.event_time". The field must be stored as a Timestamp index; an ordinary JSON string field is not sufficient. since: Lower time bound for timestamp_field (ISO-8601, UTC). until: Upper time bound for timestamp_field (ISO-8601, UTC). Bounds use the SDK's native Timestamp after/before/range queries. Do not also put timestamp_field in filters when supplying bounds.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNosemantic
limitNo
queryNo
scopeNo
sinceNo
untilNo
vectorNo
filtersNo
keyspaceNo
min_scoreNo
timestamp_fieldNo_created_at

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.1.3
    • addedInput schema / properties / timestamp_field
      Added value: +{
+  "default": "_created_at",
+  "title": "Timestamp Field",
+  "type": "string"
+}
  2. Changed1 schema field changedv1.1.2
    • addedInput schema / properties / mode
      Added value: +{
+  "default": "semantic",
+  "title": "Mode",
+  "type": "string"
+}
  3. Addedv1.0.0

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the read-only and idempotent annotations, the description discloses engine-version rejection behavior, score ranges and semantics per mode, that narrowing filters never affect ranking order, that an empty filter result returns [], and that supplying a vector bypasses query embedding. These behavioral details cannot be inferred from the annotations and materially help the agent anticipate edge cases.

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 well structured: a purpose sentence, ranked-mode explanation, narrowing semantics, then an Args list. There is mild redundancy, such as repeating score ranges in the mode prose and again under min_score, but every section earns its place given the tool's complexity and the schema's lack of descriptions.

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 an 11-parameter tool with no output schema and no enums, the description is remarkably complete: it specifies return contents (key, score, stored value), all valid score ranges, engine compatibility, timestamp indexing requirements, and edge cases like empty queries with vectors and empty filter results. An agent has enough information to call the tool correctly without external documentation.

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

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the Args section carries the full burden and succeeds: all 11 parameters receive meaning, defaults, constraints, and cross-dependencies, such as 'query may be empty when vector supplies a precomputed query embedding' and 'timestamp_field must be stored as a Timestamp index.' This goes far beyond the schema's bare types and titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb ('Search'), a resource ('stored memory'), and two retrieval strategies, so an agent immediately knows what the tool does. It does not explicitly contrast the tool with siblings like montycat_recall or montycat_list_memories, so differentiation relies on implied semantics rather than direct comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('Use this to recall relevant facts, documents, or past context for RAG and agent memory') and gives mode-selection guidance, such as using keyword mode for exact identifiers, error codes, or file names. It lacks explicit 'when not to use this tool' guidance or named alternatives, so it stops short of a perfect score.

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

Deploy Server

Other Tools