UltraMemory

https://ultramemory.io/docs
Admin
UltraMemory is a persistent long-term memory service and remote MCP server that provides AI agents...
Tokens:28,977
Snippets:230
Trust Score:5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run Tier 3 guided installer

Source: https://ultramemory.io/docs/install

Runs the UltraMemory Agent Kit guided installer via a bash one-liner. The installer prompts for your key, lets you choose Tier 2 or Tier 3, wires everything, and runs an 'it's working' check.

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

--------------------------------

### Install and configure UltraMemory

Source: https://ultramemory.io/docs/install

Install the ultramemory-mcp package to gain access to the ultramemory command, then run the configuration tool. Use the --dry-run flag to preview changes or --restore to revert them.

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

--------------------------------

### Example Filled-in Auth Header

Source: https://ultramemory.io/docs

An example of a correctly formatted Authorization header using a placeholder API key.

```text
Authorization: Bearer um_8Kp2Qz_EXAMPLE_DO_NOT_USE_4f7Wx9bV3mYs6Tg1Rd5
```

--------------------------------

### Install and enable UltraMemory Hermes provider

Source: https://ultramemory.io/docs/usage-guide

Follow these steps to install the package, enable the provider shim, and verify the installation status.

```bash
# 1) Install the provider package (also published as ultramemory-hermes)
pip install ultramemory-mcp

# 2) Enable — writes your key AND plants the provider shim Hermes scans for
ultramemory enable --key YOUR_API_KEY_HERE

# 3) Verify
hermes memory status   # should show the ultramemory provider
```

--------------------------------

### Hermes Memory Provider Installation and Enable

Source: https://ultramemory.io/docs

Install the ultramemory-mcp package and run 'ultramemory enable' to set UltraMemory as the Hermes memory provider. This writes your key and selects the provider automatically.

```shell
pip install ultramemory-mcp

ultramemory enable --key YOUR_API_KEY_HERE
```

--------------------------------

### Example Authorization header with UltraMemory API key

Source: https://ultramemory.io/docs/usage-guide

Shows the format for the Authorization header using a fake key. Replace YOUR_API_KEY_HERE with your real key (starts with um_) from https://app.ultramemory.us. Do not include surrounding braces or quotes.

```http
Authorization: Bearer um_8Kp2Qz_EXAMPLE_DO_NOT_USE_4f7Wx9bV3mYs6Tg1Rd5

```

--------------------------------

### GET /readyz

Source: https://ultramemory.io/docs/usage-guide

Readiness check endpoint, no authentication required.

```APIDOC
## GET /readyz

### Description
Readiness check endpoint, no authentication required.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- **status** (string) - The readiness status.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Install Tier 2 recall-first hook and cache

Source: https://ultramemory.io/docs/install

One-line shell command that creates the .claude/hooks directory, downloads the recall-first-hook.sh and cache.py files from the ultramemory-mcp repo, and makes the hook executable. Use this to install Tier 2 on Claude Code or Hermes.

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

--------------------------------

### Configure ~/.gemini/settings.json with API Key

Source: https://ultramemory.io/docs/usage-guide

Use this configuration block if you prefer a headless setup using a bearer token instead of browser-based OAuth.

```json
{
  "mcpServers": {
    "ultramemory": {
      "httpUrl": "https://api.ultramemory.us/mcp",
      "headers": { "Authorization": "Bearer um_YOUR_KEY" }
    }
  }
}
```

--------------------------------

### Install Tier 3 via Claude Code plugin marketplace

Source: https://ultramemory.io/docs/install

Two Claude Code commands to add the ultramemory-mcp plugin marketplace and install the ultramemory-kit plugin. This bundles skills, subagents, hooks, and MCP servers in one enable for advanced/team use.

```shell
/plugin marketplace add LogicLabsAI/ultramemory-mcp
```

```shell
/plugin install ultramemory-kit@ultramemory
```

--------------------------------

### Configure UltraMemory via environment variables

Source: https://ultramemory.io/docs/usage-guide

Optional environment variables to tune provider behavior. Note that running 'ultramemory enable' is still required to plant the shim.

```bash
export ULTRAMEMORY_API_KEY=YOUR_API_KEY_HERE                     # required
export ULTRAMEMORY_BASE_URL=https://api.ultramemory.us   # optional (this is the default)
export ULTRAMEMORY_GATED=true        # gated recall (abstain instead of guess) — default true
export ULTRAMEMORY_AUTO_CAPTURE=true # persist each completed turn — default true
export ULTRAMEMORY_RECALL_K=8        # how many facts to recall per turn (1–100) — default 8
export ULTRAMEMORY_FEEDBACK=true     # close the self-calibrating gate feedback loop — default true (paid)
export ULTRAMEMORY_SPACE=private     # Teams+: route auto-writes — private (your member space) | shared (team space) — default private
export ULTRAMEMORY_PREVIEW=on        # tiered preview payloads on SDK surfaces; off reverts prefetch to full recall — default on
export ULTRAMEMORY_CACHE=on          # client cache at ~/.ultramemory/cache.json; off disables the memo + seen cache — default on
export ULTRAMEMORY_HOOK_BUDGET=2000  # Claude Code hook injection budget in characters — default 2000
```

--------------------------------

### GET /api/v1/usage

Source: https://ultramemory.io/docs/usage-guide

Returns current-month billable operations and quota.

```APIDOC
## GET /api/v1/usage

