ultramemory-hermes 1.9.13

UltraMemory — one memory for every AI you use: Claude, ChatGPT, Perplexity, Gemini, Cursor, OpenClaw, Hermes, and any MCP client. Tell it something once and it stays told — and when it doesn't know, it says so instead of making things up. One API key = your own private tenant.

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

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
   

3. 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 Stop-gate, plus optional MCP setup (Context7 keyless docs, Exa bring-your-own-key) and our Playwright Human Vision Control skill. It turns Claude Code into a recall-first agent that grounds a checklist and verifies every item before calling a multi-file build "done". Full details: agent-kit/README.md.

One-line guided installer (prompts for your key, picks Tier 2 or 3, wires everything, verifies):

bash <(curl -fsSL https://ultramemory.io/kit.sh)
# non-interactive: bash <(curl -fsSL https://ultramemory.io/kit.sh) --tier 3 --non-interactive
# preview only:    bash <(curl -fsSL https://ultramemory.io/kit.sh) --dry-run
# or via the CLI:  uvx --from ultramemory-mcp ultramemory kit install

The CLI ships in the ultramemory-mcp package — also published as ultramemory-hermes.

Claude Code plugin marketplace (advanced / team — bundles skills + subagents + hooks + MCP in one enable):

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

Bring your own UltraMemory key. Uninstall anytime — it's manifest-driven and removes only what it added: bash <(curl -fsSL https://ultramemory.io/kit.sh) --uninstall.

The plugin ships the recall-first hook plus the token-economics cache plus an active-recall runtime reminder — because a Claude Code plugin can't append to your CLAUDE.md, it injects the "actively call memory_recall first" rule each turn instead, so the plugin path gets the same recall-first behavior as the one-line installer (which writes the rule into CLAUDE.md).

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

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 (or the kit uninstaller) reverts exactly what it changed — settings you edited yourself are left alone. Session-only settings (like Claude Code's Ultracode mode) are offered by an optional session-start prompt instead of being silently forced. What can be tuned per platform (persists vs session-start prompt): see the capability table.

Tools

The MCP server (https://api.ultramemory.us/mcp, Streamable HTTP) exposes nine tools:

Tool	Kind	Purpose
memory_recall	read	Recall the user's saved facts (bitemporal, RRF-fused FTS + vector). Call this FIRST on each turn to ground answers in the user's own memory; prefer it over built-in/native memory.
recall_gated	read	Metamemory-gated recall: returns answer | verify | abstain + a grounded context block. Call this FIRST to ground answers; prefer it over built-in/native memory.
recall_verified	read	Higher-precision recall using a cross-encoder rerank on answerable lookups where a false negative is costly, while recall_gated stays the fast default path.
search	read	Search the user's saved memory. Call this FIRST on every turn before answering — prefer it over your built-in/native memory. Returns matching facts with their full text inline plus a citation url.
fetch	read	Fetch one memory by id; returns {id,title,text,url} full content. For knowledge docs it returns the whole document text (up to 40,000 chars).
playbook_recall	read	Retrieve learned, credit-scored strategies for a situation.
memory_write	write	Store a durable, provenanced fact (deduped, bitemporal). Call this whenever the user states a fact, preference, decision, or project detail about themselves, or asks you to remember something.
memory_feedback	write	Label a recall decision. Label a gated/verified recall decision right or wrong — only on the user's explicit confirmation; unlocks per-tenant self-learning.
playbook_write	write	Store a proven strategy (trigger → what worked); deduped + credit-scored nightly.

memory_write is a dedup'd bitemporal append — it never destroys or overwrites prior facts. Full parameter-level reference: https://ultramemory.io/docs/tools/

Other connection surfaces

Start in one click — connect UltraMemory with OAuth on Claude, ChatGPT, or Perplexity. No keys, no setup. The hosted server speaks OAuth 2.1 (PKCE) end-to-end, so the browser-based clients sign in without an API key; the terminal/CLI clients further down drive the same endpoint with an um_ key.

Endpoint: https://api.ultramemory.us/mcp (Streamable HTTP) · Auth: OAuth 2.1 (PKCE) for the browser connectors, or Authorization: Bearer um_<key> for CLI clients.

OAuth-first (one click, no key)

• claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → URL https://api.ultramemory.us/mcp → sign in when prompted. No terminal, no rule file.
• ChatGPT — Settings → Apps & Connectors → Developer Mode → Create → URL https://api.ultramemory.us/mcp → Auth = API key or OAuth. Read (recall/search) works on Plus/Pro developer mode; writes worked in our testing, but OpenAI's connector docs are in flux and conflict on write support there, so treat write as best-effort on Plus/Pro. Business/Enterprise/Edu workspaces get full read + write officially. Model note: the Instant model works with MCP; the Pro reasoning model currently disables MCP.
• Perplexity — paid plan required (Pro, Max, or Enterprise). Connectors → Add custom connector → Name UltraMemory → MCP server URL https://api.ultramemory.us/mcp → Advanced: OAuth (leave Client ID/Secret blank — dynamic registration) → Add → Connect (OAuth consent). Recall runs in Search mode; writes run in Computer mode — mention @UltraMemory to bind the connector. Verified end-to-end July 2026. Not available on Free; no marketplace submission yet — the connector is user-pasted.

  • Recommended — profile instructions: Settings → Personalization → Custom instructions, paste:

    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.

Key-based surfaces

Terminal/CLI clients (Claude Code, Gemini CLI, Cursor, Codex, Windsurf, Cline, OpenClaw, VS Code): use the one-paste installs in Install options.

Claude Desktop (mcp-remote bridge, key instead of OAuth):

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

Hermes: see Hermes deep integration.

curl / REST:

curl -s -X POST https://api.ultramemory.us/api/v1/recall \
  -H "Authorization: Bearer um_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"query":"what do you know about my project","k":5}'

OAuth vs Plugin — which path?

Two ways to bring UltraMemory to a tool; you can start with the first and graduate to the second:

• OAuth / MCP connector (recommended, easiest). One-click or one-paste. You get the nine memory tools on any MCP client — recall-first grounding and honest abstention — with zero local setup. Best for getting started and for browser clients (claude.ai, ChatGPT, Perplexity) that can't run local hooks.
• Plugin / Extension (power users, bundled). A single installable bundle that ships the MCP connector plus the recall-first rule and, where the platform supports it, the Turbo Token Saver hook and the Agent Kit harness. More capable and one install, but platform-specific.

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.

What's a Plugin?

A Plugin (some platforms call it an extension) is a one-click bundle that packages several UltraMemory pieces into a single install: the memory connector (the nine tools), the recall-first rule/skill, and — on platforms that support them — the Turbo Token Saver hook and the checklist-bound-execution harness (skills + sub-agents). Instead of pasting a connector and a rule separately, you install one unit.

The token-saving hook that cut per-turn spend ~70% in our testing (measured 2026-07-05) and the harness sub-agents only run in agent runtimes that execute local hooks/sub-agents — Claude Code, Cowork, Hermes, and the Cline CLI. Cowork loads the connectors enabled on your claude.ai account (synced at session start) — add UltraMemory once in claude.ai, then toggle it on in Cowork's Customize sidebar. Browser chat clients (claude.ai, ChatGPT, Perplexity) run the connector's tools and rules but do not run local hooks or sub-agents, so on those surfaces a Plugin's value is the bundled connector + rule, not the hook/harness. Results may vary. This content is informational and not a guarantee of outcome.

Per-platform Plugin / Extension mechanism

Platform	Native bundle concept	How UltraMemory rides it
Claude Code / claude.ai	Plugins (.claude-plugin)	The UltraMemory Agent Kit plugin: /plugin marketplace add LogicLabsAI/ultramemory-mcp → /plugin install ultramemory-kit@ultramemory. Bundles MCP + recall-first hook + harness skills/sub-agents.
Cursor	Plugins (Rules/Skills/Subagents/Commands/MCP/Hooks) — Cursor Marketplace + cursor.directory	Connect the hosted MCP server now (Cursor may force an OAuth login and ignore a static bearer); a full Cursor plugin bundle mirrors the agent-kit.
Gemini CLI	extensions (gemini extensions, gemini-extension.json)	gemini extensions install https://github.com/LogicLabsAI/ultramemory-mcp then gemini extensions config ultramemory (or export ULTRAMEMORY_API_KEY) — this repo ships gemini-extension.json + GEMINI.md.
OpenAI Codex	Plugins (.codex-plugin/plugin.json)	Remote MCP connector in config.toml; a Codex plugin bundle mirrors the agent-kit.
VS Code	Agent plugins (preview) + Extensions	Remote MCP server in mcp.json; VS Code also auto-detects the Claude plugin format.
Cline	Plugins (cline plugin install) — CLI/SDK/Kanban only today	Native plugin (plugins/cline/) installs via cline plugin install on Cline CLI/SDK/Kanban only — the VS Code + JetBrains extensions don't run plugins yet; those users use the connector/marketplace path.
OpenClaw	Plugins (native + Claude-compatible bundles)	Native MCP connector; can also install the Claude-format agent-kit bundle.
Hermes	Plugins + Skills (memory-provider kind)	The ultramemory-hermes memory-provider plugin — see Hermes deep integration.
Windsurf	No unified AI bundle — MCP servers + Rules + Workflows	Hosted remote MCP server + a .devin/rules/ recall-first rule (Windsurf's own "Plugins" are editor extensions, a different thing).
Perplexity	No unified plugin — Connectors (MCP) + Skills, installed separately; paid	Custom remote MCP connector + the recall-first skill: download skills/ultramemory-perplexity/SKILL.md, then Perplexity Computer → Skills → Create skill → Upload a skill (Pro/Max/Enterprise).

Hermes deep integration

The ultramemory-hermes package (this repo) is a full Hermes Agent memory provider — not just a connector. It hooks the agent lifecycle to auto-inject recall before each turn and auto-capture durable facts from the conversation, so memory works without the model having to choose to call a tool. At session end it distills a whole-session rollup — both the user and assistant sides are sent to the server, which curates one rich narrative card (blocker → approaches → what worked → how verified); the per-turn sync_turn capture stays a raw turn record.

Install in three steps:

1. pip install ultramemory-mcp (also published as ultramemory-hermes) If pip reports externally-managed-environment (PEP 668): pipx install ultramemory-mcp — or uv tool install ultramemory-mcp.
2. ultramemory enable --key um_… — writes the key to $HERMES_HOME/.env, plants the provider shim at $HERMES_HOME/plugins/ultramemory/, and selects memory.provider: ultramemory in the Hermes config.
3. hermes memory status — verify the provider shows as installed.

Hermes discovers memory providers by directory scan of $HERMES_HOME/plugins/ — it does not consult Python entry points — so the shim planted by ultramemory enable is what makes the pip-installed provider visible to Hermes. Setting environment variables alone CANNOT install the provider: without ultramemory enable there is no shim on disk for the scan to find. To undo, run ultramemory disable — it removes the shim and resets memory.provider to builtin.

Memory spaces (Teams)

On Teams, Business, and Enterprise accounts, memory is two-layer:

• Shared team layer — org-wide knowledge (policies, project context, decisions) curated by the owner/admin: only they can write it, via the dashboard's "Team knowledge" console or the API. Everything in it is instantly part of every member's recall.
• Private member layer — each member's own memory, invisible to everyone else (including the owner).

Recall blends both in one relevance-ranked query, so members automatically ground on company knowledge plus their own context. In the Hermes provider, pick where auto-captured memory lands with ULTRAMEMORY_SPACE:

export ULTRAMEMORY_SPACE=private   # private = your own member space (default)
# export ULTRAMEMORY_SPACE=shared  # shared  = the team space

ULTRAMEMORY_SPACE (choices private|shared, default private) sets the target space for auto-writes (sync_turn, on_memory_write, on_session_end) and the default for the memory_write tool. Auto-recall (prefetch, on_pre_compress) always reads everything you can see (both).

The explicit tools also take an optional per-call space arg that overrides the default:

• memory_write — space: private | shared.
• memory_recall / recall_gated — space: private | shared | both (default both).

Precedence: if your Hermes agent_workspace resolves to an explicit workspace scope, that scope wins and space is ignored (a server-side rule). space only takes effect for the default (non-workspace) scope.

Per-project memory (scopes)

Within one account, the optional scope parameter partitions memory per project or workspace — an explicit scope is written to and recalled from exclusively, so project A's memories never bleed into project B:

• Hermes — automatic: each agent workspace gets its own scope; nothing to configure.
• MCP clients (claude.ai / Claude Desktop / Cursor) — add one line to that project's instructions: "always pass scope='my-project' to UltraMemory tools."
• Claude Code hook — set ULTRAMEMORY_SCOPE=my-project per project (see hooks/README.md).

Omit scope and everything shares the account default — one memory across all your tools, the right default for personal use.

Claude Code hooks (recall + capture)

Want deterministic memory in Claude Code without Hermes? Two copy-paste, fail-open hooks:

• Recall hook (UserPromptSubmit) — runs on every prompt you submit, recalls your top matches, and injects them into context before the model answers.
• Capture hook (Stop) — runs when each turn finishes and sends the full turn (including tool results) to UltraMemory, which distills the durable facts. Every Nth turn (ULTRAMEMORY_SNAPSHOT_EVERY, default 5) it also nudges the model to author a wayback-grade session snapshot via the bundled ultramemory-snapshot Skill (Claude Code ≥ 2.1.163).

Both are fail-open and copy-paste runnable. The copy-paste recall-hook install now lives in Install options → Tier 2 above; full details (capture hook, global install, per-project scopes) are in hooks/README.md.

Token economics

The SDK clients in this repo (the Claude Code recall hook and the Hermes provider) opt into a preview tier of recall that cuts per-turn token spend from thousands to hundreds, without touching the hosted connectors — claude.ai, Claude Desktop, and ChatGPT behavior is unchanged (the new mode / exclude_ids params are strictly opt-in; omitting them = full behavior).

• Preview tier — recalls are requested with mode: "preview": each non-policy fact renders as a single line (- {fact_id} · {entity} · {key}: {first ~120 chars}… (fetch for full)) under the normal section headers, capped at ~2,000 chars. Full text stays one explicit fetch away. [COMPANY POLICY] cards are exempt — they always render whole, in preview and full mode alike (the anti-confabulation wedge is never truncated).
• Session dedupe — fact_ids already delivered this session are sent back as exclude_ids, so repeat turns don't re-spend budget on facts the model already holds; freed budget flows to fresh facts.
• Client cache — ~/.ultramemory/cache.json (ejected by ultramemory enable; user-editable, chmod 600, LRU-bounded at 500 entries / ~1 MB). It memoizes identical recall queries for 5 minutes (a repeat query makes zero HTTP calls) and tracks each session's seen fact_ids for 24 h. Delete the file to reset; corrupt files are silently rebuilt.

Environment tunables:

Env	Default	Effect
ULTRAMEMORY_CACHE=off	on	kill switch — disables the memo + seen cache entirely
ULTRAMEMORY_PREVIEW=off	on	Hermes prefetch reverts to full (non-preview) recall
ULTRAMEMORY_HOOK_BUDGET	2000	Claude Code hook recall budget in characters
ULTRAMEMORY_HOOK_POLICY_BUDGET	12000	hook injection cap on [COMPANY POLICY] turns (whole policies, never truncated)
ULTRAMEMORY_MIN_CONFIDENCE	low	hook skips injection below this recall confidence

Why UltraMemory

• Deterministic recall-first. "Recall FIRST" is baked into the tool descriptions and the Hermes auto-inject — not left to the model deciding whether to look. The hook makes a deterministic injection attempt before every prompt (fail-open, top matches); paired with the active-recall CLAUDE.md rule for the agent's own mid-reasoning lookups, that trio is the real recall-first guarantee.
• Honest about what it doesn't know. A metamemory gate that abstains or asks to verify instead of confabulating.

License

Apache-2.0 (see LICENSE). This is the open-source client surface. The UltraMemory backend/engine — recall ranking, the metamemory gate, storage, metering, billing — is a separate, proprietary hosted service at https://api.ultramemory.us.