Muse Code

Prerequisite

Use a Muse Code install that reads MCP servers from ~/.config/muse/settings.json. Muse Code connects to XMemo as an OAuth client, so the config file holds no token.

• Endpoint: https://xmemo.dev/mcp.
• Auth mode: OAuth (browser PKCE) with dynamic client registration.
• Config file: ~/.config/muse/settings.json. It must contain "schema_version": 1.
• Granted scopes: memory:read, memory:write, knowledge:read and knowledge:write.
• Automated setup: xmemo setup muse-code is coming soon with the next XMemo CLI release. Until then, use the manual config below.

Add XMemo to settings.json

Edit ~/.config/muse/settings.json from a terminal outside Muse; Muse's sandbox rejects edits to this file made inside a Muse session. Add an xmemo entry under the top-level camelCase mcpServers key. No token or Authorization header belongs in this file.

{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}

Keep only mcpServers

Muse's public web docs still show a snake_case mcp_servers key, which is stale. If settings.json contains both mcpServers and mcp_servers, Muse drops every MCP server. Rename an existing mcp_servers block to mcpServers and merge its entries into it, so the file keeps only mcpServers.

Sign in with OAuth

Run the login command for the xmemo server and approve access in the browser. On a machine without a browser UI, add --headless.

muse mcp login xmemo
# Without a browser UI:
muse mcp login xmemo --headless

Restart the client

Restart Muse after signing in so it loads the xmemo server with the new OAuth grant.

Verify the XMemo tools

Ask Muse to list the XMemo tools without calling any of them.

muse exec "List the names of the tools you have from the xmemo MCP server. Do not call any tools."

Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

recall({ query: "connection check", limit: 1 })

Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

XMemo Skill

Muse scans ~/.agents/skills, ~/.claude/skills and ~/.codex/skills, so an XMemo Skill already installed for Claude Code or Codex works in Muse without changes.

Common Errors

Muse Code connects through OAuth; most errors come from the config key, the sign-in step or the sandbox.

• No xmemo tools are listed: settings.json contains both mcpServers and mcp_servers, so Muse dropped every MCP server. Keep only mcpServers.
• invalid_grant: the authorization is invalid, expired or already used, or the selected connection is no longer valid. Run muse mcp login xmemo again, then restart Muse.
• 403 insufficient_scope: the approved scopes do not cover the call. Sign in again and approve the memory and knowledge scopes.
• Edits to settings.json are rejected: the change was made inside a Muse session. Edit the file from an outside terminal.