Skip to main content
Install the xysq plugin to give Claude Code persistent memory across every session. The plugin configures the MCP connection and teaches Claude how to use xysq tools automatically.

​
Before You Start

Sign in to your xysq account at app.xysq.ai.

​
Step 1 - Add the xysq Marketplace

In any Claude Code session, run: 
/plugin marketplace add xysq-ai/xysq-claude-plugin
This adds the xysq plugin registry to Claude Code.

​
Step 2 - Install the Plugin

/plugin install xysq
If Claude Code doesn’t pick it up automatically, run /reload-plugins.

​
Step 3 - Sign in via OAuth

Open the MCP panel: 
/mcp
You’ll see xysq listed. Select it and approve the OAuth flow — Claude Code opens your browser, signs you in to xysq, and stores the session in your system keychain. You only do this once. Future sessions reuse the stored session automatically. No API key to paste, no config to edit. Every MCP call is authorised as you, the signed-in user, with the same identity you use in the web UI — which is what makes team memory seamless (see Working with teams below).

​
Step 4 - Verify

Start a new Claude Code session and try: 
Remember that I prefer dark mode in all my tools.
Claude should call memory_retain and confirm the memory was stored.

​
Working with teams

OAuth ties the MCP session to your xysq user, so teams are configured in one place — your web UI — and Claude Code picks them up automatically.
  1. Open app.xysq.ai/teams.
  2. On any team card, flip the MCP sync toggle on.
  3. Your next MCP tool call in Claude Code will fan-write to that team’s vault alongside your personal vault, and recall from both.
No restart, no config edit, no team ID to paste. Flip the toggle off when you want to stop syncing. See Teams via MCP for the full mental model — including per-call narrowing (team_id=..., personal_only=true) and the 10-team cap.

​
What Gets Installed

ComponentPurpose
MCP connectionOAuth-authorised connection to api.xysq.ai/mcp as your xysq user
Memory skillTeaches Claude the session protocol, tool usage, consent rules
The skill activates at the start of every session — Claude will pull your context from memory automatically.

​
Alternative: API key (server-to-server, CI, headless)

If you’re configuring Claude Code for a non-interactive context (a CI runner, an automation script, a shared workstation where browser-based OAuth isn’t practical), use an API key instead:
  1. At app.xysq.ai, click Connect Agent → Claude Code tab → Generate API Key. Save the xysq_... key — it’s shown once.
  2. Wire the MCP connection by hand:
claude mcp add xysq https://api.xysq.ai/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY"
  1. To include team vaults on an API-key session, add the X-Xysq-Teams header with a comma-separated list of team UUIDs:
claude mcp add xysq https://api.xysq.ai/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Xysq-Teams: TEAM_UUID_1,TEAM_UUID_2"
The UI MCP sync toggle only applies to OAuth sessions — API-key sessions declare scope per request via the header. This path does not install the memory skill; use the plugin if you want it.

​
Troubleshooting

ProblemFix
Plugin install failsMake sure Claude Code is up to date — run claude update (or reinstall from claude.com/code) and restart your session. Then retry /plugin install xysq. If it persists, use the API-key alternative above.
Browser doesn’t open for OAuthSome terminal environments don’t have a default browser handler. Copy the URL Claude Code prints into your browser manually, complete the login, return to the terminal. If you can’t open a browser at all, use the API-key alternative.
MCP not connecting after installRun /reload-plugins or start a new session. Check /plugin list to verify xysq is listed.
”Authentication required” errorYour OAuth session may have expired. Disconnect via /plugin disable xysq then /plugin enable xysq to re-run OAuth. For API-key installs, regenerate at app.xysq.ai/connect and reinstall.
Skills not loadingVerify with /plugin list that xysq shows as installed and enabled. Try /plugin disable xysq then /plugin enable xysq.
Team memories not appearingCheck that MCP sync is toggled on for that team at app.xysq.ai/teams. The toggle takes effect on the next MCP call — no reconnect needed.
Want to update the pluginRun /plugin update xysq to pull the latest version.