Patterns for AI agents using the Graphory MCP server. Which tool to call for which intent, how the discovery tools surface latent structure, how write gates and provenance keep the graph clean, and the anti-patterns that cause agents to degrade their own memory.
When to call which write tool
Graphory exposes several write paths because different intents deserve different validation. Pick the narrowest tool that fits.
Tool
Use when
Notes
save_message
Logging a single user or assistant turn into an ongoing conversation collection.
Lightweight. One turn at a time. Preserves role and timestamp.
save_conversation
Persisting a full multi-turn thread at the end of a session.
Two-step: request the expected schema, then submit the full thread in one call.
send_file
Writing a document, note, or memo as a first-class Asset with frontmatter.
Best for structured artifacts: meeting notes, research briefs, scoped summaries.
write_to_graph
Asserting a specific node or edge, such as "Jane works for Beta Inc."
Flows through the confidence gate: auto-merge, review queue, or reject.
ingest
Bulk programmatic push of structured records from a webhook or script.
Batched. Idempotent. Not the right choice for conversational writes.
import_from_api
Pulling and transforming records from a connected external REST API.
Uses the org's stored credentials. Good for one-off backfills or targeted syncs.
Default rule: if the user said it in chat, use write_to_graph. If a system produced it, use ingest. If it is a whole document, use send_file.
Discovery tools
The discovery tools surface structure the user did not explicitly ask about. Good agents use them proactively at natural moments: when the user names a company, when Monday arrives, when a project stalls.
get_latent_connections
Returns people and organizations that sit in the same cluster as a target entity but are not directly connected in the graph. Useful for "who else might I know at this company?" and "any warm intros into X?" questions. Mechanism: community detection over the full org graph, with the target's direct neighbors filtered out.
Example narration
User: "I'm reaching out to Acme Corp next week. Anyone I should loop in?"
Agent calls get_latent_connections with entity "Acme Corp", then reports:
"You aren't directly connected to anyone at Acme, but three people in
your network share a community with folks there. Priya at Northwind,
who you co-recipient'd on several threads last quarter, sits in the
same cluster. Want me to draft a warm intro request to her?"
get_stale_entities
Returns people, accounts, and threads that have gone quiet for longer than expected given their prior cadence. Useful for check-in prompts, dormant-relationship surfacing, and "who haven't I talked to in a while?" reflection.
Example narration
User: "Help me plan my week."
Agent calls get_stale_entities as part of setup, then weaves it in:
"Two relationships have gone quiet relative to how often you used
to engage with them: Jordan at Globex (you usually exchanged weekly,
now silent for a while) and the Orion renewal account. Worth a
nudge this week?"
get_weekly_digest
Returns a summary of what changed in the graph over the past week: new entities, newly active accounts, noteworthy shifts in communication patterns, and flagged review-queue items. Ideal for Monday-morning briefings and "what happened in my graph this week?" recaps.
Example narration
User: "Monday check-in."
Agent calls get_weekly_digest and reports:
"Last week: four new contacts landed from Gmail, all tied to the
Helios account. Two review-queue items are waiting on you, both are
potential duplicate Person nodes. The Meridian thread went from
dormant to active. Want to start with the review queue?"
Write gates
Every write is confidence-gated and authority-stamped. Your agent does not set its own confidence; the server computes it from provenance, source authority, and corroboration with existing edges.
High confidence writes auto-merge into the graph.
Medium confidence writes land in a review queue for the user to confirm or correct. This is not a failure state; it is a feature.
Low confidence writes are rejected with a reason the agent should surface to the user, who can then provide the missing signal or escalate.
When a write is queued or rejected, tell the user. "I've queued the edit for your review because it conflicted with two existing emails" is strictly better than silently dropping the change or pretending it landed.
Every edge also records an authority level. Agent writes are stamped as user-correction authority when the user is clearly asserting a fact, and as AI-inference authority when the agent is proposing a fact on its own. User corrections override prior AI inferences automatically on conflict.
Presentation rules
When presenting graph results to the user, the agent's job is to be a faithful synthesizer, not an improviser.
Cite source filenames. Every search result carries the source file. Show it. Users learn to trust the graph by being able to drill in.
Preserve timestamps verbatim. Do not round, paraphrase, or re-express dates in different time zones silently. If the source says 2026-04-10T14:22:00Z, quote it.
Prefer direct quotes when asked "what did X say." Paraphrase is where hallucinations creep in. The graph has the literal text; use it.
Show provenance when stakes are high. For financial, employment, or legal facts, mention the source system (Gmail, QuickBooks, Drive) and the date the record was captured.
Anti-patterns
Agents degrade their own memory when they do these things. Avoid all of them.
Rephrasing the user's message. Do not call a Graphory tool with "the user wants to know about Jane." Call it with the raw message. Proper names, corrections, and scoping cues are often lost in rephrasing, and the server uses the original for query expansion and intent routing.
Claiming confidence in your own writes. The server assigns confidence based on provenance and corroboration. Do not pass a fabricated confidence score; let the gate decide.
Inventing node types. The ontology is fixed. Writes with unknown types are rejected. Express specificity with properties, not with new types. See the Ontology page.
Inventing edge names. Same story. The edge vocabulary is fixed; extra specificity lives in edge properties.
Swallowing rejections. If a write is rejected or queued, tell the user. Silent failure is the fastest way to lose their trust in the graph.
Re-summarizing a fact the graph already stores literally. If the user asks "what did the contract say about renewal," quote the contract clause, do not paraphrase it.
Related
MCP Tools - full reference for every tool the agent can call.
Ontology - the node types and edge names the server will accept.
