Quickstart

Connect UltraMemory

One URL and a key. UltraMemory is a remote MCP server (Streamable HTTP), so any MCP-capable client plugs in with a single block. Pick your client below — everything uses the same Bearer credential.

MCP endpoint

https://api.ultramemory.us/mcp

Auth header

Authorization: Bearer YOUR_API_KEY_HERE

Get your key: sign in at app.ultramemory.us. Your YOUR_API_KEY_HERE key is shown once on the dashboard — copy it, then paste it into any snippet below.

Using your key: wherever a snippet below shows YOUR_API_KEY_HERE, replace that whole token with your real key (it starts with um_, copied once from app.ultramemory.us). Paste only the key — do not keep any surrounding { } braces or quotes.

Example — a filled-in auth header (this key is fake; use your own):

Authorization: Bearer um_8Kp2Qz_EXAMPLE_DO_NOT_USE_4f7Wx9bV3mYs6Tg1Rd5

Claude Code

one command

Add the remote MCP server from your terminal. Streamable HTTP, one line. What this does: registers the UltraMemory connection with your key, installs a hook that recalls your memories before each prompt, and adds a recall-first note to your project instructions — then run /mcp and you'll see ultramemory✓ Connected. It's open source — read every line on GitHub, download it from the repo yourself, or paste it and ask Claude Code to explain exactly what it does before you run it.

shell

claude mcp add --transport http ultramemory \
  https://api.ultramemory.us/mcp \
  --header "Authorization: Bearer YOUR_API_KEY_HERE"

Then ask Claude to recall or store a memory — the memory_recall / memory_write tools appear automatically.

Cursor

mcp.json

Add one server block to ~/.cursor/mcp.json (or .cursor/mcp.json in your project).

json

{
  "mcpServers": {
    "ultramemory": {
      "url": "https://api.ultramemory.us/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY_HERE" }
    }
  }
}

Reload Cursor; UltraMemory shows up under Settings → MCP.

Claude Desktop

connectors

Settings → Connectors → Add custom connector. Paste the URL; add an Authorization header. Or edit claude_desktop_config.json directly:

json

{
  "mcpServers": {
    "ultramemory": {
      "url": "https://api.ultramemory.us/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY_HERE" }
    }
  }
}

Fully quit and reopen Claude Desktop to load the connector.

ChatGPT

developer mode

Settings → Connectors → Advanced → Developer mode, then Create. Use the URL as the MCP server and add the Bearer header as a custom authentication header.

text

Server URL:  https://api.ultramemory.us/mcp
Auth header: Authorization: Bearer YOUR_API_KEY_HERE

The same one URL + key works in the OpenAI Agents SDK — pass it as a remote MCP (Streamable HTTP) server.

Hermes

memory provider

The deep path. Install the provider plugin and point Hermes at it — UltraMemory then auto-injects relevant memory before every turn, captures after, and consolidates on session end.

shell

pip install ultramemory-hermes

ultramemory enable --key YOUR_API_KEY_HERE

ultramemory enablewrites your key and selects UltraMemory as the Hermes memory provider for you — no hand-edited yaml. This is the “it just works and self-learns” experience MCP structurally can't offer — lifecycle hooks, not just tool calls.

curl / REST

direct

No client? Call the REST API straight over HTTP to confirm your key — plain recall works on every tier.

shell

curl https://api.ultramemory.us/api/v1/recall \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"query": "what did we decide about auth?"}'

Every REST call uses the same header: Authorization: Bearer YOUR_API_KEY_HERE. Swap /recall for /recall/gated to add the answer / verify / abstain gate — every feature is on every plan.

Verify it works

Confirm the connection in 30 seconds

Start with plain recall — it works on every tier and is the quickest way to prove your key is live. Write a memory, then recall it back.

shell

# 1) write a memory
curl https://api.ultramemory.us/api/v1/permanent \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"entity": "auth", "key": "decision", "value": "We chose OAuth 2.1 with PKCE."}'

