Skip to main content
Glama
Sign In
MemAI

MemAI

by Filipe-Soares-de-Almeida
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search

Read-onlyIdempotent

Retrieve stored memories by keyword across content, tags, and domains, returning ranked candidates annotated by match source and rank.

Instructions

Keyword search over memory content+tags+domain: FTS5 BM25.

Each result is annotated with match_source ("fts", or "uid" for the row a pasted identifier names) and fts_rank (bm25, lower = better). The search only widens the candidate set -- judge the returned candidates yourself.

Only active memories by default.

Returns {"results": [...], "est_tokens": N}. Content is snippet-truncated per result -- call get_memory(uid) for the full record; a result's est_tokens estimates what that full record costs, and the top-level est_tokens is the sum over the results.

Two annotations worth acting on. succeeded_by means something in the store supersedes this memory: read that one instead. collapsed lists near-identical results folded into this one, so a fact written five times spends one slot -- raise limit if you want the copies.

A memory marked confidence='contradicted' sorts behind everything that still holds, but it does come back: knowing a claim was ruled out is worth a slot, and it is what stops it being written again.

A diagram ranks like any other memory: it comes back when it matches the query, in the position its score earns. Nothing lifts a type to the top, so a flow in the results is a flow this query actually hit -- and when one does show up it is worth opening first, because it states a whole routine the surrounding notes only annotate.

To recall note()'d knowledge specifically, recall() is the sugar for search(type='note') -- which also means recall() never surfaces a diagram; use search() for that.

Input Schema

NameRequiredDescriptionDefault
typeNo'note', 'reasoning', 'checkpoint', 'anti_pattern', 'diagram', 'task' (one writer each) or 'handoff' (rows already stored; task() carries unfinished work to the next session); any other type is an error. Ask for type='diagram' to sweep the documented flows on purpose.
limitNothe most results to return.
queryYesthe words to look for. SPEND TERMS FREELY. Every space-separated term is asked for separately and a row matching more of them ranks higher, so piling on synonyms, the identifier, the routine name and the plain-language phrasing into one query costs one call and finds strictly more. Twenty terms beat ten. Write a sentence if that is what you have -- common words score near zero and cost nothing, so there is nothing to strip.
domainNoscopes to a path AND everything under it: domain='acme/x100' searches the module and each of its routines. Give more of the path to narrow it. A domain naming only the deep end of a path ('p200') is resolved to the branches it sits in -- every result carries its real `domain`, which is where to read what the filter actually covered.
offsetNowhere the page starts; `next_offset`, when present, starts the next.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.16.1
    • addedInput schema / properties / domain / description
      Added value: +"scopes to a path AND everything under it: domain='acme/x100' searches the module and each of its routines. Give more of the path to narrow it. A domain naming only the deep end of a path ('p200') is resolved to the branches it sits in -- every result carries its real `domain`, which is where to read what the filter actually covered."
    • removedInput schema / properties / domain / title
      Removed value: -"Domain"
    • addedInput schema / properties / limit / description
      Added value: +"the most results to return."
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "description": "where the page starts; `next_offset`, when present, starts the next.",
+  "type": "integer"
+}
    • addedInput schema / properties / query / description
      Added value: +"the words to look for. SPEND TERMS FREELY. Every space-separated term is asked for separately and a row matching more of them ranks higher, so piling on synonyms, the identifier, the routine name and the plain-language phrasing into one query costs one call and finds strictly more. Twenty terms beat ten. Write a sentence if that is what you have -- common words score near zero and cost nothing, so there is nothing to strip."
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • addedInput schema / properties / type / description
      Added value: +"'note', 'reasoning', 'checkpoint', 'anti_pattern', 'diagram', 'task' (one writer each) or 'handoff' (rows already stored; task() carries unfinished work to the next session); any other type is an error. Ask for type='diagram' to sweep the documented flows on purpose."
    • removedInput schema / properties / type / title
      Removed value: -"Type"
    • removedInput schema / title
      Removed value: -"searchArguments"
  2. Changed2 schema fields changedv0.1.1
    • changedInput schema / properties / limit / default
      Previous value: -30New value: +10
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "items": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "title": "Result",
-      "type": "array"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "searchOutput",
-  "type": "object"
-}New value: +null
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses that snippets are truncated and est_tokens estimates the full-record cost, explains succeeded_by and collapsed annotations, and details that confidence='contradicted' rows sort last but still return. None of this contradicts the annotations; it materially enriches them.

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 core purpose and return format are front-loaded and the result-annotation semantics are necessary given there is no output schema. It runs long (~350 words) with a few discursively framed sentences about why contradicted memories deserve a slot and how diagrams rank, but almost every sentence carries usable behavioral information.

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 no output schema, the description carries the full burden of explaining the return value, and it does: results array, est_tokens at both levels, snippet truncation, match_source, fts_rank, succeeded_by, collapsed, and ranking order. Nothing an agent needs to interpret or act on results 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 real meaning beyond the schema: it says the search only widens the candidate set and that the agent must judge candidates, and it links `limit` to the collapsed-duplicate behavior. It adds modest value on top of an already verbose schema rather than fully re-explaining syntax.

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 with implementation detail: 'Keyword search over memory content+tags+domain: FTS5 BM25.' It also distinguishes itself from siblings by naming recall() explicitly and clarifying that recall() is just search(type='note') and never surfaces diagrams. An agent can route between search, recall, list_recent and list_by_domain without opening schemas.

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?

Explicit when-to-use guidance is present throughout: call get_memory(uid) when the truncated snippet is insufficient, raise `limit` to see collapsed duplicates, and use recall() specifically to recall note()'d knowledge while using search() to sweep diagrams. It also states the default scope ('Only active memories by default'), so the agent knows what is excluded and how to widen.

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