Graph-Memory

Graph Ingest

graph_ingest

Idempotent

Queue a document for asynchronous extraction into the memory graph or check the ingest backlog status. Use it when a file should be summarized later, not reflected in the current conversation.

Instructions

Queue a document for asynchronous extraction into the memory graph (mode='queue'), or check the ingest backlog (mode='status'). Use this when you have a file the user wants summarized into the graph but doesn't need it reflected in the same conversation — the nightly dream process picks queued documents up. For inline assertions during a conversation, call graph_relate directly instead. Idempotent: queueing the same file twice overwrites the prior copy in the pending dir. Remote callers (e.g. a cloud session collecting its own transcripts) can't name a file on this machine, so they pass content + file_name instead of file_path (admin tenant only). status also returns session_cursors: for each cloud session queued with meta.source='claude-code-cloud', the newest meta.through already queued or dreamed.

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": {
      "action": "<action>"
    },
    "name": "graph_ingest"
  }
}

Input Schema

Name	Required	Description
`meta`	No	Optional metadata for the queued document
`action`	Yes	queue: add file to pending. status: check queue.
`content`	No	Document text to queue inline, for callers that can't reach the server's filesystem. Requires file_name. Admin tenant only.
`file_name`	No	Name for inline content in the pending dir: plain basename ending .md, .txt or .json.
`file_path`	No	Path to a file on the server to queue. For queue, give file_path or content + file_name.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.6.0Oct 29, 2026

addedInput schema / properties / content

Added value: +{
+  "description": "Document text to queue inline, for callers that can't reach the server's filesystem. Requires file_name. Admin tenant only.",
+  "type": "string"
+}

addedInput schema / properties / file_name

Added value: +{
+  "description": "Name for inline content in the pending dir: plain basename ending .md, .txt or .json.",
+  "type": "string"
+}

changedInput schema / properties / file_path / description

Previous value: -"Path to file to queue (required for queue action)"New value: +"Path to a file on the server to queue. For queue, give file_path or content + file_name."

addedInput schema / properties / meta / properties / last_event_id

Added value: +{
+  "description": "ID of the newest session event included in this document",
+  "type": "string"
+}

addedInput schema / properties / meta / properties / session_id

Added value: +{
+  "description": "Cloud session this document came from (with source='claude-code-cloud')",
+  "type": "string"
+}

addedInput schema / properties / meta / properties / through

Added value: +{
+  "description": "ISO timestamp of the newest session event included in this document",
+  "type": "string"
+}

Addedv0.2.2May 10, 2026
Removedv0.1.4May 9, 2026
First observedv1.0.0May 7, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare idempotentHint, and the description adds substantial beyond that: async pickup by a nightly dream process, overwrite semantics on duplicate queueing, an admin-tenant restriction on inline content, and a filesystem-reachability constraint for remote callers. It also discloses what status returns (session_cursors), which the agent could not otherwise know.

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-loads the primary action and mode split, then layers constraints; every sentence carries information. The closing session_cursors sentence is dense and packs several clauses, slightly reducing scannability, but it is not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/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 return-value burden and does describe status output (session_cursors semantics). It stops short of describing what queue returns on success or failure, which would fully close the loop for a tool with five parameters and nested meta.

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 already 100%, so the baseline is 3; the description rises above it by explaining the rationale behind file_path versus content+file_name (remote callers can't reach the server filesystem) and the admin-tenant gating. Minor deduction because it refers to the action parameter as 'mode', which doesn't match the schema's parameter name and could momentarily confuse an agent mapping prose to fields.

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 ('Queue a document for asynchronous extraction into the memory graph') and explicitly covers the second mode ('check the ingest backlog'). The distinction between the two modes and the named sibling graph_relate makes it unambiguous against the many graph_* siblings.

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?

Gives explicit when-to-use ('file the user wants summarized into the graph but doesn't need reflected in the same conversation') and when-not-to-use with the alternative named ('For inline assertions during a conversation, call graph_relate directly instead'). Nothing is left to inference about routing.

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