# 2) recall it — plain recall, works on every tier
curl https://api.ultramemory.us/api/v1/recall \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"query": "what did we decide about auth?"}'

optional See the metamemory gate. Gated recall adds the answer / verify / abstain decision on top of recall — on every plan, like every feature. On a fresh tenant with no grounded memory, the gate correctly abstains— that's the system working, not an error.

shell

# 3) optional: run recall through the metamemory gate
curl https://api.ultramemory.us/api/v1/recall/gated \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"query": "what did we decide about auth?"}'

expected — gated, no memory yet

{ "decision": "abstain",
  "context_block": "No sufficiently grounded memory. Retrieve or ask before asserting." }

A 401 means the key is missing or wrong — re-copy it from the dashboard. A 429 means you hit your rate or usage limit; check the meters in your workspace. A 402 means your subscription payment is past due — fix billing from your workspace. Gated recall is not tier-gated: every feature, including the metamemory gate, is on every plan. Health check: https://api.ultramemory.us/healthz.

How updates work

Bitemporal supersede

Facts are bitemporal. Writing to the same entity + keysupersedes the prior active fact: the old row isn't deleted — it retires with its dates (valid_from / valid_to preserved), and recall serves only active facts from that moment on. Pass as_offor time-travel (“what was true in March?”). Two more layers keep answers honest: decay de-ranks knowledge that goes unused, and the metamemory gate abstains on weak or conflicting evidence instead of guessing.

1 · A part gets replaced

Your service company documents that the H1000's compressor part was superseded. Write the new fact to the same entity + key— the old one retires with its dates, and “what was true in March” is still answerable.

shell

# the H1000's compressor part is superseded — same entity + key, new value
curl https://api.ultramemory.us/api/v1/permanent \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"entity": "H1000", "key": "compressor_part", "value": "Use part P-2041 (replaces P-1050 as of June 2026)."}'

# → { "fact_id": "…", "deduped": false, "superseded": 1 }
#   the prior fact retired: its valid_to is set; the new fact answers from now on

# time-travel: what was true in March?
curl https://api.ultramemory.us/api/v1/recall \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"query": "H1000 compressor part", "as_of": "2026-03-15T00:00:00Z"}'

2 · A product is discontinued

Your catalog sync says item #2043 is gone. A salesperson asks their AI about it and gets “discontinued as of June” — not a confident yes on something you no longer sell.

shell

# the catalog sync marks item #2043 discontinued
curl https://api.ultramemory.us/api/v1/permanent \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"entity": "item-2043", "key": "status", "value": "Discontinued as of June 2026 — quote item-2051 instead."}'

# the salesperson's AI asks — recall serves the current truth, gated recall
# abstains rather than bluff when the evidence is weak or conflicting
curl https://api.ultramemory.us/api/v1/recall/gated \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"query": "can I still quote item 2043?"}'

3 · A policy is rewritten

Upload the new handbook into the company knowledge layer (Teams and up, owners and admins). The engine matches the new policies to the old ones, supersedes what changed, and queues anything ambiguous for a one-click admin review — nobody scrubs the memory by hand.

shell

# upload the new handbook (PDF, DOCX, Markdown, plain text, or CSV)
curl https://api.ultramemory.us/me/team/knowledge/upload \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -F "file=@employee-handbook-2026.pdf"

# → a queued ingest job; matched policies supersede the old ones,
#   ambiguous matches wait as proposals for one-click admin review

Update a fact once, and every member's AI knows it from that moment. Old truth retires. Current truth answers. Nothing is ever silently made up.

Comparing memory tools? See the detailed comparison — names, sources, benchmarks →

Open source

The UltraMemory client surface is open source (Apache-2.0) — the connect snippets, the Hermes provider package, and a Claude Code recall hook all live in one repo: github.com/LogicLabsAI/ultramemory-mcp ⭐.

Want deterministic recall on every prompt in Claude Code? Add the UserPromptSubmit recall hook →

Need a hand?

Open your dashboard to manage keys, usage, and plan — or email us and we'll help you connect.

Full usage guide →