Skip to main content
Glama

Moltline Recall

by com.moltlinestudio

Graph Upsert

graph_upsert
Read-onlyIdempotent

Fold new facts into a memory graph and get the whole graph back. FREE.

Idempotent by construction: re-adding the same entity, observation or relation changes nothing, so an agent that replays its own history does not end up with a graph full of duplicates. Typical input {"graph": {"entities": [], "relations": []}, "entities": [{"name": "Acme Corp", "type": "company", "observations": ["renewed in March"]}]} returns {"graph": {...}, "added": {"entities": 1, "observations": 1, "relations": 0}, "merged": 0}.

Use as the single write path for memory. Not for reading it back selectively - that is graph_search - and not for finding out what a write changed, which graph_diff answers precisely. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "graph exceeds entities; split it"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
graphNoThe existing graph document, or omitted to start a new one. Shape: {"entities": [...], "relations": [...]}.
entitiesNoEntities to add or extend, each {"name": ..., "type": ..., "observations": [...]}. Observations are appended and deduplicated; an existing entity keeps its type unless a new one is supplied.
relationsNoRelations to add, each {"from": ..., "to": ..., "type": ..., and optionally "since", "until", "confidence"}. Dates are ISO 8601 (YYYY-MM-DD); confidence is 0 to 1.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

TDQS

A4.7/5.0
Behavior5/5

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

It discloses idempotency, read-only behavior (which matches annotations), error handling (returns error object instead of raising), and output structure. It goes beyond annotations by detailing error responses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy and includes some redundant statements (e.g., 'Every call is read-only and idempotent' appears twice). However, it is structured with a clear opening and provides comprehensive details, though it could be streamlined.

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 complexity of the tool and the presence of an output schema, the description covers usage, error handling, idempotency, and differentiation from siblings, making it sufficiently complete for an agent.

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?

The schema already provides descriptions for each parameter, including details on appending observations and deduplication. The tool description adds the idempotency aspect which affects parameter behavior, but not much else.

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 clearly states that it folds new facts into a memory graph and returns the whole graph, using the verb 'fold' as an upsert action. It also identifies it as the single write path for memory.

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?

It explicitly states when to use (single write path) and when not to use, directing to graph_search for reading and graph_diff for change detection. Also mentions idempotency for safe retries.

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

All Moltline Recall toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.9/5.0
Disambiguation5/5

Each tool has a distinct, non-overlapping purpose: time-based query, compaction, diff, lint, search, and upsert. No ambiguity between them.

Naming Consistency5/5

All tools follow a consistent 'graph_' prefix with descriptive verb suffixes, forming a clear and predictable naming pattern.

Tool Count5/5

Six tools is an appropriate number for a memory graph server, covering all essential operations without redundancy or bloat.

Completeness5/5

The toolset provides full coverage: upsert for writing, search and at_time for reading, diff for change tracking, lint for validation, and compact for maintenance. No gaps.

Resources