API Reference

HyperMemory exposes 18 tools. Every tool is available over MCP, and all but one have a REST route and a CLI command — all three run the same implementation, with the same limits and results.

Surface	Endpoint	Best for
MCP (Streamable HTTP)	https://api.hypermemory.io/mcp	AI agents and MCP clients
REST	https://api.hypermemory.io/api/v1/memory/…	Backends, scripts, workflow tools
CLI	hm …	Shells, CI and agents that run commands

Tools

Memory

Tool	What it does	REST
hm_recall	Search your memory (and your organization’s) with semantic + keyword search and graph context.	POST /recall
hm_store	Save a node with its relationships in one atomic write.	POST /store
hm_update	Correct or extend a node or edge.	POST /update
hm_forget	Delete a node with its edges, or one edge.	POST /forget
hm_get_nodes	Read up to 50 nodes in full by key.	POST /nodes
hm_find_related	Walk the graph outward from a node.	POST /find-related
hm_add_relationships	Connect existing nodes with edges and hyperedges.	POST /relationships
hm_get_overview	Graph totals, node types and your organizations.	GET /overview
hm_ingest	Pull simple facts and relationships out of text.	POST /ingest
hm_list_orphans	Find nodes disconnected from the rest of the graph.	GET /orphans
hm_get_chat_context	Reload what one conversation touched.	— (MCP only)

Timeline

Tool	What it does	REST
hm_timeline	Look up what happened, and when.	POST /timeline
hm_timeline_write	Add a diary entry.	POST /timeline/write

Files

Tool	What it does	REST
hm_upload_file	Upload and process a document, image, audio file or spreadsheet.	POST /upload-file
hm_list_files	List your files and their processing status.	GET /files
hm_tabular	Query processed spreadsheets.	POST /tabular/{mode}

Skills and usage

Tool	What it does	REST
hm_skill	Fetch HyperMemory, system, custom and organization agent skills.	GET / POST /skills
hm_tokens	Report one turn’s AI token usage.	POST /hm_tokens

REST paths are relative to https://api.hypermemory.io/api/v1/memory. See REST API for the HTTP details, including exports and health checks.

Common parameters

Parameter	Tools	Description
organization_id	hm_recall, hm_get_nodes, hm_find_related, hm_get_overview, hm_list_orphans	Read an organization’s memory. On hm_recall it is searched alongside yours; on the others it replaces your graph for that call and the result carries read_target. "none" means your own memory only.
session_id	hm_store, hm_recall, hm_find_related	The conversation’s id. Groups what the conversation touched, for hm_get_chat_context.
response_format	all (MCP)	structured (default) returns the result as structured content with a one-line text summary; text returns the JSON as text; both returns both.

Read and write tools

Writes	Reads
hm_store, hm_update, hm_forget, hm_add_relationships, hm_ingest, hm_upload_file, hm_timeline_write, hm_tokens	hm_recall, hm_get_nodes, hm_find_related, hm_get_overview, hm_list_orphans, hm_get_chat_context, hm_timeline, hm_list_files, hm_tabular, hm_skill

Organization memory is read-only for members: the organization_id reads above never write. A read-only API key can call only the reads. When an organization admin turns on organization write mode, their hm_store, hm_update, hm_forget, hm_add_relationships, hm_ingest, hm_upload_file and hm_list_orphans calls go to the organization’s graph and the result carries write_target.

Safe retries

Writes are idempotent. Send the same X-Request-ID header when you retry a request whose answer was lost, and HyperMemory returns the original result (replayed: true) instead of writing twice. Relationships and hyperedges are also de-duplicated by content.

Discover tools at runtime

curl -X POST https://api.hypermemory.io/mcp \
  -H "Authorization: Bearer $HYPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

tools/list returns every tool with its full input schema.