Empirical Docs / MCP

MCP tool reference.

Choose the MCP function that matches the agent’s task: retrieve context, write or maintain memory, manage workspace scope, or discover Empirical guidance.

Install MCP in a client

MCP tools are available after a supported client connects to Empirical. Install the CLI before using local coding-agent setup; ChatGPT and Claude web use hosted app/connector flows instead.

npm install -g @empirical-gauzza/cli
empirical install

Read and query functions

Use these when an agent needs context before acting. Prefer query_memories for natural-language retrieval, list_memories for deterministic browsing, and get_memory when an exact ID is known.

  • query_memories — semantic search with category, tag, date, graph, and result-size filters; pass workspaceIds to search several workspaces in one merged call
  • get_memory — retrieve one memory by ID with metadata, notes, and version history
  • list_memories — browse deterministic pages and follow nextCursor while hasMore is true
  • get_memory_neighbors — get related memories and edges for a memory node, incoming, outgoing, or both
query_memories({ query: "deployment constraints", topK: 5 })
get_memory({ memoryId: "<id>" })

Write and maintain functions

Use the write tool only when the user’s context is durable and the action is authorized.

  • record_graph_memory — create or merge a durable memory from structured context
  • update_memory_relationships — add, remove, or replace relationships on a memory node
record_graph_memory({ category: "decision", summary: "Use OAuth for remote MCP" })

By-query convenience functions

Use these when the agent has a natural-language description but not a stable memory ID. They fuzzy-find the target first, so inspect the match and use confirmation for destructive actions.

  • add_note_by_query — find a memory and append a note
  • update_memory_by_query — find a memory and apply a patch (pass dueAt to set or re-date a reminder)
  • delete_memory_by_query — find a memory and delete only with confirm=true
  • acknowledge_reminder — close a due reminder the user has handled (or cancel it); frees its slot and clears the alert on every surface

Safety: By-query tools are convenient, not proof of identity. For high-impact changes, retrieve the exact memory first. If you're acting on a memory you just created earlier in the same conversation, pass its memoryId instead of re-resolving by natural-language query, since search indexing can lag a few seconds behind a fresh write and briefly return not_found for a memory that already exists.

Whole-subtree functions

Items can nest: an idea with sub-ideas, and sub-ideas under those, at any depth. Pull one out with everything under it in a single call rather than walking the graph a hop at a time.

  • get_memory_tree — one item and every item nested under it, as a readable markdown document plus the list of nodes, in the order the tree is arranged
  • depth and maxNodes bound it; when the cap bites the response says truncated: true rather than looking complete
  • Prefer this over get_memory_neighbors for a whole idea: neighbor walks cap at two hops and cannot see sibling order
  • In the terminal: empirical memory tree --memory-id <id> --out idea.md
get_memory_tree({ memoryId: "<id>", depth: 10 })

File functions

