# Quickstart

Connect one client, save useful context, recall it later, and keep credentials out of public configuration.

- Canonical: https://docs.xmemo.dev/docs/quickstart
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 266253a44118fa60a2206124929a59ffe67c5889e638db5c54db03da8d1c0b85
- Edition-Digest: e67ecb7df69a56c7f8fcae496e5cf0f0e8c206dc93df920ca2e3d5b44aedcb6e
- Source-Revision: sha256:7a7b2bd41d3c5c59708cbfdeaadada3a41707c3928778dccc70da532892b4792

## 1. Choose client and auth mode

Select a supported client (Claude Desktop, Cursor, VS Code, or ChatGPT) and choose between OAuth and Direct MCP. Use OAuth whenever supported by your host client; use Direct MCP with XMEMO_KEY from your local environment only when OAuth is unavailable.

- Supported clients: Claude Desktop, Cursor, VS Code, and ChatGPT.
- Auth modes: OAuth (preferred, browser-approved) vs Direct MCP (environment variable XMEMO_KEY).
- Intermediate status: Selecting a client and copying config is an intermediate step, not activation.

## 2. Configure client without exposing tokens

Configure your client using the hosted MCP endpoint (https://xmemo.dev/mcp). For Direct MCP, reference ${XMEMO_KEY} from your local environment or secret store. Never hardcode plaintext bearer tokens into client configuration files or version control.

- OAuth clients: Configure https://xmemo.dev/mcp and approve memory:read and memory:write in the browser.
- Direct MCP: Reference ${XMEMO_KEY} in config; keep the real token in your local environment or secret store.
- Zero secrets: Configuration files must never contain unencrypted bearer tokens.

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}
```

## 3. Verify connection with read-only check

Always verify connectivity with a read-only request before writing data. A successful read confirms that your client can reach the server and that your memory:read scope is valid.

- Tool: get_mcp_identity (or recall with limit 1).
- Scope gate: memory:read.
- Success signal: Identity metadata confirms the server is reachable and authorized.

```ts
get_mcp_identity()
```

## 4. Save an explicit synthetic fact

Record a synthetic project convention to verify write capability under memory:write. Give the memory a specific path so subsequent queries can find it within the project scope.

- Tool: remember with explicit synthetic content.
- Path scope: projects/demo-onboarding/conventions.
- Success signal: Receipt begins with 'Saved to XMemo.' with assigned ID and Location.

```ts
remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})
```

## 5. Open a fresh client session

Start a new conversation thread or restart your client to clear ephemeral in-memory context. This stateless transition ensures your next recall verifies server-side persistence rather than local chat history replay.

- Action: Close or reset the current chat session in your client.
- Context reset: Ephemeral client context is cleared to guarantee stateless testing.
- Persistence verification: Subsequent recall queries the remote store directly.

## 6. Recall fact with source attribution

Query the stored convention from the fresh session. Activation is strictly defined as completing the first verified memory recall with source attribution—copying configuration or inspecting snippets is only an intermediate setup step.

- Tool: recall with query 'demo project timestamp format'.
- Receipt format: Textual output beginning with '### XMemo Memory Results:' showing Reference, Location, optional Created/Updated/Revision, and content.
- Success signal: First verified recall with source attribution marks true activation.

```ts
recall({
  query: "demo project timestamp format",
  limit: 1
})
```

## 7. Correct convention with update_memory

When project conventions evolve or require clarification, use update_memory with the exact memory_id returned from recall. This supersedes the previous revision while preserving an immutable history.

- Tool: update_memory with valid memory_id.
- Revision trail: Supersedes previous revision while preserving immutable history.
- Success signal: Receipt begins with 'XMemo memory updated.' showing Reference and Revision.

```ts
update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})
```

## Recovery: Clipboard access denied

If your browser denies clipboard access or permissions are blocked, manually select the snippet text inside the code block and copy with Ctrl+C (or Cmd+C). All code blocks provide tabIndex=0 for keyboard scrolling and selection.

- Symptom: Browser blocks automatic clipboard copy or permissions prompt fails.
- Action: Click or tab into the code container and use Ctrl+C or Cmd+C.
- Verification: Pasted configuration matches the displayed snippet exactly.

## Recovery: Expired or insufficient auth

If your client receives HTTP 401 Unauthorized, HTTP 403 Forbidden, or SetupRequiredMCPError, your authentication token has expired or lacks required scopes.

- Symptom: HTTP 401, HTTP 403, or SetupRequiredMCPError on tool invocation.
- Action: Re-authenticate via OAuth, or set XMEMO_KEY in your local environment.
- Verification: Confirm token grants both memory:read and memory:write scopes.

## Recovery: Tools not visible in client

If XMemo tools do not appear in your client palette after configuration, the configuration file may contain syntax errors or the MCP connection process may need a restart.

- Symptom: Client shows 0 tools or fails to recognize the XMemo MCP server.
- Action: Check client developer logs, validate JSON syntax, and restart client.
- Verification: Client logs show successful MCP initialization and tool discovery.

## Recovery: Empty recall results

If recall returns no matching memories ('No matching memories found' or 'No strong memory match'), verify that the write in Step 4 completed successfully and check your search query.

- Symptom: recall returns text message indicating no matching memories were found.
- Action: Check query keywords ('timestamp', 'UTC') and verify path scope.
- Verification: Confirm remember returned receipt starting with 'Saved to XMemo' before recalling.

## Recovery: Unknown memory ID on update

If update_memory rejects your call because memory_id is unknown or invalid, do not guess identifiers.

- Symptom: update_memory returns error indicating memory_id not found.
- Action: Call recall first to retrieve the active memory Reference and pass it as memory_id.
- Verification: Pass the active memory Reference from recall into update_memory.

## Hosted XMemo quickstart

Start with the managed XMemo service and one of these connection paths. Self-hosted, Docker, Supabase, and Python package setup are developer references, not the first path for hosted users.

### OAuth clients

Use this path for ChatGPT, OpenAI app review, VS Code, and GitHub Copilot when the host supports OAuth. Add the hosted MCP URL, approve memory:read and memory:write, and do not paste XMEMO_KEY into the client config.

```
MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write
```

### @xmemo/client setup

Use the public CLI to discover the hosted service, review the generated MCP profile, and copy only client-safe configuration into your local tool.

```
npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev
```

### Direct MCP with XMEMO_KEY

Use this path only for clients or headless runners that cannot complete OAuth. Store XMEMO_KEY in the local environment or secret store, keep the hosted MCP URL in config, and never paste the real token into public docs or chat.

```
MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID
```

### Account controls

After the first connection, use the account entry to review what was saved, check agent attribution, and find delete/export or support paths before expanding a pilot.

```
Account entry: https://xmemo.dev/login
```