Skip to main content
Glama
Plain Text Memory MCP

Plain Text Memory MCP

Search memory

search_nodes
Read-onlyIdempotent

Find entities and notes by BM25-ranked keywords, with optional agent and date filters, to retrieve matching memories and related graph entities.

Instructions

Search entities and notes, ranked by BM25 relevance.

Words match whole, ignoring case and plain plurals; rare words count more than common ones. Recent and often-opened memories rank a little higher. Returns "hits", the matching notes with their entity names and ranks; and the matching entities with every relation that touches them, whose other end may be outside the results. Both lists put the strongest results at the start and end and the weakest in the middle. A query with no words returns every entity and no hits. With since, before, or agent, searches only entries whose tags match; any of them leaves out untagged entries. Each note's path names the memory file it came from. To fetch entities by exact name, see open_nodes. For a multi-step search before planning a task, see recall.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_nodes"
  }
}

Input Schema

NameRequiredDescriptionDefault
agentNoOnly entries written by this agent, such as claude-code or codex.
limitNoMost entities to return, and most hits; omit for all.
queryYesWords to find in entity names, types, and notes, ignoring case; a "quoted phrase" matches only whole.
sinceNoOnly entries added at or after this time: an ISO date such as 2026-10-01, or a timestamp; local time when no offset is given.
beforeNoOnly entries added before this time, in the same format as since.
expandNoSpread scores along relations, so entities linked to the matches rerank and can join the results.
include_supersededNoAlso return notes that were struck through, with superseded_at and replaced_by; hidden by default.

Output Schema