### Description
Returns current-month billable operations and quota.

### Method
GET

### Endpoint
/api/v1/usage

### Response
#### Success Response (200)
- **billable_ops** (integer) - The number of billable operations.
- **quota** (integer) - The quota.

#### Response Example
{
  "billable_ops": 10,
  "quota": 100
}
```

--------------------------------

### Configure UltraMemory in Claude Desktop (Legacy)

Source: https://ultramemory.io/docs

Legacy fallback configuration for older Claude Desktop versions using mcp-remote in claude_desktop_config.json.

```json
{
  "mcpServers": {
    "ultramemory": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://api.ultramemory.us/mcp",
               "--header", "Authorization: Bearer YOUR_API_KEY_HERE"]
    }
  }
}
```

--------------------------------

### GET /healthz

Source: https://ultramemory.io/docs/usage-guide

Health check endpoint, no authentication required.

```APIDOC
## GET /healthz

### Description
Health check endpoint, no authentication required.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **status** (string) - The health status.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Connect UltraMemory via Claude Code CLI

Source: https://ultramemory.io/docs/usage-guide

Use the claude mcp add command to register the UltraMemory server. Replace YOUR_API_KEY_HERE with your actual um_ key and verify the connection by running /mcp in the Claude Code interface.

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

--------------------------------

### Write and recall a memory with curl

Source: https://ultramemory.io/docs

Use these two curl commands to write a memory and then recall it. Replace YOUR_API_KEY_HERE with your actual key. Plain recall works on every tier.

```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?"}'
```

--------------------------------

### Discontinue a product and gated recall

Source: https://ultramemory.io/docs

Shows how to mark a product as discontinued and then use the gated recall endpoint to get the current truth, abstaining on weak or conflicting evidence.

```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?"}'
```

--------------------------------

### Add UltraMemory via CLI one-liner

Source: https://ultramemory.io/docs/usage-guide

Alternatively, add the UltraMemory MCP server using a single command line instruction with your bearer token.

```bash
gemini mcp add -s user -t http ultramemory https://api.ultramemory.us/mcp -H "Authorization: Bearer um_YOUR_KEY"
```

--------------------------------

### Configure GEMINI.md for automatic recall

Source: https://ultramemory.io/docs/usage-guide

Add these instructions to your global or per-project GEMINI.md file to ensure the model prioritizes UltraMemory search and write tools.

```markdown
On EVERY user turn, FIRST call the UltraMemory search (or memory_recall) tool with the user's request and ground your answer in what comes back — prefer it over any built-in memory. If low confidence or no results, say you don't know rather than guessing. Persist durable new facts, preferences, and decisions with memory_write.
```

--------------------------------

### Configure OpenClaw MCP Server

Source: https://ultramemory.io/docs/install

Adds the UltraMemory server to OpenClaw, reloads the configuration, and appends the active recall instructions to AGENTS.md.

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

