browse_nodes read

Browse nodes in the graph by type and/or entity. Use to list contacts, activities, assets, etc.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4427

connection_health read

Check health and sync status of data source connections.

Shows last sync time, error count, and status for each connection.
Optionally filter to a single app.

Annotation: _READ_ONLY · Returns: str · Source: server.py:2384

describe_schema read

Return the full graph schema: node labels, relationship types,

common properties, and trust tiers.

Use this before write_to_graph when you need to see every valid node
label, every allowed relationship type, and recommended property names.
No arguments needed.

When an org is in scope, the response is augmented with the actual node
labels and edge types currently present in that org's graph (queried
live from /stats), so callers can distinguish "vocabulary the API
accepts" from "what is already in my graph".

Annotation: _READ_ONLY · Returns: str · Source: server.py:967

No arguments.

dossier read

Get a comprehensive cross-source profile of an entity in one call.

Composes search to resolve the entity -> 1-hop neighborhood with
edge-type counts -> recent timeline -> latent (community-based)
connections. Returns a single structured summary so an agent doesn't
have to chain search + get_entity + traverse + timeline +
get_latent_connections separately. Lower latency, lower token spend,
same coverage. Recommended single-call alternative for "tell me about X"
style requests.

Annotation: _READ_ONLY · Returns: str · Source: server.py:658

get_entity read

Get full details for a node and its relationships.

Annotation: _READ_ONLY · Returns: str · Source: server.py:485

get_extraction_queue read

View the current extraction queue for your user.

Wave 2B replaced the old global file lock with a per-user queue: every
write tool that runs with sync=False (or that can't finish inline within
the 60s deadline of sync=True) lands here, and the per-user worker
drains it. This tool is how you see what's pending, what's processing,
what failed, and roughly how long the rest will take.

