Build on your knowledge graph.

Overview

Everything you capture in Memohopper — pages, PDFs, notes, memories — lives in Contexts (readable knowledge pages) and Memos (verbatim memory), organized in per-user, isolated workspaces. The API lets an agent or a script store into that graph and recall from it by meaning.

One contract, two transports: remember is an MCP tool and POST /v1/memories. Documented once, kept stable together.

Quickstart

1 Get an API key

In the app: Settings → API keys → New key. The raw key (mh_…) is shown once — copy it. When you mint a key you can scope it to specific workspaces, choose its capabilities (read write ingest), and set a default workspace.

Open Settings → API keys

2 Connect an agent over MCP recommended for agents

Memohopper runs a remote MCP server. The fastest path wires every coding agent you have in one command:

# auto-detects Claude Code, Cursor, Gemini, Codex, OpenCode…
npx memohopper init --token mh_your_key_here

Or add it by hand to any MCP client:

claude mcp add --transport http memohopper https://mcp.memohopper.com/mcp \
  --header "Authorization: Bearer mh_your_key_here"

3 Or make your first REST call

Store a memory, then recall it by meaning:

curl -X POST https://api.memohopper.com/v1/memories \
  -H "Authorization: Bearer mh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content":"We chose Paddle as merchant-of-record for EU VAT.","workspace":"Engineering"}'

curl -X POST https://api.memohopper.com/v1/recall \
  -H "Authorization: Bearer mh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"why did we pick our payment provider?","workspace":"Engineering"}'

Core concepts

A small mental model goes a long way. Everything below is per-user and isolated by workspace.

Workspace

An isolated knowledge graph. Most calls act on one; pass workspace (its name or id), or rely on the key's default when it can access only one.

Context

A readable, structured knowledge page that lives as a node on the graph — the unit you read, search, and grow. Long or document-shaped writes become Contexts automatically.

Memo

A verbatim memory stored exactly as given. Short notes stay memos in the Library; they surface through recall and search.

Source & citations

Ingested documents become source nodes; concepts extracted from them link underneath. Answers and recalls carry the address of the exact paragraph they came from.

Session

An optional episodic tag (e.g. a branch or ticket id) you stamp on writes so you can recall everything from one task later.

Expiry

Time-bound facts can carry an expires value. When it passes, the memory drops out of recall and waits in a review queue — it is never silently deleted.

Authentication & keys

Every request carries a Personal Access Token (PAT) as a bearer token:

Authorization: Bearer mh_your_key_here

The REST API accepts API keys only — a web session is rejected with 401. Keys are minted (and revoked) in the app, and each one can be constrained:

Treat keys like passwords: the raw value is shown once, never logged. Revoke a leaked key in Settings — it stops working immediately.

MCP

The Model Context Protocol is the native path for AI agents. Point any MCP client at https://mcp.memohopper.com/mcp with your key as a bearer header. The server also ships a short usage protocol to the agent automatically — orient with get_briefing, recall before answering from memory, remember durable outcomes.

Connect a client

npx memohopper init --token mh_… auto-detects and wires every coding agent (Claude Code, Cursor, Gemini CLI, Codex, OpenCode) — registering the server and installing the memory rules + a session hook. To wire one by hand, any client connects with:

{
  "mcpServers": {
    "memohopper": {
      "url": "https://mcp.memohopper.com/mcp",
      "headers": { "Authorization": "Bearer mh_your_key_here" }
    }
  }
}

Tools

Once connected, the agent has these tools (plus graph tools explore, link_contexts, get_graph):

REST API v1

Base URL https://api.memohopper.com. This is /v1, a stable contract (see Versioning). Responses return the resource directly; errors are a machine error code plus a human message. Every response carries X-Api-Version: 1.

Addressing a workspace

Pass workspace (name or id) in the JSON body (POST) or query string (GET). Omit it if your key can access only one workspace.

Idempotency

POST /v1/memories and POST /v1/ingest accept an Idempotency-Key header. A repeat with the same key within 24h returns the original response (with Idempotent-Replay: true) instead of writing twice — so a retry after a dropped connection is safe.

curl -X POST https://api.memohopper.com/v1/memories \
  -H "Authorization: Bearer mh_your_key_here" \
  -H "Idempotency-Key: onboarding-note-42" \
  -H "Content-Type: application/json" \
  -d '{"content":"…","workspace":"Engineering"}'

Endpoints

Full request/response schemas for every endpoint live in the machine-readable spec: GET /v1/openapi.yaml (no auth — it's documentation).

Errors

Every error is { "error": "<code>", "message": "<sentence>" } with the matching HTTP status.

Limits & credits

Generative calls — ingest, ask, and memories with mode: "synthesize" — consume plan credits, exactly as they do in the app and over MCP. Plain reads and verbatim stores are free. There are no daily lockouts: the credit allowance refills continuously, with no midnight reset.

When the window is exhausted you get 429 credits_exhausted (retryable). Reads keep working — they cost nothing. Full-agent access is included on every plan; higher plans raise the allowance, parallelism, and per-item size.

See plans & allowances →

Versioning

This is /v1, a stable contract. Additive changes — new endpoints, new optional request fields, new response fields — never change the version, so write clients that ignore unknown response fields. A breaking change ships as /v2, and /v1 keeps working for at least 6 months after, announced here and via a Deprecation response header.

Don't build against the internal /api/* surface — it is unversioned and changes without notice. /v1 and the MCP tools are the supported contracts.