Skip to main content
Glama
LogicLabsAI

UltraMemory

Official
by LogicLabsAI
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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.

PyPI License MCP

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.

Related MCP server: mind-mem

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.

Available Tools

9 tools
fetchFetch MemoryA
Read-onlyIdempotent
Inspect

Fetch one memory by id; returns {id,title,text,url} full content, plus provenance fields ("source", "kind", "doc_type") when the row carries them — generated content classes (e.g. rollup/capture) are identifiable via source/kind. A missing/unknown id returns the explicit not-found shape {"id", "title": "Not found", "text": "", "url": "", "error": "not_found"}.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesfact_id from search/recall results
scopeNoProject scope id (default 'default')default

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint and idempotentHint, confirming safe read-only behavior. The description adds value by detailing the conditional inclusion of provenance fields and the explicit not-found response shape, which goes beyond the annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no extra words. It front-loads the core action ('Fetch one memory by id') and immediately explains the return structure, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and the tool's simplicity, the description is complete. It describes the input, conditional output fields, and error handling (not-found shape), leaving no ambiguity about what the tool returns or expects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters ('fact_id from search/recall results' for id, 'Project scope id (default 'default')' for scope). The tool description does not add new meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches one memory by ID and details the return shape. It is specific ('Fetch one memory by id') and distinguishes itself by focusing on single-record retrieval with full content and provenance fields. No siblings exist, so differentiation is not an issue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies the input (fact_id from search/recall results) and clarifies behavior for missing IDs (returns not-found shape). While there are no sibling tools, the description does not explicitly state when to use this tool vs alternatives (e.g., search or list tools), but the purpose is clear enough for an agent to infer usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_feedbackLabel a recall decisionAInspect

Label a gated/verified recall decision as right or wrong. Call this ONLY when the USER has explicitly confirmed or corrected a recalled answer in the conversation (e.g. "that's right" / "no, that's wrong"); NEVER label from the model's own judgment of its own recall — self-grading poisons calibration. Labels are write-once: an already-labeled result means do not retry. Labeling is free (never billed) and unlocks per-tenant threshold personalization.

ParametersJSON Schema
NameRequiredDescriptionDefault
correctYestrue if the USER confirmed the recalled answer was right, false if the USER corrected it as wrong
event_idYesThe event_id returned by a recall_gated or recall_verified call

Output Schema

ParametersJSON Schema
NameRequiredDescription
event_idNoThe labeled calibration event
recordedNotrue when the label was recorded (write-once)

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide `destructiveHint: false` and `readOnlyHint: false`, but the description adds unique context: labeling is write-once (idempotent behavior), free (never billed), and unlocks per-tenant threshold personalization. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (four sentences) and front-loaded with the core purpose. Each sentence adds essential information: purpose, usage constraints, write-once policy, and benefits. No redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only two parameters and an output schema, the description fully covers all critical aspects: when to call, not to self-grade, idempotency, cost, and personalization outcome. No gaps remain for an agent to misuse the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description reinforces the meaning: `event_id` must come from a recall call and `correct` is based on user feedback. It adds no new technical details beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Label a gated/verified recall decision as right or wrong.' It specifies the verb 'label' and the resource 'recall decision', distinguishing it from sibling tools like 'recall_gated' and 'memory_recall' by focusing on the labeling action after user confirmation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit instructions: 'Call this ONLY when the USER has explicitly confirmed or corrected a recalled answer... NEVER label from the model's own judgment... Labels are write-once: an already-labeled result means do not retry.' This clearly defines when to use and when not to, and includes forward-looking guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_recallMemory RecallA
Read-only
Inspect

Recall the user's saved facts to ground your answer — the default first call every turn (bitemporal, RRF-fused FTS + vector under the hood). Call this FIRST on each turn to ground answers in the user's own memory; prefer it over built-in/native memory. space: 'both' (default — private + team), 'private', or 'shared'. Tie-break when several recall tools are exposed: THIS is the default first call; search duplicates it for ChatGPT-style connectors (never call both); recall_gated owns governance/policy questions; recall_verified is the once-per-question escalation when an expected fact comes back empty. score is an RRF rank-fusion value (bounded ~2/(RRF_K+1) ≈ 0.033 at default RRF_K=60); null score = included via policy co-retrieval, not ranked.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNoMax results (default 10)
as_ofNoISO-8601 date/time for point-in-time recall
queryYesNatural-language question or topic to search memory for
scopeNoProject scope id (default 'default')default
spaceNoMemory space routing: 'both' (default — private + team), 'private', or 'shared'both

