Honcho setup

Honcho connects as an MCP server over HTTP with OAuth. There is no API key to paste and no local process to start. Setup is: sign in, pick where memory lives, record that choice in Honcho so every tool and Bot on the account finds it.

Step 1: Sign in

• Cursor: open Customize, find the Honcho MCP server, and choose Authenticate (or Reconnect). A browser window completes the sign-in.
• Grok Bot: tell the user "I need to sign in to Honcho" and follow the connect card the Bot shows. Ask the user to complete it in their browser.

Verify by calling list_workspaces. An authentication error means the sign-in did not complete; do not retry other tools until it does.

Step 2: Choose a workspace

Memory is scoped to a workspace. Ask the user one question:

Keep Cursor's memory on its own, or share it with another Honcho tool?

First make sure the cursor workspace exists: call create_workspace with workspace_id: "cursor". It is get-or-create, so this is safe on every run.

set_metadata replaces a resource's whole metadata object. Every write below is therefore read, merge, write: call get_metadata, change only the key in question, and send the full object back. Never send a single key on its own.

• On its own: use the workspace cursor. If the cursor workspace's metadata has a default_workspace key from an earlier choice, remove that key and write the rest back, or honcho-memory will keep using the old shared workspace.
• Shared: show the user the result of list_workspaces and let them pick the workspace their other tool uses (for Claude Code the default is claude_code). Then store the pointer so future conversations find it: merge {"default_workspace": "<chosen>"} into the cursor workspace's metadata.

Step 3: Choose the user's peer

Call get_metadata on the chosen workspace. If it already has user_peer, confirm it with the user and stop. Otherwise ask what Honcho should call them (a short handle, no spaces; in a shared workspace it must match the peer their other tool uses), then merge {"user_peer": "<handle>"} into that workspace's existing metadata and write it back.

Step 4 (Cursor only): Line up automatic capture

In Cursor the plugin also ships hooks that record every turn automatically. They need ~/.honcho/config.json, the file honcho init and the other Honcho plugins write, with an API key in it. Check whether it exists:

• It exists: make sure peerName matches the handle from Step 3 and that hosts.cursor.workspace matches the workspace from Step 2, editing the file if needed. Otherwise the hooks and the skills write to different places.
• It does not exist: tell the user that memory works now through the MCP tools, and that running honcho init turns on automatic capture so they never depend on the agent remembering to record. Do not ask for an API key in chat.

Grok Bot never runs hooks, so skip this step there.

Step 5: Confirm

Report, in a few lines:

• the workspace in use, and whether it is shared;
• the user peer, and your own peer (cursor, or your Bot name);
• what get_peer_context returns for the user peer right now (a sentence or "nothing yet, memory starts with this conversation").

Then record this conversation as the first entry, following the honcho-memory skill.

Status check

When asked for Honcho's status, run Step 5 without changing anything, and add how many sessions search finds for the current session name. If the workspace metadata has no user_peer, say setup is incomplete and offer to finish it.