UltraMemory

UltraMemory — cross-tool memory for your AI

One memory across Claude Code, Claude Desktop, claude.ai, Cursor, ChatGPT, Perplexity, Gemini CLI, OpenClaw, and Hermes. Recalls first every turn — and is honest enough to say "I don't know" instead of making things up.

UltraMemory is a hosted, multi-tenant agent-memory service. One API key (um_…) = your own private tenant. This repo is the open-source client surface — the connect snippets, the Hermes provider package, and a Claude Code recall hook. They all just call the hosted API at https://api.ultramemory.us; the engine stays a managed service (open-core).

Quick start

claude mcp add --transport http ultramemory https://api.ultramemory.us/mcp \

--header "Authorization: Bearer um_YOUR_KEY"

Get a free key at https://ultramemory.io — no credit card required.

Or connect with OAuth — no key needed

On claude.ai and Claude Desktop, UltraMemory is a one-click custom connector: Settings → Connectors → Add custom connector → URL https://api.ultramemory.us/mcp → sign in when prompted. The server speaks OAuth 2.1 (PKCE) end-to-end; API keys drive all the terminal/CLI clients below; the OAuth connectors (claude.ai, Claude Desktop, ChatGPT) sign in without one.

Install options

Three tiers — pick one (each builds on the last):

Tier 1 — UltraMemory (MCP)

Simple connect: point any MCP client at the hosted endpoint and you get the nine memory tools. Memory tools, no local caching.

Claude Code — one paste: registers the MCP server and writes the active-recall rule to CLAUDE.md:

claude mcp add --transport http ultramemory https://api.ultramemory.us/mcp \

--header "Authorization: Bearer um_YOUR_KEY" \ && cat >> CLAUDE.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Gemini CLI — one paste: registers the MCP server and writes the active-recall rule to GEMINI.md:

gemini mcp add -s user -t http ultramemory https://api.ultramemory.us/mcp \

-H "Authorization: Bearer um_YOUR_KEY" \ && cat >> GEMINI.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Prefer OAuth instead of a key? Gemini CLI also supports OAuth — add an httpUrl block to ~/.gemini/settings.json, then run /mcp auth ultramemory inside the CLI.

Cursor — one paste: registers the MCP server and writes the active-recall rule to AGENTS.md:

python3 - <<'PY'

import json,pathlib,shutil,time p=pathlib.Path.home()/".cursor"/"mcp.json"; p.parent.mkdir(parents=True,exist_ok=True) try: d=json.loads(p.read_text()) if p.exists() else {} except ValueError: b=p.with_name("mcp.json.bak-%d"%time.time()); shutil.copy2(p,b); d={} print("Cursor: invalid mcp.json backed up to",b) d.setdefault("mcpServers",{})["ultramemory"]={"url":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}} p.write_text(json.dumps(d,indent=2)) print("Cursor: wrote",p,"— Cursor may prompt an OAuth login; approve it (your key still attributes usage).") PY cat >> AGENTS.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Or use Cursor's official one-click deeplink (add your Bearer key afterwards in ~/.cursor/mcp.json): cursor://anysphere.cursor-deeplink/mcp/install?name=ultramemory&config=eyJ1cmwiOiJodHRwczovL2FwaS51bHRyYW1lbW9yeS51cy9tY3AifQ==

Codex — one paste: registers the MCP server and writes the active-recall rule to AGENTS.md:

mkdir -p ~/.codex && grep -q 'mcp_servers.ultramemory' ~/.codex/config.toml 2>/dev/null || cat >> ~/.codex/config.toml <<'EOF'

[mcp_servers.ultramemory] url = "https://api.ultramemory.us/mcp" http_headers = { Authorization = "Bearer um_YOUR_KEY" } EOF cat >> AGENTS.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Prefer keeping the key out of config.toml: replace the http_headers line with bearer_token_env_var = "ULTRAMEMORY_API_KEY" (Codex 0.46+) and export ULTRAMEMORY_API_KEY in your shell.

Windsurf — one paste: registers the MCP server and writes the active-recall rule to AGENTS.md:

python3 - <<'PY'

import json,pathlib p=pathlib.Path.home()/".codeium"/"windsurf"/"mcp_config.json"; p.parent.mkdir(parents=True,exist_ok=True) d=json.loads(p.read_text()) if p.exists() else {} d.setdefault("mcpServers",{})["ultramemory"]={"serverUrl":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}} p.write_text(json.dumps(d,indent=2)) print("Windsurf: wrote",p) PY cat >> AGENTS.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Windsurf interpolates ${env:VAR}: use "Authorization": "Bearer ${env:ULTRAMEMORY_API_KEY}" to keep the key out of the file (an unset variable silently becomes an empty string). Teams/Enterprise: an admin may need to enable the MCP Servers toggle — off by default on Enterprise.

