Skip to main content
Glama

XMemo

by io.github.yonro
OverviewDiscussionsAdmin

Read Memory

read_memory
Read-onlyIdempotent

Read one exact authorized XMemo memory or Document in character windows.

Use a bare memory ID (e.g. returned by recall or search) for the initial read (offset 0). The response includes 'revision' (e.g. '<memory_id>@v') and 'version'. To continue reading long content across multiple pages (when 'has_more' is True), callers MUST pass the returned 'revision' as memory_id along with 'next_offset'. This pins continuation pages to that exact snapshot and prevents torn reads if concurrent updates occur between requests. Querying with a bare memory ID always resolves to the latest active version (head), which is unpinned and subject to version tearing across updates. A Document item's reference ('document:') reads the whole Document the same way. For a Document, 'anchor' (a heading path) with 'ordinal' (1 = its first chunk) starts the page at that section; continue with 'next_offset' and no anchor. 'version' pins like a revision; a Document that changed since returns version_changed=true and no content, so restart at offset 0. Embeddings are never returned.

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum content characters in this page; defaults to 4000.
anchorNoOptional Document heading path to start the page at; leave offset at 0.
offsetNoZero-based character offset into this memory's content; defaults to 0.
ordinalNoWhich chunk carrying the anchor to start at (1 = first); defaults to 1.
versionNoOptional version pin, the same as a '@v<version>' revision.
memory_idYesExact XMemo memory reference or 'document:<id>' returned by recall or search.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / anchor
      Added value: +{
+  "default": "",
+  "description": "Optional Document heading path to start the page at; leave offset at 0.",
+  "type": "string"
+}
    • changedInput schema / properties / memory_id / description
      Previous value: -"Exact XMemo memory reference returned by recall or search."New value: +"Exact XMemo memory reference or 'document:<id>' returned by recall or search."
    • addedInput schema / properties / ordinal
      Added value: +{
+  "default": 1,
+  "description": "Which chunk carrying the anchor to start at (1 = first); defaults to 1.",
+  "type": "integer"
+}
    • addedInput schema / properties / version
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional version pin, the same as a '@v<version>' revision."
+}
  2. Changed1 schema field changed
    • removedInput schema / additionalProperties
      Removed value: -false
  3. Added

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses critical behavior: bare IDs resolve to latest head and are unpinned, revision-pinned continuation prevents torn reads, and version_changed forces restart. It also states that embeddings are never returned. This is exactly the kind of behavioral context the annotations cannot provide.

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 dense but well front-loaded, starting with the core operation and then explaining continuation and pinning. Every paragraph carries necessary behavioral detail about revisions, offsets, anchors, and Documents. There is little wasted language for a tool with this much continuation semantics.

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?

Given the rich annotations, full schema description coverage, and output schema, the description covers the remaining gaps an agent needs: revision pinning, Document anchor behavior, version mismatch handling, and the no-embeddings guarantee. No essential call behavior is omitted for this complexity level.

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 cross-parameter meaning: memory_id can be a bare ID, revision, or document reference; anchor pairs with ordinal; version pins like a revision. The only ambiguity is that it refers to 'next_offset' while the schema parameter is named 'offset', which could cause a minor lookup mismatch.

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 states a specific verb and resource: reading one exact authorized XMemo memory or Document in character windows. It clearly distinguishes this precise-read tool from recall/search discovery tools by noting that IDs are returned by recall or search. An agent can identify the operation 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 Guidelines4/5

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

It gives clear usage context: use a bare memory ID for the initial read, then use the returned revision with next_offset to continue long content. It also explains Document anchor/ordinal starts and version pinning. It does not explicitly state exclusions against siblings such as recall, but the discovery-versus-exact-read split is strongly implied.

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

All XMemo toolsInspect
Try in Browser
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources