API Reference

HyperMemory exposes 8 MCP tools for memory operations. This reference documents each tool’s parameters, responses, and behavior.

Available tools

Tool	Description	Scope Required
memory_store	Store a new memory node	memory:write
memory_recall	Query memories by natural language	memory:read
memory_find_related	Find nodes related to a given node	memory:read
memory_get_relationships	Get edges and hyperedges for a node	memory:read
memory_update	Update an existing node	memory:write
memory_forget	Delete a node	memory:write
memory_export_subgraph	Export a portion of the graph	memory:admin
memory_load_link	Import a subgraph	memory:admin

Usage costs

Operation Type	Cost
Write operations (store, update, forget, load_link)	Free
Read operations (recall, find_related, get_relationships, export)	1 query

Request format

All tools are called via MCP JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1",
      "param2": "value2"
    }
  }
}

Response format

Successful responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "data": "..."
  }
}

Error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Common error codes

Code	Description	Resolution
INVALID_PARAMETER	Missing or invalid parameter	Check parameter types and requirements
NODE_NOT_FOUND	Referenced node doesn’t exist	Verify node ID
UNAUTHORIZED	Invalid or missing API key	Check Authorization header
FORBIDDEN	Key lacks required scope	Use key with appropriate scope
RATE_LIMITED	Too many requests	Implement backoff, try later
QUOTA_EXCEEDED	Monthly limit reached	Upgrade plan or wait for reset

Base URL

https://api.hypermemory.io/mcp

Authentication

All requests require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Rate limits

Plan	Requests/minute
Free	60
Developer	300
Pro	1000
Enterprise	Custom

Pagination

Tools that return lists support pagination:

{
  "arguments": {
    "query": "...",
    "max_results": 10,
    "offset": 20
  }
}

Response includes pagination info:

{
  "results": [...],
  "total": 150,
  "offset": 20,
  "limit": 10,
  "has_more": true
}

Tool reference

memory_store

Create new memory nodes

memory_recall

Query memories by language

memory_find_related

Find connected nodes

memory_get_relationships

Get edges for a node

memory_update

Modify existing nodes

memory_forget

Delete nodes

memory_export_subgraph

Export graph portions

memory_load_link

Import subgraphs