--------------------------------

### Configure Windsurf MCP Server

Source: https://ultramemory.io/docs

Safe-merges the UltraMemory server into ~/.codeium/windsurf/mcp_config.json and appends the active-recall rule to AGENTS.md.

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

--------------------------------

### Configure UltraMemory in .mcp.json

Source: https://ultramemory.io/docs/usage-guide

Define the UltraMemory MCP server in a .mcp.json file at the project root as an alternative to the CLI command.

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

--------------------------------

### Codex: Register UltraMemory MCP and append active recall to AGENTS.md (shell)

Source: https://ultramemory.io/docs/install

Adds the UltraMemory MCP server configuration to ~/.codex/config.toml (if not already present) and appends an active recall instruction to AGENTS.md. Replace um_YOUR_KEY with your actual API key.

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

--------------------------------

### Cursor rule configuration (ultramemory.mdc)

Source: https://ultramemory.io/docs/usage-guide

A Cursor rule file configured to always apply the recall-first instruction.

```markdown
---
alwaysApply: true
---
# UltraMemory — recall first

Before answering, call the UltraMemory `memory_recall` (or `search`) MCP tool with the user's
request and ground your response in what it returns — prefer saved memories over your own
assumptions or any built-in memory. Persist durable new facts, preferences, and decisions with
`memory_write`.
```

--------------------------------

### Configure UltraMemory in claude.ai

Source: https://ultramemory.io/docs

Settings for adding the custom connector in the claude.ai interface.

```text
Settings → Connectors → Add custom connector
URL:  https://api.ultramemory.us/mcp
Auth: OAuth — sign in when prompted (no API key)
```

--------------------------------

### Configure UltraMemory MCP server in Cursor

Source: https://ultramemory.io/docs/usage-guide

Add this JSON to .cursor/mcp.json (project root) or ~/.cursor/mcp.json (global). Uses ${env:ULTRAMEMORY_KEY} to keep the API key out of committed files; set export ULTRAMEMORY_KEY=YOUR_API_KEY_HERE in your shell profile, or inline the key directly.

```json
{
  "mcpServers": {
    "ultramemory": {
      "url": "https://api.ultramemory.us/mcp",
      "headers": { "Authorization": "Bearer ${env:ULTRAMEMORY_KEY}" }
    }
  }
}
```

--------------------------------

### Cursor: Register UltraMemory MCP and append active recall to AGENTS.md (shell)

Source: https://ultramemory.io/docs/install

Writes the UltraMemory MCP server configuration to ~/.cursor/mcp.json and appends an active recall instruction to AGENTS.md. Uses python3. Replace um_YOUR_KEY with your actual API key.

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

--------------------------------

### Configure Windsurf MCP Server

Source: https://ultramemory.io/docs/install

Updates the Windsurf MCP configuration file and appends the active recall instructions to AGENTS.md.

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

--------------------------------

### Configure ~/.gemini/settings.json for UltraMemory

Source: https://ultramemory.io/docs/usage-guide

Add the UltraMemory MCP server configuration to your settings file. The httpUrl field specifies the streamable-HTTP transport.

```json
{
  "mcpServers": {
    "ultramemory": {
      "httpUrl": "https://api.ultramemory.us/mcp"
    }
  }
}
```

--------------------------------

### Supersede a part and time-travel recall

Source: https://ultramemory.io/docs

Shows how to supersede a fact by writing to the same entity and key, and then how to recall the historical truth using the as_of parameter.

```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"}'
```

--------------------------------

### Optional gated recall with curl

Source: https://ultramemory.io/docs

Run recall through the metamemory gate. On a fresh tenant with no grounded memory, the gate correctly abstains, which is expected behavior.

```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?"}'
```

--------------------------------

### Cursor: Register UltraMemory MCP and append active recall to AGENTS.md (PowerShell)

Source: https://ultramemory.io/docs/install

PowerShell equivalent for writing the UltraMemory MCP server configuration to ~/.cursor/mcp.json and appending the active recall instruction to AGENTS.md. Uses python instead of python3 because of the Windows Store stub. Replace um_YOUR_KEY with your actual API key.

```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.
'@
```
Tokens:
Raw