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 -->
| Tool | Access | Write target |
|---|---|---|
uniloom_capabilities | read | — |
create_doc | write | — |
get_doc | read | — |
append_to_doc | write | id, target.kind:branch, target.kind:knowledge_doc; ambiguity=refuse |
remember | write | — |
recall | read | — |
get_memory | read | — |
log_mission_progress | write | — |
list_memories | read | — |
propose_memory_change | write | — |
get_artifact | read | — |
publish_artifact | write | — |
get_widget | read | — |
publish_widget | write | — |
activity | read | — |
handoff | write | — |
live_sessions | read | — |
propose_setup_change | write | — |
get_agent_run | read | — |
report_agent_run_step | write | — |
start_agent_run | write | — |
wait_for_runs | read | — |
run_automation | write | — |
my_tasks | read | — |
update_my_task | write | — |
connected_tools | read | — |
read_connected | read | — |
<!-- 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:
| Code | When |
|---|---|
invalid_arguments | An argument the tool's schema refuses, such as a missing id or a wrong type |
unknown_tool | A tool name Uniloom does not have |
approval_required | create_doc without user_approved: true |
content_required | create_doc for a typed doc with no markdown |
target_not_found, target_archived, ambiguous_target | A doc target that does not resolve to exactly one live doc |
invalid_request, not_found | A bad update_my_task call, or an item that is not there |
proposal_refused | A propose_memory_change the project's memories cannot take |
not_a_project, invalid_proposal, already_offered | A refused propose_setup_change |
artifact_not_found, invalid_artifact, is_a_widget | The artifact tools |
widget_not_found, invalid_widget, build_failed, not_a_widget, version_conflict | The widget tools. version_conflict: someone published a newer version meanwhile; publish again |
wrong_workspace | The working folder belongs to another workspace than the session's (Tool rules) |
no_agent_run | get_agent_run outside an agent run |
stale, closed, invalid | A refused report_agent_run_step |
uniloom_not_running | A tool that needs the app, while Uniloom is closed |
run_not_startable | A run_automation id that names no automation, or one with no steps |
store_unavailable | The workspace needs an update that only the Uniloom app makes. Open Uniloom once |
internal_error | Anything 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