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
  • 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
  • delete_memory_by_query — find a memory and delete only with confirm=true

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.

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
  • set_current_workspace — switch the active memory boundary
get_current_workspace()
set_current_workspace({ workspaceKey: "project-atlas" })

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 for a blueprint. Returns the first question and a sessionId
  • continue_guided_setup — record the answer to the current question (if any) and return the next question, or completion with an installId once every question is answered
  • finish_guided_setup — end a guided interview before every question is answered. Unanswered slots use their defaults. Triggers install
start_guided_setup({ setupId: "<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
  • 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