ultramemory-mcp

![UltraMemory](assets/ultramemory-icon-512.png)

# UltraMemory — cross-tool memory for your AI

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

[![PyPI](https://img.shields.io/pypi/v/ultramemory-hermes?color=2dba4e&label=pypi%3A%20ultramemory-hermes)](https://pypi.org/project/ultramemory-hermes/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-7c3aed.svg)](https://modelcontextprotocol.io)

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

```bash
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 eight memory tools.
**Memory tools, no local caching.**

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

```bash
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`:

```bash
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`:

```bash
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
```

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`:

```bash
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`:

```bash
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.

```bash
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`:

```bash
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** — one paste: registers the MCP server and writes the active-recall rule to `AGENTS.md`:

```bash
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](#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:
   ```bash
   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 requ