Memories can carry files, and an agent can read them back, not just see that they exist. A text file (an HTML page, markdown, JSON, code) comes back in full inside the tool result; an image comes back as an image; anything else comes back with a download link that works for ten minutes. Every file is also an MCP resource (empirical://memories/<memoryId>/attachments/<attachmentId>), so a client that supports resources/read can fetch it that way, and list_memory_attachments returns each file as a resource link. Writing goes two ways: a public URL the server fetches, or the file's text passed directly, which is how an agent saves something it wrote itself. Binary bytes cannot travel as a tool argument; those come by URL or from the CLI.

  • list_memory_attachments — list the files on a memory, with size, type and resource URI; pass includeDeleted to also see deleted files still inside the 30-day restore window and the date each one is purged
  • get_memory_attachment — read one file. Text up to 1MB is returned inline (default 512KB, raise with maxInlineBytes), images as an image, everything else as a signed download link plus the resource URI
  • attach_file_to_memory — attach a file by https URL (25MB per file, 20 files per memory), or pass its text as content with mimeType and filename (up to 1MB). URLs that resolve to private or internal addresses are refused, and redirects are re-checked at every hop. HTML and SVG are stored as plain text so they cannot execute when served
  • delete_memory_attachment — delete one file, reversible for 30 days. Requires confirm: true
  • restore_memory_attachment — put a deleted file back while it is still inside the window
  • For a file on your own machine, use the CLI: empirical memory attachment add --memory-id <id> --file <path>; to save a file locally, empirical memory attachment get --memory-id <id> --attachment-id <id> --out <path>
list_memory_attachments({ memoryId: "<id>" })
get_memory_attachment({ memoryId: "<id>", attachmentId: "<fileId>" })
attach_file_to_memory({ memoryId: "<id>", content: "<html>...</html>", mimeType: "text/html", filename: "landing-page.html" })
attach_file_to_memory({ memoryId: "<id>", url: "https://example.com/contract.pdf" })

Workspace functions

Use workspace tools to keep memory scoped to the right project or team context before reading or writing.

  • list_workspaces — list workspaces available to the authenticated client
  • get_current_workspace — inspect the active scope. For a team workspace with an active shape it also returns shape (kinds of item with their keys, statuses and fields) and policy (the rules its managers confirmed)
  • set_current_workspace — switch the active memory boundary
  • create_workspace — create a new shared workspace. It is created EMPTY, with no kinds of item; call set_workspace_shape next. It does not switch the active workspace, and it refuses with an upgrade link when the plan does not allow another one
  • set_workspace_shape — give a workspace its kinds of item, their stages and their fields, which is what turns it from a list of memories into a board. Ask the person what they track before calling it: a kind of item takes its permanent key from its singular label, and later you can ADD kinds, stages and fields but never remove one
get_current_workspace()
set_current_workspace({ workspaceKey: "project-atlas" })

// Set one up from scratch
create_workspace({ name: "Fieldnotes" })
set_workspace_shape({ workspaceId: "ws_team_...", shape: { itemTypes: [{ label: "Lead", statuses: [{ label: "New" }, { label: "Won", isDone: true }] }] } })

Utility and policy functions

Use utility tools to identify the account, inspect policy, and manage workspace scope.

  • get_empirical_policy — return the memory-use policy for the current client
  • get_user — return account and plan metadata
  • memory_usage_guide — read the memory usage policy for when to create, query, update, or delete memories
get_user()
get_empirical_policy()

Guided setup functions

Use these to run a guided interview that configures a blueprint through a short back-and-forth instead of a single install call. Locked setups require a paid plan.

  • list_guided_setups — list available guided-interview blueprint setups. Locked entries require a paid plan
  • start_guided_setup — start a guided interview. Returns the first question and a sessionId; a setup that uses Empirical Tokens first returns the cost, and the call is repeated with acceptEmpiricalTokenCost true only after the person agrees. The setup_workspace setup, when list_guided_setups shows it, interviews the person to create a shared workspace; passing reshapeWorkspaceId (an id from list_workspaces) re-shapes that workspace instead. Leaving it out always creates a new one, and the selected workspace is never the target
  • continue_guided_setup — record the answer to the current question (if any) and return the next question, or completion once every question is answered: an installId for a blueprint setup, or the confirmed workspace for the workspace setup. The workspace setup never completes on its own: show the draft and use confirm_guided_setup
  • finish_guided_setup — end a guided interview before every question is answered. Unanswered slots use their defaults. Triggers install. Not available for the workspace setup (setup_workspace), which is refused: answer the questions and confirm the draft instead
  • confirm_guided_setup — confirm a finished interview from its reviewed draft: the Writing Voice setup installs the voice, and the workspace setup creates the workspace (or saves its new shape) and emails the invitations the draft lists. Needs the draftHash shown with the draft, and the person's clear yes
start_guided_setup({ setupId: "<id>" })
start_guided_setup({ setupId: "setup_workspace", reshapeWorkspaceId: "<workspace id>" })
continue_guided_setup({ sessionId: "<id>", answer: "..." })

Blueprint catalog functions

Use these to browse, claim, install, and manage blueprints from the catalog. install_blueprint claims automatically for free blueprints, so claim_blueprint is only required for a manual, separate claim step.

  • list_blueprints — browse the blueprint catalog. Returns a compact summary per blueprint, not full detail (use get_blueprint for that). Optionally filter by category
  • get_blueprint — full detail for one blueprint: description, outcomes, compatibility, node/relationship estimates, and whether you own/have installed it
  • claim_blueprint — claim entitlement to a free blueprint. Required before installing, unless you use install_blueprint, which claims automatically for free blueprints
  • preview_blueprint_install — preview what installing a blueprint would create: node/relationship counts and duplicate-candidate count against your existing memories
  • install_blueprint — install a blueprint into your memory graph. Automatically claims first if the blueprint is free and not yet owned. Waits for the install to finish (up to ~20s) and returns the final status; a blueprint that uses Empirical Tokens first returns the cost
  • get_blueprint_install_status — poll the status of an install. Use this if install_blueprint returned jobStatus "running" (still installing past its own bounded wait)
  • list_installed_blueprints — list every blueprint currently installed for you, with node/relationship counts and whether an update is available
  • update_blueprint — update an installed blueprint to a newer version. Untouched memories from the old version are removed; anything you edited is preserved (detached from the blueprint)
  • uninstall_blueprint — uninstall a blueprint. Untouched memories are deleted; anything you edited is preserved (detached from the blueprint, not deleted)
list_blueprints({ category: "build" })
install_blueprint({ blueprintId: "<id>" })

Ownership: update_blueprint and uninstall_blueprint only affect memories that are still attached to the blueprint's own version. Anything you've edited is treated as yours and is never deleted.

Last updated: July 31, 2026