NameRequiredDescriptionDefault
hitsYes
entitiesYes
relationsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changedv0.4.0
    • addedInput schema / properties / expand
      Added value: +{
      +  "default": false,
      +  "description": "Spread scores along relations, so entities linked to the matches rerank and can join the results.",
      +  "title": "Expand",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / include_superseded
      Added value: +{
      +  "default": false,
      +  "description": "Also return notes that were struck through, with superseded_at and replaced_by; hidden by default.",
      +  "title": "Include Superseded",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / limit
      Added value: +{
      +  "anyOf": [
      +    {
      +      "minimum": 1,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Most entities to return, and most hits; omit for all.",
      +  "title": "Limit"
      +}
    • changedInput schema / properties / query / description
      Previous value: -"Words to find in entity names, types, and observations, ignoring case; a \"quoted phrase\" matches as one term."New value: +"Words to find in entity names, types, and notes, ignoring case; a \"quoted phrase\" matches only whole."
    • changedOutput schema / $defs / EntityRecord / description
      Previous value: -"One entity line of the memory file."New value: +"One entity as JSON, with its notes."
    • addedOutput schema / $defs / EntityRecord / properties / notes
      Added value: +{
      +  "items": {
      +    "$ref": "#/$defs/NoteRecord"
      +  },
      +  "title": "Notes",
      +  "type": "array"
      +}
    • removedOutput schema / $defs / EntityRecord / properties / observations
      Removed value: -{
      -  "items": {
      -    "$ref": "#/$defs/ObservationRecord"
      -  },
      -  "title": "Observations",
      -  "type": "array"
      -}
    • changedOutput schema / $defs / EntityRecord / required
      Previous value: -[
      -  "type",
      -  "name",
      -  "entityType",
      -  "added_at",
      -  "agent",
      -  "observations"
      -]New value: +[
      +  "type",
      +  "name",
      +  "entityType",
      +  "added_at",
      +  "agent",
      +  "notes"
      +]
    • addedOutput schema / $defs / HitRecord
      Added value: +{
      +  "description": "One matching note, with its rank; 1 is the strongest.",
      +  "properties": {
      +    "entityName": {
      +      "title": "Entityname",
      +      "type": "string"
      +    },
      +    "note": {
      +      "$ref": "#/$defs/NoteRecord"
      +    },
      +    "rank": {
      +      "title": "Rank",
      +      "type": "integer"
      +    },
      +    "score": {
      +      "title": "Score",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "rank",
      +    "score",
      +    "entityName",
      +    "note"
      +  ],
      +  "title": "HitRecord",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / NoteRecord
      Added value: +{
      +  "description": "One note as JSON, inside an entity's notes list.",
      +  "properties": {
      +    "added_at": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Added At"
      +    },
      +    "agent": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Agent"
      +    },
      +    "path": {
      +      "title": "Path",
      +      "type": "string"
      +    },
      +    "replaced_by": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Replaced By"
      +    },
      +    "superseded_at": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Superseded At"
      +    },
      +    "text": {
      +      "title": "Text",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "text",
      +    "added_at",
      +    "agent"
      +  ],
      +  "title": "NoteRecord",
      +  "type": "object"
      +}
    • removedOutput schema / $defs / ObservationRecord
      Removed value: -{
      -  "description": "One observation as JSON, inside an entity's observations list.",
      -  "properties": {
      -    "added_at": {
      -      "anyOf": [
      -        {
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "title": "Added At"
      -    },
      -    "agent": {
      -      "anyOf": [
      -        {
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "title": "Agent"
      -    },
      -    "edited_at": {
      -      "anyOf": [
      -        {
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "title": "Edited At"
      -    },
      -    "edited_by": {
      -      "anyOf": [
      -        {
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "title": "Edited By"
      -    },
      -    "text": {
      -      "title": "Text",
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "text",
      -    "added_at",
      -    "agent"
      -  ],
      -  "title": "ObservationRecord",
      -  "type": "object"
      -}
    • changedOutput schema / $defs / RelationRecord / description
      Previous value: -"One relation line of the memory file."New value: +"One relation as JSON."
    • changedOutput schema / description
      Previous value: -"Entities and the relations between them, as tools return them."New value: +"Matched entities, the relations touching them, and the top hits."
    • addedOutput schema / properties / hits
      Added value: +{
      +  "items": {
      +    "$ref": "#/$defs/HitRecord"
      +  },
      +  "title": "Hits",
      +  "type": "array"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "entities",
      -  "relations"
      -]New value: +[
      +  "entities",
      +  "relations",
      +  "hits"
      +]
    • changedOutput schema / title
      Previous value: -"GraphRecord"New value: +"SearchRecord"
  2. First observedv0.2.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world, so the safety burden is covered. The description goes well beyond that by disclosing match semantics (whole words, case/plural insensitive, rare words weighted more), recency/frequency boosts, result ordering, and the non-obvious tag-filter interaction ('any of them leaves out untagged entries'). The only soft spot is the vague ordering sentence about strongest results at start and end and weakest in the middle, which could confuse rather than clarify.

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 and ranking, with sibling routing saved for the end, which is good ordering. It is dense and information-rich rather than padded, but the sentence about strongest results being at the start and end and weakest in the middle is awkward and adds little actionable value for an agent.

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 a 7-parameter search tool with an output schema, this is complete: it explains match rules, filtering side effects, ordering, empty-query behavior, and how to read note paths. Nothing needed to call or interpret it correctly is missing, and it avoids re-documenting the return shape the output schema already covers.

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 description coverage is 100%, so a baseline of 3 applies, but the description adds genuinely non-obvious semantics the schema does not state: since/before/agent act as tag filters and exclude untagged entries entirely, and an empty query suppresses hits. It does not cover expand or include_superseded in prose, so it falls short of full compensation.

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?

Opens with a specific verb and resource ('Search entities and notes') plus the ranking model (BM25), which no sibling shares. It also names what it is not: open_nodes for exact-name lookup and recall for multi-step planning, so the agent can discriminate without opening a 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?

Explicit routing is given for both alternatives: 'To fetch entities by exact name, see open_nodes' and 'For a multi-step search before planning a task, see recall.' It also states edge-case behavior (empty query returns every entity, no hits), which tells the agent when a zero-word query is legitimate.

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