UltraMemory← Home

Install

Install UltraMemory — three tiers

You know the feeling: you /clear and the agent that knew your whole project five seconds ago now knows nothing. Every new session starts with re-explaining the stack, the decisions, the gotchas — again. That loss is the problem UltraMemory removes.

Three tiers, each a superset of the last. Tier 1 connects the memory tools. Tier 2 adds the recall-first hook so memory arrives on every prompt. Tier 3 installs the full Agent Kit in one line. Every tier uses the same key from your dashboard.

Start here

Your Claude, ChatGPT, Gemini, Hermes, and Perplexity never forget — with UltraMemory.

Give your AI and your projects: never-forget memory across every tool · ~70% less token spend in our testing · grounding in your real facts instead of guesses and hallucinations · faster delivery with fewer iterations · and less of the token waste that typical LLMs burn on drift. Results may vary.

Start in one click — connect UltraMemory with OAuth on Claude, ChatGPT, or Perplexity. No keys, no setup.

Want to stop burning tokens? The UltraMemory Plugin (one-line install) cut token use ~70% in our testing. Want that PLUS your project locked on persistent grounded truth — fewer iterations, faster delivery, and no tokens wasted on drift? Add the UltraMemory Agent Kit. Results may vary.

Token figure: ~70% in our testing (measured 2026-07-05). Results may vary. This content is informational and not a guarantee of outcome.

OAuth vs Plugin — which path?

OAuth connect — recommended, easiest

One click, no keys, no setup. Best for most people. Available today on Claude, ChatGPT, and Perplexity. You get the memory tools (recall / write / search) wired in — start in seconds.

Plugin / Extension — power users, bundled

A one-line install that bundles the memory tools together with recall-first behavior and the token-saver / harness. Best when you want the deeper, always-on experience. The UltraMemory Plugin cut token use ~70% in our testing. Results may vary.

What's a Plugin?

A Plugin is a one-click bundle: it packages the UltraMemory memory tools together with recall-first behavior and the optional token-saver / harness, so your agent connects and starts recalling without hand-wiring config. Skills and rules work broadly across platforms; hooks and sub-agents run only in Claude Code, Cowork, Hermes, and the Cline CLI — never inside claude.ai, ChatGPT, or Perplexity chat. Cowork loads the connectors enabled on your claude.ai account, synced at session start — add UltraMemory once on claude.ai, then toggle it on in Cowork's Customize sidebar.

The Plugin / Extension path per platform

  • Gemini CLI — MCP server (gemini mcp add -t http)
  • Codex — Plugins (.codex-plugin/plugin.json)
  • Cline — Plugins (cline plugin install; CLI/SDK today)
  • OpenClaw — MCP server (openclaw mcp add)
  • VS Code — Agent plugins (preview) + Extensions
  • Hermes — Plugins (memory-provider plugin)
  • Windsurf — MCP server + rules (no bundle; MCP + .windsurf/rules/)
  • Perplexity — Connector (Pro/Max/Enterprise) — verified end-to-end July 2026; paid plans

Perplexity — profile instructions (recommended)

Paste this into Settings → Personalization → Custom instructions so recall-first and Computer-mode auto-save are standing behavior:

UltraMemory (@UltraMemory) is my authoritative long-term memory across all my AI tools.

RECALL FIRST: On every question — not just at chat start — recall from UltraMemory before answering and ground your reply in it; prefer it over built-in memory. If context might be missing, recall instead of guessing.

TOOL ROUTING: Governance/policy/compliance questions → recall_gated (only it returns the full COMPANY POLICY briefing). Expected fact comes back empty → retry once with recall_verified. Never invent a memory — if it's not there, say so. If Perplexity's own memory and UltraMemory disagree, UltraMemory wins. Memories saved from my other tools (Claude, ChatGPT, etc.) only surface via @UltraMemory or Computer mode — check there before saying it isn't saved. ATTACH RULE: for any question about my saved info, memory, or memory tools — including meta-questions — attach and query @UltraMemory instead of web-searching its docs.

WRITES (Computer mode; @UltraMemory binds): at the end of each substantial turn, save durable takeaways (decisions, specs, names, dates, state, next steps) via memory_write — self-contained values: named entities, absolute dates, concrete numbers, 15-100 words. Skip ephemeral or sensitive items I didn't ask to keep. Confirm in one line what you saved. When I confirm or correct a recalled answer, label it via memory_feedback (event_id).

Search mode is recall-only. Standing instruction; don't ask me to redefine it.

Perplexity caps Custom instructions at 1,500 characters — this text is 1,455 and fits; if you add your own lines, keep the total under 1,500 or the field silently truncates.

Tier 1 — UltraMemory (MCP)

Connect only — the memory_recall / memory_write tools, no local caching. One command registers the remote MCP server (Streamable HTTP) with your key:

What each tool takes and when the agent calls it: Tools reference →

Claude Code

shell
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

Windows (PowerShell):

powershell
claude mcp add --transport http ultramemory https://api.ultramemory.us/mcp --header "Authorization: Bearer um_YOUR_KEY"
Add-Content -Path CLAUDE.md -Value @'

## 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.
'@

Gemini CLI

shell
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

Cursor

shell
python3 - <<'PY'
import json,pathlib
p=pathlib.Path.home()/".cursor"/"mcp.json"; p.parent.mkdir(parents=True,exist_ok=True)
d=json.loads(p.read_text()) if p.exists() else {}
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

