UniloomDocs
Reference

Connecting your agents

Any agent that speaks MCP can connect to Uniloom and share its memory. What it can then do is in the tool reference.

From Connect#

Open Connect → Agents, pick the agent and its account, and switch Uniloom on. Uniloom adds itself to that account's setup, so it holds for every project. Toolkit can also write MCP setups for every agent.

The entry starts uniloom-mcp, a program inside the app. It opens your workspace itself, so the agent has Uniloom's tools whether or not the Uniloom window is open. The entry holds no key.

Three tools need the Uniloom app open: connected_tools and read_connected (Uniloom holds those integrations' sign-ins) and run_automation. With Uniloom closed they answer uniloom_not_running. Every other tool works.

Sessions Uniloom starts itself, from Sessions or Tasks, reach the running app over a port on this computer instead: 47366 for the first user account on the Mac, then 47367 and up. If another program holds that port when Uniloom starts, a red line at the top of the window names the port. Run lsof -i :<port> to find the program, quit it, and restart Uniloom.

One click in VS Code or Cursor#

Install Uniloom first. These links only add an entry that runs the app's uniloom-mcp, so they do nothing without the app.

Install in VS Code · Install in Cursor

By hand#

Connect is the supported way. To write the entry yourself, run the program inside the app, with no arguments. For Claude Code, in ~/.claude.json:

{
  "mcpServers": {
    "uniloom": {
      "type": "stdio",
      "command": "/Applications/Uniloom.app/Contents/MacOS/uniloom-mcp",
      "args": []
    }
  }
}

Other agents spell it their own way: OpenCode {type: "local", command: [path]}, Codex command and args under [mcp_servers.uniloom]. Claude Desktop, VS Code and other clients take the same command.

A client started with no folder, such as Claude Desktop's chat, is asked to call recall with the conversation's topic, naming the project if there is one, instead of with a working folder.

Check that it works#

Ask your agent:

"Use the uniloom_capabilities tool to check the Uniloom contract, then use recall with query 'test' to check if Uniloom is connected."

An answer that mentions your workspace means it works. Empty results are fine.

The contract#

Each tool, whether it reads or writes, and where a write lands:

<!-- uniloom-contract:start -->

ToolAccessWrite target
uniloom_capabilitiesread—
create_docwrite—
get_docread—
append_to_docwriteid, target.kind:branch, target.kind:knowledge_doc; ambiguity=refuse
rememberwrite—
recallread—
get_memoryread—
log_mission_progresswrite—
list_memoriesread—
propose_memory_changewrite—
get_artifactread—
publish_artifactwrite—
get_widgetread—
publish_widgetwrite—
activityread—
handoffwrite—
live_sessionsread—
propose_setup_changewrite—
get_agent_runread—
report_agent_run_stepwrite—
start_agent_runwrite—
wait_for_runsread—
run_automationwrite—
my_tasksread—
update_my_taskwrite—
connected_toolsread—
read_connectedread—

<!-- uniloom-contract:end -->

A tool can save a typed doc and add to a doc. Saving a doc of a type the branch already has rewrites that doc. Every tool carries the standard MCP labels, so a client can skip asking before a read. See Tool rules.

A refused remember is not an error: the answer says saved: false, with the reason. Memory lands in the workspace that holds the call's working folder: Personal, unless a shared workspace holds it.

Error codes#

A failed call answers with error.code and error.message:

CodeWhen
invalid_argumentsAn argument the tool's schema refuses, such as a missing id or a wrong type
unknown_toolA tool name Uniloom does not have
approval_requiredcreate_doc without user_approved: true
content_requiredcreate_doc for a typed doc with no markdown
target_not_found, target_archived, ambiguous_targetA doc target that does not resolve to exactly one live doc
invalid_request, not_foundA bad update_my_task call, or an item that is not there
proposal_refusedA propose_memory_change the project's memories cannot take
not_a_project, invalid_proposal, already_offeredA refused propose_setup_change
artifact_not_found, invalid_artifact, is_a_widgetThe artifact tools
widget_not_found, invalid_widget, build_failed, not_a_widget, version_conflictThe widget tools. version_conflict: someone published a newer version meanwhile; publish again
wrong_workspaceThe working folder belongs to another workspace than the session's (Tool rules)
no_agent_runget_agent_run outside an agent run
stale, closed, invalidA refused report_agent_run_step
uniloom_not_runningA tool that needs the app, while Uniloom is closed
run_not_startableA run_automation id that names no automation, or one with no steps
store_unavailableThe workspace needs an update that only the Uniloom app makes. Open Uniloom once
internal_errorAnything else, with its message

If it does not work#

  • "command not found" or "no such file": Uniloom is not in /Applications. Install it as in Install and first ten minutes.
  • The tools appear but calls fail: open the Uniloom app once, so it creates your workspace.

Last updated