Cline — one paste: registers the MCP server and writes the active-recall rule to AGENTS.md. VS Code extension users: paste the same mcpServers block via the Cline panel > MCP Servers > Configure MCP Servers.

python3 - <<'PY'

import json,pathlib p=pathlib.Path.home()/".cline"/"data"/"settings"/"cline_mcp_settings.json"; p.parent.mkdir(parents=True,exist_ok=True) d=json.loads(p.read_text()) if p.exists() else {} d.setdefault("mcpServers",{})["ultramemory"]={"type":"streamableHttp","url":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}} p.write_text(json.dumps(d,indent=2)) print("Cline: wrote",p) PY cat >> AGENTS.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

OpenClaw — one paste: registers the MCP server and writes the active-recall rule to AGENTS.md:

openclaw mcp add ultramemory --url https://api.ultramemory.us/mcp \

--transport streamable-http --header "Authorization=Bearer um_YOUR_KEY" \ && openclaw mcp reload && cat >> AGENTS.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Verify the connection with openclaw mcp doctor ultramemory --probe — static checks plus a live connection proof. Changing the header later? openclaw mcp set ultramemory ' ' replaces the whole server definition; run doctor --probe again after.

VS Code — one paste: registers the MCP server and writes the active-recall rule to AGENTS.md:

code --add-mcp '{"name":"ultramemory","type":"http","url":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}}' \

&& cat >> AGENTS.md <<'EOF'

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

This applies to terminal/CLI MCP clients only. The claude.ai OAuth connector needs nothing here — no terminal, no rule file.

Tier 2 — UltraMemory + Turbo Token Saver

The full client plus the Claude Code recall hook — a locally-ejected cache (~/.ultramemory/cache.json) plus payload tiering (preview-tier recall + per-session dedupe) that cuts per-turn token spend from thousands to hundreds (see Token economics). Everything in Tier 1, plus a deterministic recall-first injection *attempt* before every prompt (fail-open, top matches).

1. Drop the recall hook (and its optional cache module) into your project's Claude config:

   mkdir -p .claude/hooks \

&& curl -fsSL https://raw.githubusercontent.com/LogicLabsAI/ultramemory-mcp/main/hooks/recall-first-hook.sh -o .claude/hooks/recall-first-hook.sh \ && curl -fsSL https://raw.githubusercontent.com/LogicLabsAI/ultramemory-mcp/main/cache.py -o .claude/hooks/cache.py \ && chmod +x .claude/hooks/recall-first-hook.sh

2. Export your key (get one free at https://ultramemory.io — no credit card required):

   export ULTRAMEMORY_API_KEY=um_YOUR_KEY

1. One combined paste — registers the hook in .claude/settings.json and appends the

active-recall rule to CLAUDE.md (the Tier-1 one-paste pattern, so the rule can't be skipped by stopping early — the rule covers the agent's own mid-reasoning lookups, not just the passive per-prompt injection):

python3 - <<'PY' && cat >> CLAUDE.md <<'EOF'

import json,pathlib p=pathlib.Path(".claude/settings.json"); p.parent.mkdir(parents=True,exist_ok=True) d=json.loads(p.read_text()) if p.exists() else {} d.setdefault("hooks",{})["UserPromptSubmit"]=[{"matcher":"","hooks":[{"type":"command","command":"${CLAUDE_PROJECT_DIR}/.claude/hooks/recall-first-hook.sh","timeout":20}]}] p.write_text(json.dumps(d,indent=2)) print("Claude Code: registered recall hook in",p) PY

Active recall (UltraMemory)

Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write. EOF

Prefer the richer kit rule? Paste agent-kit/templates/CLAUDE.md.tmpl into CLAUDE.md instead of the block above.

The hook (passive, prompt-scoped injection) and the active-recall rule (the agent's own lookups) are complementary — ship both, don't pick one.

Full details (the Stop capture hook, global install, per-project scopes) live in hooks/README.md.

Tier 3 — UltraMemory Agent Kit

Everything in Tier 2 plus the harness: the grounding + checklist-bound-execution methodology as installable skills and subagents (checklist-worker, checklist-verifier) with a St