Windows (PowerShell) — uses python, not python3 (a Store stub on Windows 11):

powershell
python -c "import json,pathlib; p=pathlib.Path.home()/'.cursor'/'mcp.json'; p.parent.mkdir(parents=True,exist_ok=True); d=json.loads(p.read_text()) if p.exists() else {}; 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)"
Add-Content -Path AGENTS.md -Value @'

## 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.
'@

Codex

shell
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.

Windows (PowerShell) — set the env var for the current session, or persist it:

powershell
$env:ULTRAMEMORY_API_KEY = "um_YOUR_KEY"   # current session
setx ULTRAMEMORY_API_KEY "um_YOUR_KEY"       # persists for new shells (user scope)

Windsurf

shell
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

shell
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

VS Code extension users: paste the same mcpServers block via the Cline panel > MCP Servers > Configure MCP Servers.

OpenClaw

shell
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 '<full JSON>' replaces the whole server definition; run doctor --probe again after.

VS Code

shell
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

Replace um_YOUR_KEY with your real um_ key, then run /mcp — you'll see ultramemory ✓ Connected.

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

Same memory, a fraction of the tokens: the recall-first hook + local cache + payload tiering recall your memory before every prompt, so you stop paying to re-send what the agent should already know. One paste installs it from the public repo.

Everything in Tier 1, plus the recall-first hook: instead of waiting for the agent to remember to check its memory, the hook injects your top matching memories before every prompt — deterministic injection (fail-open: any error injects nothing), paired with an active-recall rule in CLAUDE.mdfor the agent's own mid-task lookups. A local cache plus payload tiering trims repeated recalls, so it saves tokens while it saves context.

shell
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

Full setup + every line of source: github.com/LogicLabsAI/ultramemory-mcp

The step-by-step manual setup (download the hook, export your key, wire .claude/settings.json) lives in the repo's hooks/README →

Ships for Claude Code and Hermes today — on this client you get Tier 1 now; Tier 2/3 hook support lands per client.

Tier 3 — UltraMemory Agent Kit

Everything in Tier 2, plus the harness — grounding + checklist-bound execution skills, the checklist-worker / checklist-verifier subagents, and a static Stop-gate. One guided installer prompts for your key, lets you pick Tier 2 or Tier 3, wires everything, and runs an “it's working” check:

shell
bash <(curl -fsSL https://ultramemory.io/kit.sh)

Or install through the Claude Code plugin marketplace — bundles the skills, subagents, hooks, and MCP servers in one enable (advanced / team):

shell
/plugin marketplace add LogicLabsAI/ultramemory-mcp
/plugin install ultramemory-kit@ultramemory

The kit is open source (Apache-2.0) — read every line before you run it: github.com/LogicLabsAI/ultramemory-mcp.

Ships for Claude Code and Hermes today — on this client you get Tier 1 now; Tier 2/3 hook support lands per client.

Optional: Auto-tune your platform

Once any tier is installed, one command tunes your agent platform for UltraMemory — the best persistable model and effort settings, low-friction permissions, and pre-approval for exactly the nine UltraMemory tools (never a blanket allow). The command ships in the ultramemory-mcp package (pip install ultramemory-mcp; also published as ultramemory-hermes):

shell
pip install ultramemory-mcp   # provides the ultramemory command
ultramemory configure
# preview only: ultramemory configure --dry-run
# undo:         ultramemory configure --restore

It proposes each change and asks first — per-item consent, default no: nothing changes without your explicit yes, and installing UltraMemory never runs it for you. Before its first write to any file it saves a timestamped backup and records every change, so ultramemory configure --restore (from the ultramemory-mcp package) or the kit uninstaller reverts exactly what it changed — settings you edited yourself are left alone.

Some settings are session-only by design (Claude Code's Ultracode mode, Cline's thinking level) and can't honestly be persisted — for those, an optional session-start prompt offers the boost at launch and stays silent when you're already tuned.

PlatformAuto-tuned (persists, with your yes)Session-start prompt covers
Claude CodeModel, effort (xhigh), permission mode, the 9-tool allowlist, session-start hookUltracode / max effort (session-only by design)
Codex CLIReasoning effort (high), approval + sandbox mode, per-server allowlistModel pick (account-gated rollout); the hook runs after you trust it via /hooks
Gemini CLIThinking level (HIGH), auto-edit approvals, server trust + exact tool scope, hook (v0.26+)YOLO mode (per-launch flag only — not persistable)
CursorApproval mode, Max Mode, the 9-tool allowlist, session-start hookModel pick (CLI-managed — set via /model)
Cline (CLI)Auto-approve for the 9 tools, streamable transport, TaskStart hookThinking level (per-run --thinking flag)
VS Code / CopilotDefault chat model, hooks enabled + session-start hookPer-tool approvals + thinking effort (internal storage, not settings.json)
OpenClawThinking default (xhigh) via openclaw config — applies after openclaw gateway restart, run it when convenientModel pick (explicit only)
HermesReasoning effort (xhigh) via hermes config, exact tool include-listModel pick (explicit only)
WindsurfModel pin, the 9-tool allowlist, session-start hookThinking level (Alt+T, session-scoped)

Honesty notes: Hermes runs MCP tools without approval prompts today, so pre-approval adds nothing there; Cline is tuned CLI-side only (the IDE extension stores its state internally); Cursor's tool allowlist replaces its in-app allowlist editor while present — configure (from the ultramemory-mcp package) discloses this and skips it if you decline.