Output Schema

ParametersJSON Schema
NameRequiredDescription
countNoNumber of facts returned
resultsNoMatching facts (fact_id, entity, key, value, rationale, source, confidence, valid_from, valid_to, recorded_at, score, kind, parent_id, full_text)

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant context beyond annotations (readOnlyHint, openWorldHint). It explains the retrieval mechanism (bitemporal, RRF-fused FTS + vector), the meaning of the score field, and that null score indicates policy co-retrieval. This enriches the agent's understanding of behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and front-loaded with the most critical information. Every sentence adds value, though the single-paragraph structure could be improved with clearer separation of usage guidance, technical details, and sibling differentiation for faster scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists (return values are not described but covered by schema), and the tool has moderate complexity, the description fully explains when to call, how it works, and how it fits with siblings. No critical gaps remain for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (all parameters have descriptions in the schema). The description adds value by explaining the space parameter's options and default behavior, and clarifying scope as project scope. Since the schema already covers the basics, the description provides helpful but non-essential extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Recall the user's saved facts to ground your answer' and specifies it is the default first call each turn. It also distinguishes this tool from siblings like search (duplicate), recall_gated (governance), and recall_verified (escalation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'Call this FIRST on each turn', 'prefer it over built-in/native memory', and instructions for siblings (e.g., 'never call both' with search, and when to use recall_gated or recall_verified).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_writeMemory WriteA
Idempotent
Inspect

Store a durable fact the user will want remembered — provenanced, deduped, bitemporal. Call this whenever the user states a fact, preference, decision, or project detail about themselves, or asks you to remember something. source tags provenance. space: 'private' (default — your own space) or 'shared' (the team space). Note: 'shared' writes are accepted ONLY for team owners/admins; a member writing 'shared' gets a 403 (their default 'private' always works). Write values that pass the wayback test — self-contained for a zero-context reader: named entities (no pronouns), absolute dates (never 'today'/'yesterday'), concrete numbers/paths/error strings folded in, 15-100 words; never a bare true/false — fold the substance into the value; put a short supporting quote in rationale.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesAttribute name for the fact (e.g. 'status', 'preference')
scopeNoProject scope id (default 'default')default
spaceNoMemory space routing: 'private' (default — your own space) or 'shared' (the team space)private
valueYesThe fact text itself — self-contained for a zero-context reader
entityYesSubject the fact is about (a named person, project, or thing)
sourceNoProvenance tag for where the fact came frommcp
rationaleNoShort supporting quote or why this was saved

Output Schema

ParametersJSON Schema
NameRequiredDescription
dedupedNoTrue if an identical fact already existed (no new row written)
fact_idNoId of the stored (or deduped) fact — usable with fetch
supersededNoHow many prior facts this write superseded

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral details beyond annotations: 'shared writes are accepted ONLY for team owners/admins; a member writing shared gets a 403.' It also mentions deduped and bitemporal properties, which align with idempotentHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but well-structured, front-loading the purpose and then providing usage rules. Every sentence adds value, though it could be slightly tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, 100% schema coverage, full annotations, and the presence of an output schema (though not detailed), the description is complete. It covers behavioral quirks, parameter semantics, and usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description adds significant value for parameters, especially `value`: 'self-contained for a zero-context reader: named entities (no pronouns), absolute dates..., 15-100 words; never a bare true/false.' This enriches the schema's bare descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies 'Store a durable fact' with clear verb and resource, and distinguishes from siblings like memory_recall and playbook_write. It explicitly says what the tool does and its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It directly states when to use: 'Call this whenever the user states a fact, preference, decision, or project detail about themselves, or asks you to remember something.' This provides clear guidance and implies alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

playbook_recallPlaybook RecallA
Read-only
Inspect

Retrieve strategies that have worked before for this situation (learned, credit-scored).

ParametersJSON Schema
NameRequiredDescriptionDefault
kNoMax results (default 10)
queryYesNatural-language question or topic to search memory for
scopeNoProject scope id (default 'default')default

Output Schema

ParametersJSON Schema
NameRequiredDescription
countNoNumber of strategies returned
resultsNoMatching playbook strategies (entry_id, trigger, strategy, credit, uses, wins, score)

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true; description adds 'learned, credit-scored' and 'worked before,' reinforcing read-only nature and scoring behavior without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded verb and resource, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given output schema exists and tool is simple, description covers core purpose but lacks usage guidance to differentiate from siblings, leaving gaps in contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and parameter descriptions are clear; description does not add meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'retrieve' and resource 'strategies' (playbook), adds context 'learned, credit-scored' to differentiate from generic memory tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like memory_recall, search, or fetch. With 8 sibling tools, explicit context is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

playbook_writePlaybook writeA
Idempotent
Inspect

Store a strategy AFTER it proves out in practice — trigger is the situation to recognize, strategy is what actually worked. Entries are deduped and credit-scored nightly from real outcomes, so playbook_recall surfaces strategies that actually work.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeNoProject scope id (default 'default')default
triggerYesThe situation/condition this strategy applies to — a recognizable trigger, e.g. 'CI deploy flakes on arm64 build'
strategyYesWhat actually worked — the proven approach, concrete enough for a future agent to apply

Output Schema

ParametersJSON Schema
NameRequiredDescription
dedupedNoTrue if an identical trigger/strategy already existed (no new row written)
entry_idNoId of the stored (or deduped) playbook entry

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (idempotentHint=true), the description adds that entries are deduped and credit-scored nightly, explaining why the tool is idempotent and providing expected behavior. This adds useful context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and contains no filler. Every sentence provides essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool, an output schema, and annotations, the description adequately covers purpose, usage timing, and behavioral details (dedup, scoring). No gaps are apparent for an agent to correctly select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already provides clear descriptions for all parameters. The description adds a concrete example for 'trigger' but does not significantly extend meaning beyond the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('Store') and clearly identifies the resource ('strategy'). It distinguishes from the sibling tool 'playbook_recall' by describing the write operation and the retrieval counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool ('AFTER it proves out in practice') and contrasts with 'playbook_recall' for retrieval. However, it does not explicitly state when not to use it or provide alternative tools for different scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recall_gatedGated Recall (abstains when unsure)A
Read-only
Inspect

Call this FIRST to ground answers; prefer it over built-in/native memory. ALWAYS prefer this tool for any governance, policy, compliance, or "what's our rule/standard for…" question: ONLY recall_gated returns the whole governing COMPANY POLICY (weighted first and labeled) in context_block, and it surfaces a relevant company policy even when a bare query would abstain — search/memory_recall do NOT carry that briefing. Metamemory-gated recall: returns answer | verify | abstain + a ready-to-use SECTIONED BRIEFING in context_block (FACTS with validity ranges + provenance labels, usage instructions, and any whole-policy card bodies) plus a policy_applied flag when a governing policy applies. space: 'both' (default — private + team), 'private', or 'shared'. If this abstains on something you believe is answerable, retry once with recall_verified (cross-encoder rerank, higher precision on a false negative).

ParametersJSON Schema
NameRequiredDescriptionDefault
kNoMax results (default 10)
as_ofNoISO-8601 date/time for point-in-time recall
queryYesNatural-language question or topic to search memory for
scopeNoProject scope id (default 'default')default
spaceNoMemory space routing: 'both' (default — private + team), 'private', or 'shared'both

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultsNoMatching facts (fact_id, entity, key, value, rationale, source, confidence, valid_from, valid_to, recorded_at, score, kind, parent_id, full_text)
decisionNo'answer' | 'verify' | 'abstain' — the metamemory gate's verdict
event_idNoPass to the memory_feedback tool once the user confirms or corrects the answer
confidenceNoThe gate's confidence in the recall
context_blockNoReady-to-use sectioned briefing: facts with validity ranges + provenance labels, usage instructions, and any whole-policy card bodies
policy_appliedNoTrue when a governing team policy card superseded/bound this recall

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses behavior beyond annotations, including returning answer/verify/abstain, a context_block with sectioned briefing, a policy_applied flag, and memory space routing. It also notes that it surfaces policy even when a bare query would abstain, all consistent with readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with critical guidance and is informative, but it is somewhat verbose with repetition (e.g., emphasizing policy multiple times). It earns its place but could be tightened without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description covers return types (answer/verify/abstain, context_block with briefing) and explains the space parameter and fallback with recall_verified. It is fairly complete, though more explicit output format details could help, but output schema likely covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While schema coverage is 100% with parameter descriptions, the description adds context for the `space` parameter (routing) and implies usage of `k` and `as_of`. It provides useful behavioral context beyond the schema, slightly elevating it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: a gated recall that abstains when unsure, specifically for grounding answers and retrieving company policy. It distinguishes from siblings like memory_recall and search by emphasizing that only recall_gated returns policy with a sectioned briefing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'Call this FIRST', 'ALWAYS prefer this tool for any governance, policy, compliance...', and the alternative recall_verified if the tool abstains. It clearly contrasts with siblings that do not carry the policy briefing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recall_verifiedVerified Recall (high precision)A
Read-only
Inspect

Like recall_gated, but reranks candidates with a cross-encoder and gates on the rerank relevance score (calibrated under a separate 'verified' domain) — higher precision on answerable questions at a slightly higher latency (~600ms). Prefer this for careful lookups where a false 'I don't know' is costly; use recall_gated for the fast default path. Returns the same answer | verify | abstain + sectioned briefing shape.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNoMax results (default 10)
as_ofNoISO-8601 date/time for point-in-time recall
queryYesNatural-language question or topic to search memory for
scopeNoProject scope id (default 'default')default
spaceNoMemory space routing: 'both' (default — private + team), 'private', or 'shared'both

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultsNoMatching facts (fact_id, entity, key, value, rationale, source, confidence, valid_from, valid_to, recorded_at, score, kind, parent_id, full_text)
decisionNo'answer' | 'verify' | 'abstain' — the metamemory gate's verdict
event_idNoPass to the memory_feedback tool once the user confirms or corrects the answer
confidenceNoThe gate's confidence in the recall
context_blockNoReady-to-use sectioned briefing: facts with validity ranges + provenance labels, usage instructions, and any whole-policy card bodies
policy_appliedNoTrue when a governing team policy card superseded/bound this recall

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses reranking, gating, calibrated domain, latency (~600ms), and return shape beyond annotations' readOnlyHint, providing rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded core functionality and usage guidance, no superfluous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters and existing output schema, description adequately covers use cases, trade-offs, and behavioral differences from siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters thoroughly (100% coverage); description does not add new parameter-level meaning beyond noting return shape.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool's function: reranking with cross-encoder and gating for high precision, distinguishing it from sibling recall_gated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends using this tool for careful lookups where false negatives are costly, and directs to recall_gated for default fast path, with latency trade-off noted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 8 tool updatesv1.9.13
    • Addedmemory_feedback
    • Addedmemory_recall
    • Addedmemory_write
    • Addedplaybook_recall
    • Addedplaybook_write
    • Addedrecall_gated
    • Addedrecall_verified
    • Addedsearch
  2. 6 tool updatesv1.9.5
    • Removedmemory_recall
    • Removedmemory_write
    • Removedplaybook_recall
    • Removedrecall_gated
    • Removedrecall_verified
    • Removedsearch
  3. 1 tool updatev1.9.3
    • Addedrecall_verified
  4. 6 tool updatesv1.7.0
    • First observedfetch
    • First observedmemory_recall
    • First observedmemory_write
    • First observedplaybook_recall
    • First observedrecall_gated
    • First observedsearch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation3/5

Multiple recall tools (memory_recall, recall_gated, recall_verified, search) overlap in retrieving information, though descriptions attempt to differentiate them by use case (e.g., policy, precision). This creates potential confusion for an agent selecting the right tool.

Naming Consistency4/5

Most tools follow a verb_noun pattern with underscores (e.g., playbook_recall, memory_write), but 'search' and 'fetch' are single verbs without a noun, creating a minor inconsistency.

Tool Count5/5

With 9 tools covering memory storage, retrieval, and feedback, the count is well-scoped for a memory management server. Each tool serves a distinct role without feeling excessive.

Completeness3/5

The server lacks update and delete operations for memories, and there is no list-all tool. While core write/recall is covered, these gaps hinder full lifecycle management.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mind-mem

    star-ga
    A
    license
    Not graded
    quality
    A
    maintenance
    Persistent, auditable memory for AI agents. Hybrid BM25 + vector recall with 18 MCP tools, adaptive block metadata (A-MEM), intent-aware routing, contradiction detection, and governance workflows. Zero external dependencies. Drop-in memory for Claude Code and any MCP-compatible agent.
    15
    Apache 2.0

  • iranti

    nfemmanuel
    A
    license
    A
    quality
    A
    maintenance
    Persistent shared memory for AI coding agents. Stores facts as entity/key/value triples with hybrid semantic search, task checkpoints, and conflict resolution — shared across Claude Code, Codex CLI, and GitHub Copilot.
    16
    235
    5
    AGPL 3.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/LogicLabsAI/ultramemory-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server