Tools
Tools reference
UltraMemory exposes nine MCP tools. Six are read-only recall surfaces; three — memory_write, memory_feedback, and playbook_write— write. Every parameter description below is the live server's own field description, and each tool fronts the same REST API on /api/v1/*.
Which tool does the agent call?
memory_recall is the default first call on every turn. search duplicates it for ChatGPT-style connectors — an agent should never call both. recall_gated owns governance and policy questions: only it returns the whole governing COMPANY POLICY briefing. recall_verified is the once-per-question escalation when an expected fact comes back empty. fetch re-reads one specific memory, playbook_recall retrieves learned strategies, and memory_write persists durable new facts.
Read-only recall
All six tools in this group advertise readOnlyHint: true (search and fetch add idempotentHint: true) — none of them modifies memory.
memory_recall
Recall the user's saved facts (bitemporal, RRF-fused full-text + vector search) — the default first call to ground an answer in the user's own memory. REST: POST /api/v1/recall.
| Name | Type | Required / default | Description |
|---|---|---|---|
| query | string | required | Natural-language question or topic to search memory for |
| scope | string | default "default" | Project scope id (default 'default') |
| k | integer | default 10 | Max results (default 10) |
| as_of | string | null | default null | ISO-8601 date/time for point-in-time recall |
| space | string | default "both" | Memory space routing: 'both' (default — private + team), 'private', or 'shared' |
recall_gated
Metamemory-gated recall — returns a decision of answer | verify | abstain plus a ready-to-use sectioned briefing in context_block, and it is the only tool that returns the whole governing COMPANY POLICY (with a policy_applied flag) when one applies. REST: POST /api/v1/recall/gated.
Decision semantics: answer — the gate is confident, use the briefing; verify — medium confidence, verify before relying on it; abstain — the gate declines rather than guess. Abstaining beats confabulating.
| Name | Type | Required / default | Description |
|---|---|---|---|
| query | string | required | Natural-language question or topic to search memory for |
| scope | string | default "default" | Project scope id (default 'default') |
| k | integer | default 10 | Max results (default 10) |
| as_of | string | null | default null | ISO-8601 date/time for point-in-time recall |
| space | string | default "both" | Memory space routing: 'both' (default — private + team), 'private', or 'shared' |
recall_verified
Like recall_gated, but reranks candidates with a cross-encoder and gates on the rerank relevance score — higher precision on answerable questions at slightly higher latency (~600ms). Same answer | verify | abstain decision and sectioned-briefing shape; call it once per question when a recall abstains on something the user has saved. REST: POST /api/v1/recall/gated with verified: true.
| Name | Type | Required / default | Description |
|---|---|---|---|
| query | string | required | Natural-language question or topic to search memory for |
| scope | string | default "default" | Project scope id (default 'default') |
| k | integer | default 10 | Max results (default 10) |
| as_of | string | null | default null | ISO-8601 date/time for point-in-time recall |
| space | string | default "both" | Memory space routing: 'both' (default — private + team), 'private', or 'shared' |
search
Connector shim over the same recall, built for ChatGPT Deep Research / Company Knowledge — returns matching facts with their full text inline plus a citation url. If memory_recall is also exposed, agents should prefer it and skip this tool. REST: POST /api/v1/recall.
| Name | Type | Required / default | Description |
|---|---|---|---|
| query | string | required | Natural-language question or topic to search memory for |
| scope | string | default "default" | Project scope id (default 'default') |
| k | integer | default 10 | Max results (default 10) |
| space | string | default "both" | Memory space routing: 'both' (default — private + team), 'private', or 'shared' |
fetch
Fetch one memory by id — returns its id, title, full text, and url, plus provenance fields (source, kind, doc_type) when the row carries them. The id must be the full UUID fact_id exactly as returned by search/recall results — a shortened 8-character prefix returns the explicit not_found shape instead of a guess. REST: POST /api/v1/fact.
| Name | Type | Required / default | Description |
|---|---|---|---|
| id | string | required | fact_id from search/recall results |
| scope | string | default "default" | Project scope id (default 'default') |
playbook_recall
Retrieve learned, credit-scored strategies for a situation — trigger → strategy entries with credit and usage stats. REST: POST /api/v1/playbook/recall.
| Name | Type | Required / default | Description |
|---|---|---|---|
| query | string | required | Natural-language question or topic to search memory for |
| scope | string | default "default" | Project scope id (default 'default') |
| k | integer | default 10 | Max results (default 10) |
Write
memory_write advertises readOnlyHint: false with destructiveHint: false and idempotentHint: true — a deduped, non-destructive bitemporal append.
memory_write
Store a durable, provenanced fact (deduped, bitemporal) — called whenever the user states a fact, preference, decision, or project detail, or asks the assistant to remember something. space: "shared" writes are accepted only for team owners/admins; a member writing shared gets a 403 (their default private always works). REST: POST /api/v1/permanent.
| Name | Type | Required / default | Description |
|---|---|---|---|
| entity | string | required | Subject the fact is about (a named person, project, or thing) |
| key | string | required | Attribute name for the fact (e.g. 'status', 'preference') |
| value | string | required | The fact text itself — self-contained for a zero-context reader |
| rationale | string | default "" | Short supporting quote or why this was saved |
| scope | string | default "default" | Project scope id (default 'default') |
| source | string | default "mcp" | Provenance tag for where the fact came from |
| space | string | default "private" | Memory space routing: 'private' (default — your own space) or 'shared' (the team space) |
playbook_write
Store a learned strategy after it proves out — trigger (the situation) plus strategy (what worked). Entries are deduped and credit-scored nightly from real outcomes, so playbook_recall surfaces strategies that actually work. REST: POST /api/v1/playbook.
| Name | Type | Required / default | Description |
|---|---|---|---|
| trigger | string | required | The situation this strategy applies to |
| strategy | string | required | What worked in that situation |
| scope | string | default "default" | Project scope id (default 'default') |
Feedback
memory_feedback advertises readOnlyHint: false with destructiveHint: false — it records a write-once calibration label and never edits a memory.
memory_feedback
Label a recall decision — mark a gated/verified recall decision as right or wrong. The agent calls it ONLY when the user has explicitly confirmed or corrected a recalled answer; it never labels from the model grading its own recall — self-grading poisons calibration. Labels are write-once (an already-labeled result means do not retry), and labeling is free — it is never billed. Each label unlocks per-tenant threshold personalization: the gate self-learns from your confirmations. The event_id comes from a recall_gated / recall_verified response. REST: POST /api/v1/feedback.
| Name | Type | Required / default | Description |
|---|---|---|---|
| event_id | string | required | The event_id returned by a recall_gated or recall_verified call |
| correct | boolean | required | true if the USER confirmed the recalled answer was right, false if the USER corrected it as wrong |
REST access and error codes
The tools front the REST API on /api/v1/* (per-tool endpoints above) with the same bearer key — Authorization: Bearer um_YOUR_KEY. A ready-to-copy curl example lives on the Quickstart.
Error responses: 401 — invalid, revoked, or disabled key; 402 — payment past due (your memories stay safe); 429 — rate or usage limit, with the exact reset time. Full meanings on the Billing page.
A note on annotations
Per the MCP spec, tool annotations (readOnlyHint, idempotentHint, and friends) are advisory hints for clients — useful for display and confirmation flows, but not a security boundary. The UltraMemory server enforces authentication and tenant isolation on every call regardless of how any client treats the hints.