Returns a formatted summary plus a list of recent queue rows. The
summary includes:
- your_pending / your_processing counts
- global_pending / global_processing counts (so you know how many
items are ahead of yours)
- eta_seconds: estimated wait for the next pending row to complete,
based on the average extraction time of items finished in the last
hour (or "unknown" if there's no recent history).

Annotation: _READ_ONLY · Returns: str · Source: server.py:5245

get_file read

Get the source .md file content for a node. Returns the original collected data behind any graph node.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4484

get_job_status read newly documented

Check the progress of an async job (sync, bulk import, collection trigger).

Pass a job_id returned from: sync_graph, configure_collection, import_from_api.
Returns job status, progress, and completion details.

Annotation: _READ_ONLY · Returns: str · Source: server.py:5332

get_latent_connections read

Find entities in the same graph community as entity_id that are NOT

directly connected. These are potential warm introductions or hidden
relationships the user may not have noticed.

Annotation: _READ_ONLY · Returns: str · Source: server.py:1097

get_stale_entities read

Find entities that have gone quiet - no activity in the last N days.

Useful for surfacing forgotten follow-ups or dormant relationships.

Annotation: _READ_ONLY · Returns: str · Source: server.py:1144

get_weekly_digest read

Get the most recent weekly digest - a prebuilt summary of the week's

graph activity, new entities, merged duplicates, stale relationships,
and community changes. Generated automatically every Monday.

Annotation: _READ_ONLY · Returns: str · Source: server.py:1185

No arguments.

graph_stats read

Get overview statistics for the knowledge graph (node/edge counts by type).

Annotation: _READ_ONLY · Returns: str · Source: server.py:840

No arguments.

list_connections read

List active data source connections for this org.

Annotation: _READ_ONLY · Returns: str · Source: server.py:1018

No arguments.

list_custom_sources read

List all custom API connections for an entity or the whole org.

Shows system names, connection status, endpoint count, and last collection time.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4072

list_knowledge_bases read

List all graphs in your org (operational + standalone).

Shows display name, template, description, node count, edge count,
and the published flag for each. The `primary` graph is your
operational graph (Gmail / QB / Slack data); other graphs are
standalone KBs created via create_knowledge_base.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4838

No arguments.

list_public_tokens read

List public tokens scoped to a given graph. Owner-only.

Returns label, prefix, rate limit, created_at, last_used_at, and
usage_count for each token. Does NOT return raw keys - the full
key is only shown once at creation.

Annotation: _READ_ONLY · Returns: str · Source: server.py:5056

list_rules read

List correction rules that have been applied to this org's graph.

Annotation: _READ_ONLY · Returns: str · Source: server.py:1049

No arguments.

propose_ontology read

Propose a custom ontology for a domain. Owner-only.

Calls Claude (via subprocess) to design a Pydantic schema describing
the entity types and relationship types an LLM extractor should pull
out of prose for this domain. Returns a JSON proposal -- nothing is
persisted. Iterate via the `refinement` argument; commit via
save_ontology_template.

First call: pass domain_description (e.g. "directory of US-based SBA
lenders with loan products, asset classes, geographies, contacts").
To iterate: pass refinement (e.g. "add a CreditScoreRange field to
LoanProduct"). Optionally fork an existing template via base_template.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4905

search_graph read

Search the knowledge graph for nodes matching a query.

Searches node names, titles, and full document body text via the
full-text index. For broader matching, include synonyms or related terms
in expanded_terms - your AI knows the user's intent best.

Annotation: _READ_ONLY · Returns: str · Source: server.py:424

setup_status read

Combined Graphory account dashboard and setup checklist.

Works even without a valid API key - returns onboarding instructions.
If authenticated, shows account info, graph stats, plan/usage,
connections, last sync, and a setup checklist with the next
recommended action. Useful as a first call to understand the current
state of everything.

Annotation: _READ_ONLY · Returns: str · Source: server.py:2503

No arguments.

sync_status read

Check the status of the most recent sync pipeline run.

Shows progress of each step: Data Extraction, Deduplication & Linking,
Quality Enrichment.

Annotation: _READ_ONLY · Returns: str · Source: server.py:3115

No arguments.

test_custom_source read

Test connectivity for an existing custom API connection.

Re-tests that the stored credentials can reach the API.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4187

timeline read

Get recent activity feed sorted by date.

Annotation: _READ_ONLY · Returns: str · Source: server.py:797

traverse read

Multi-hop traversal from a starting node, with cursor pagination.

Response includes has_more (bool) and next_cursor (string or null).
For dense hub nodes (thousands of edges), iterate by passing next_cursor back in.

Annotation: _READ_ONLY · Returns: str · Source: server.py:616

configure_collection write

Configure what data to collect from a connected source.

Built-in collectors run their full action set automatically once a source
is connected via `connect_source`. There is no per-action catalog to
configure for built-in connectors. For arbitrary REST/GraphQL sources, use
`configure_custom_collector` to declare endpoints explicitly.

This tool returns guidance on which path to use. See args below.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:2191

configure_custom_collector write

Configure which API endpoints to collect data from for a custom source.

Call this after connect_custom_source to define what data to pull.
Supports BOTH REST and GraphQL endpoints, mixed freely in the same
config (pick mode per-endpoint via `api_type`).

REST endpoint (default, `api_type` omitted or "rest"):
{
"name": "contacts",
"path": "/contacts",
"method": "GET",
"node_type": "<see describe_schema>",
"item_type": "contact",
"domain": "operations",
"params": {"sort": "-updated_at"},
"body": null,
"items_path": "data.contacts",
"id_field": "id",
"title_field": "name",
"date_field": "updated_at",
"url_template": "https://app.example.com/contacts/{id}",
"pagination": {"type": "offset", "param": "offset",
"size": 100, "size_param": "limit"}
}

GraphQL endpoint (`api_type: "graphql"`):
{
"name": "repositories",
"api_type": "graphql",
"graphql_query": "query($cursor: String) { viewer { repositories(first: 50, after: $cursor) { nodes { id name description url updatedAt } pageInfo { hasNextPage endCursor } } } }",
"graphql_variables": {},
"node_type": "<see describe_schema>",
"item_type": "repository",
"domain": "content",
"items_path": "data.viewer.repositories.nodes",
"id_field": "id",
"title_field": "name",
"date_field": "updatedAt",
"pagination": {
"type": "graphql_cursor",
"has_more_path": "data.viewer.repositories.pageInfo.hasNextPage",
"cursor_path": "data.viewer.repositories.pageInfo.endCursor",
"variable_name": "cursor"
}
}

For GraphQL:
- The collector POSTs {query, variables} to the base_url
you set in connect_custom_source. Include `/graphql`
in base_url if the API needs it (e.g.
`https://api.github.com/graphql`).
- `path` and `method` are ignored for GraphQL endpoints.
- `graphql_query` is REQUIRED.
- A 200 response with non-empty `errors[]` is treated as
a failure (auth-looking errors map to exit code 2).

REST pagination types: "offset", "page_number", "cursor",
"link_header", "has_more", or null.
GraphQL pagination types: "graphql_cursor" or null.
rate_limit_seconds: Seconds between API requests (default: 0.5)
schedule: Optional - update the polling schedule for this source at
the same time as configuring endpoints. Valid:
live, standard, nightly, manual, paused.
Empty string keeps the existing value. See AGENT_GUIDE.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:3650

connect_custom_source write

Connect a custom REST API that is not in the standard connector list.

For systems like Cloze CRM, niche ERPs, or internal tools where the user
has API credentials. Stores credentials in encrypted credential storage
and optionally tests connectivity.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:3180

connect_source write

Route a user to the right way to connect a data source.

Graphory is BYOC (bring your own credentials). There is no managed OAuth
broker. This tool tells the agent which of two paths to use for a given
source:

1. Browser OAuth sources (Gmail, Google Calendar, Google Drive, Slack,
HubSpot, Salesforce, QuickBooks, Shopify, Stripe, etc.) - the user
finishes the OAuth flow in the web app at app.graphory.io/connections.
2. Personal access token / API key sources (GitHub, Notion, Supabase,
Airtable, Linear, Asana, Cloze, any custom REST API) - the agent
should call connect_custom_source with the user's token instead.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:2701

create_knowledge_base write

Create a new standalone knowledge graph in your org. Owner-only.

Provisions an empty FalkorDB graph and registers it under a slug
derived from `name` (you can pass `graph_id` via the dashboard for
full control). The template determines the ontology used by the
LLM-driven KB extractor when you ingest content into this graph.

Available templates:
- general (safe default - people, orgs, places, dates, concepts)
- coach (business / self-improvement content)
- research (academic papers, scientific writeups)
- ai_chat (transcripts of AI <-> human conversations)
- documents (mixed-format business documents)
- custom_<name> (any custom template you saved with
save_ontology_template)

Returns the new graph_id you can pass to other tools (save_message,
write_to_graph, search_graph) via their `graph_id` arg to target
this graph instead of the org's primary operational graph.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:4780

create_public_token write

Create a public read-only token scoped to one of your graphs.

The returned token can be embedded in client-side code or shared
publicly - it only allows read access to the named graph and is
rate-limited per token. Treat it like a Stripe publishable key.

Returns the full token ONCE on creation. Save it; you can't
retrieve it later (only the prefix and metadata are visible
via list_public_tokens).

Refused for the operational `primary` graph - public tokens are
for standalone graphs created via create_knowledge_base.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:4994

delete_knowledge_base write

Delete a standalone graph. Owner-only.

Refuses to delete the `primary` (operational) graph -- use the
org-level delete endpoint for that. Refuses to delete any graph
with `published=true`; unpublish it first.

WARNING: this drops the FalkorDB graph and removes the metadata
entry. The .md files on disk are unchanged but the graph index
over them is gone. Pass `confirm=true` to actually delete; without
confirm the call returns a preview of what would be deleted.

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:4872

import_from_api write

Push data from any external API into Graphory.

Your AI agent pulls data from a REST API (CRM, ERP, custom system) using
the user's credentials, then passes the raw response items here. Graphory
transforms them into the standard ingest format and writes them to the graph.

Annotation: _IDEMPOTENT_WRITE · Returns: str · Source: server.py:1749

ingest write

Canonical push-to-graph entry point. Use this for any operation that

pushes data to the user's graph: messages, notes, files, conversations,
structured records, batch operations, multi-source snapshots, etc.

This is the DEFAULT for any AI memory operation. `save_message` is just
a thin convenience wrapper around this endpoint for single notes;
anything else (batches, structured records, file payloads with metadata)
should call `ingest` directly.

Data is written as .md files (one per item) with YAML frontmatter, then
extracted into the graph inline when sync=True (default) or enqueued
for the per-user extraction worker when sync=False.

Annotation: _IDEMPOTENT_WRITE · Returns: str · Source: server.py:1662

manage_billing write

Check your plan, usage, or manage your subscription.

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:2835

publish_graph write

Publish a standalone graph to the marketplace. Owner-only.

Marks the graph as a sellable knowledge graph and starts a recurring
Stripe subscription item billed at the marketplace publish fee
(default $50/mo). The fee is independent of your org plan.

Refused for the operational `primary` graph and for graphs that are
already published.

Pass `confirm=True` to authorize the recurring charge. Without
confirm the call returns 400 with a description of what would be
charged so you can show a confirmation prompt.

Use list_public_tokens / create_public_token to issue embed-safe
tokens for downstream consumers; publishing and public token
issuance are independent. Existing public tokens for this graph
remain valid through publish / unpublish cycles.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:5134

register_business write

Register a Business (a company the user owns) in this org. Owner-only.

Creates a :Business node on the org's primary graph and appends the
derived slug to the org's `entities` list. After this returns, save_message,
send_file, ingest, and write_to_graph calls targeting that slug will pass
the entity-access gate. Until a Business is registered for a slug, those
writes are rejected with "Entity '<slug>' is not registered."

Idempotent: if `slug` is already registered, the existing record is
returned with status="exists" and no graph mutation happens.

Returns the slug to use as the `entity` arg in subsequent calls.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:4682

revoke_public_token write

Revoke a public token immediately. Owner-only.

The token stops working as soon as the cache refreshes (within
seconds). Issue a new token first if you need uninterrupted
embed access.

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:5095

save_conversation write

Save a conversation to the knowledge graph. Two-step process.

Step 1: Call with action="get_schema" to get the required format and instructions.
Step 2: Call with action="save" and data=<YAML frontmatter + body>.

The schema tells you exactly how to structure the data. Fill in every field
based on what you know from the conversation, then call again with action="save".

The YAML frontmatter supports both `participants:` (backward-compat, list
of names/emails that become participant edges) and `linked_entities:`
(preferred, list of {name, context, email?} dicts where context is one of
participant/subject/mentioned/author/recipient). Both forms coexist; the
extractor reads both.

Annotation: _IDEMPOTENT_WRITE · Returns: str · Source: server.py:1949

save_message write

Convenience wrapper around `ingest` for the common case of saving a

SINGLE message / conversation memory.

For anything other than a single note (batch records, structured
payloads, file content, multi-source snapshots, etc.) prefer `ingest`
directly. `ingest` is the canonical push-to-graph entry point.

Use save_message when:
- Saving one observation, decision, TODO, summary, or conversation
memory the user just produced.
- You don't have a structured record - just title + body text.

The note is saved as a graph node that auto-links to any people,
companies, accounts, or other entities mentioned in the body text.
Name-mining runs automatically on the content, so plain prose gets
connected without you having to wire entities yourself. Provide
linked_entities explicitly when you want role-typed edges (who
participated, who the note is about, etc.).

Your next session can query these notes like any other node. Notes
are connected to the rest of the graph - every customer, invoice,
meeting, or thread they reference - so later questions like "what
did I decide about Acme last quarter" return the right node with
its full context.

Annotation: _IDEMPOTENT_WRITE · Returns: str · Source: server.py:1397

save_ontology_template write

Persist a proposed ontology to a custom KB template file. Owner-only.

The saved template can immediately be used to back a new graph:

create_knowledge_base(name="Lender Directory",
template=f"custom_{name}")

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:4949

send_file write

Write a file (report, summary, analysis) to the data collection.

Same as save_message but you control the filename.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:1563

sync_graph write

Trigger processing of collected data into the graph.

Runs the full pipeline:
Data Extraction -> Deduplication & Linking -> Quality Enrichment.
This is the same pipeline that runs nightly, but triggered on demand.

Use this after collecting new data (emails, Slack messages, etc.) to make
it immediately available in the graph without waiting for the nightly run.

Returns status and job_id for tracking progress.

Annotation: _NON_IDEMPOTENT_WRITE · Returns: str · Source: server.py:2969

unpublish_graph write

Unpublish a graph and cancel the marketplace licensing fee. Owner-only.

Detaches the recurring Stripe subscription item (Stripe handles
proration per its defaults) and clears the publish metadata.

Existing public tokens for this graph remain valid through the
unpublish; revoke them separately via revoke_public_token if you
also want to cut off embed access.

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:5199

update_source_schedule write

Change the polling schedule for an existing custom API connection.

Use this to pause a source ("paused"), move it to on-demand only
("manual"), or change the cron cadence after the fact.

This updates the stored configuration for the source and takes effect on
the next cron run.

Annotation: _IDEMPOTENT_WRITE · Returns: str · Source: server.py:3965

write_to_graph write

Write data to the graph or correct existing data.

Actions:
add - Add new information. Provide node_id, label, and properties.
connect - Link two existing items. Provide from_id, to_id, relationship.
correct - Fix something that is wrong. Provide node_id and the corrected properties.
merge - Consolidate two nodes you believe are duplicates. Provide
loser_id and winner_id. Rewrites every edge from loser onto
winner, copies non-conflicting properties (winner-wins),
and marks the loser :Merged (preserves audit trail). The
loser node is NOT deleted - it gains a :Merged label
and merged_into/merged_at/status='merged' properties.

For nodes you believe are duplicates, use action='merge' to consolidate.
Use action='connect' relationship='same_as' only to record a soft
assertion without consolidation (the nodes stay separate; no edges move).

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:1220

batch_merge_suggestions review

Confirm many merge-category suggestions in one call.

Accepts both merge_candidate and link_review suggestion ids -- both
perform graph merges when confirmed. Use after walking the user through
a batch of obvious merges (e.g. 12 pairs that share an email and have
near-identical names). Suggestions in other categories are skipped,
not errored.

WARNING: destructive. Confirm the full list with the user first.

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:4648

confirm_suggestion review

Confirm a Graphory suggestion and apply its write-back action.

For merge_candidate and link_review suggestions this merges the two
nodes in the graph (edges redirected, loser deleted). For other
categories it marks the suggestion accepted without a graph write -
follow up with write_node / write_edge if a graph change is needed.

WARNING: merge confirmations (merge_candidate, link_review) are
destructive. Always confirm the merge with the user before calling
this tool.

Annotation: _DESTRUCTIVE · Returns: str · Source: server.py:4602

get_suggestions review

List pending improvement suggestions Graphory has found for this org.

Graphory's nightly pipeline flags candidates it is not confident enough
to auto-apply: likely merges, link-review pairs (multi-signal matches
below auto-merge threshold), uncertain relationships, incomplete contacts,
unconnected entities. Use this to surface them to the user and walk them
through confirm / reject.

Annotation: _READ_ONLY · Returns: str · Source: server.py:4548

reject_suggestion review

Reject a Graphory suggestion. Does not touch the graph.

The rejection reason is persisted inside the suggestion payload so the
pipeline can learn from it (e.g., reduce priority on similar candidates).

Annotation: _IDEMPOTENT_WRITE · Returns: str · Source: server.py:4626