# @socialmemory/mcp

Use saved X likes and bookmarks from socialmemory inside Codex, Claude Code, and Cursor.

This package covers the Agent Access path for Codex, Claude Code, and Cursor. The web app and Chrome extension are separate product surfaces that use the same socialmemory archive.

It lets local agents such as Codex, Claude Code, and Cursor:

- search a user's saved X likes and bookmarks
- refresh saved X likes and bookmarks from the local browser session
- read one saved post
- append notes to saved posts
- merge tags into saved posts
- create a socialmemory web link that opens exactly the posts returned by the agent
- check archive and sync status

## Release Guard

Official package identity:

- npm package: `@socialmemory/mcp`
- public repo: `https://github.com/kennyberg/socialmemory-mcp`
- release path: GitHub workflow in `.github/workflows/publish.yml`

Before releasing, verify:

```bash
npm run release:guard
npm test
npm run check
npm run pack:dry-run
```

The package name must stay `@socialmemory/mcp`, and the package repository must stay `https://github.com/kennyberg/socialmemory-mcp`. Do not publish if the package name, repository URL, or release guard result is unexpected.

## Requirements

- Node.js 20 or newer
- A socialmemory account
- An active socialmemory Personal plan or trial
- Chrome, Chromium, Brave, or Edge on macOS for local X sync in this first version
- The user must be signed into X in that local browser profile before running sync

## CLI Login

The package now includes two binaries:

- `socialmemory` is the user-facing CLI.
- `socialmemory-mcp` is the MCP server that Codex and Claude Code run.

Run:

```bash
npx -y --package @socialmemory/mcp socialmemory login
```

This starts a short login session, opens socialmemory in the browser, shows a code, and waits while the user approves the local agent. After approval, the CLI stores the credential locally without printing the token.

On macOS, the CLI stores the credential in Keychain using the `security` command. If Keychain is unavailable, it falls back to `~/.config/socialmemory/credentials.json` with file mode `0600`.

Check the local setup:

```bash
npx -y --package @socialmemory/mcp socialmemory status
npx -y --package @socialmemory/mcp socialmemory doctor
```

Revoke this credential on the socialmemory server and remove the local copy:

```bash
npx -y --package @socialmemory/mcp socialmemory logout
```

`SOCIALMEMORY_AGENT_TOKEN` is still supported as an advanced fallback. It takes priority over the stored local credential.

## Codex Setup

The socialmemory web app generates the full command on the `Agent Access` page under `Set up Codex`.

Run the generated setup command:

```bash
npx -y --package @socialmemory/mcp@latest socialmemory setup codex --base-url https://socialmemory.dev
```

That one command installs socialmemory in Codex, checks supported local Chrome, Chromium, Brave, and Edge profiles for a signed-in X session, asks which profile to use when needed, opens the browser login, saves the approved credential locally, starts a full first sync when the archive is empty or has never synced, and prints the current archive status. A safely running or paused first sync can leave the library empty for a while without making installation fail. The command calls the import complete only after Sync v2 reports `all_sources_complete`.

If setup finds one usable X account/profile, it saves that local choice for future syncs. If it finds more than one, it asks which browser profile to use and shows each browser, profile name, Google account, and choice id. It only shows the X account when socialmemory can read it safely. In a noninteractive shell, such as CI, setup exits with exact commands you can rerun, for example:

```bash
npx -y --package @socialmemory/mcp@latest socialmemory setup codex --base-url https://socialmemory.dev --session-id chrome-profile-default
```

The advanced env-token fallback still works when browser login is unavailable:

```bash
codex mcp add socialmemory \
  --env SOCIALMEMORY_BASE_URL=https://socialmemory.dev \
  --env SOCIALMEMORY_AGENT_TOKEN=YOUR_TOKEN \
  -- npx -y --package @socialmemory/mcp@latest socialmemory-mcp
```

Restart Codex after adding the connector, then ask:

```text
check my socialmemory status
```

## Claude Code Setup

The socialmemory web app generates the full command on the `Agent Access` page under `Set up Claude Code`.

If you have run `socialmemory login`, the command can use the locally stored credential:

```bash
claude mcp add --transport stdio \
  --scope user \
  socialmemory \
  -- npx -y --package @socialmemory/mcp@latest socialmemory-mcp
```

The advanced env-token fallback still works:

```bash
claude mcp add --transport stdio \
  --env SOCIALMEMORY_BASE_URL=https://socialmemory.dev \
  --env SOCIALMEMORY_AGENT_TOKEN=YOUR_TOKEN \
  --scope user \
  socialmemory \
  -- npx -y --package @socialmemory/mcp socialmemory-mcp
```

Restart Claude Code or run `/mcp` after adding the connector.

## Cursor Setup

The socialmemory web app generates the full command on the `Agent Access` page under `Set up Cursor`.

Run the generated setup command:

```bash
npx -y --package @socialmemory/mcp@0.4.0 socialmemory setup cursor --base-url https://socialmemory.dev
```

The command safely merges the `socialmemory` entry into Cursor's official global configuration at `~/.cursor/mcp.json`. It preserves unrelated Cursor MCP entries and other top-level configuration, opens the normal browser-approved socialmemory login with the client name `Cursor`, and finishes with `doctor` and `status` checks. Rerunning the command keeps the same configuration instead of creating duplicates.

## Environment Variables

`SOCIALMEMORY_AGENT_TOKEN` is optional. It is an advanced fallback and takes priority over the local stored credential.

`SOCIALMEMORY_BASE_URL` is optional. It defaults to `https://socialmemory.dev`.

Never paste the token into chat messages. Store it with the CLI, or use it only in the MCP setup command or MCP config.

## CLI Commands

`socialmemory login`

Open the browser-based authorization flow and store the credential locally after approval.

`socialmemory login --token-stdin`

Read one generated agent token from stdin and store it locally. The token is not printed.

`socialmemory logout`

Revoke the active credential on the socialmemory server, then remove its local copy. Use `socialmemory logout --local-only` only when the server cannot be reached and you intentionally accept that the server credential remains active. If `SOCIALMEMORY_AGENT_TOKEN` is active, logout revokes that environment credential but cannot unset the shell variable and does not delete a separate Keychain/file credential hidden behind it. Unset the variable, then run logout again to revoke and remove that stored credential.

`socialmemory status`

Show the current credential source and archive/sync status.

`socialmemory doctor`

Check Node.js, credential storage, credential presence, server capabilities, and whether the selected local browser profile is signed into X. A progressively rolled-out feature is reported honestly without blocking other staging checks. Release validation must use `socialmemory doctor --require-release-capabilities`, which fails if any capability promised by the current MCP release is unavailable.

`socialmemory setup codex`

Install socialmemory in Codex, choose the local X account/profile to use for sync, run browser login, verify setup with `doctor`, and start or continue a full first sync. If saved posts are already usable, setup succeeds while clearly reporting that the import is still incomplete. Only a v2 run with every required source finished is called complete.

`socialmemory setup cursor`

Add socialmemory to Cursor's global MCP configuration without changing unrelated entries, run browser-approved login with the Cursor client name, and verify the connection with `doctor` and `status`.

`socialmemory sync`

Run local X sync from this machine. Options:

```bash
socialmemory sync --mode recent
socialmemory sync --mode full --force
socialmemory sync --browser brave
socialmemory sync --x-handle alex
socialmemory sync --session-id chrome-profile-default
```

When no `--browser` flag is passed, sync scans supported local browser profiles and tries to detect the active X handle in each readable profile. If setup saved an account/profile choice, sync uses that choice unless you pass `--x-handle` or `--session-id`. If there is no saved choice and multiple active X handles or browser profiles are detected, sync stops and asks you to run again with `--x-handle` when handles are available or `--session-id` when only profile labels are available.

## Tools

`search_saved_x`

Retrieve broad candidate posts from saved X likes and bookmarks. Pass the user's original request as `intent`, add optional concise `probes`, and add one optional `meaningQuery` when conceptual retrieval is useful.

Search responses contain unverified candidates and transparent retrieval evidence, not a prewritten answer. The calling agent reads the candidates and decides which are direct matches, related material, or irrelevant.

`list_saved_x`

Enumerate exact pages from the saved-X archive by liked/bookmarked state, post-publication date, author, X bookmark folder, tag, content type, favorite state, or note state. Follow `nextCursor` without changing the filters until `queryExhausted` is true before claiming an exhaustive result.

X does not provide the time when the user pressed Like or Bookmark. Date filters use the time the X post itself was published, and every response states that limitation explicitly. Import time, sync time, and database save time are never presented as Like or Bookmark action time.

`sync_x_memory`

Refresh saved X likes, bookmarks, and X bookmark-folder memberships from a detected local browser session. The default mode is `recent`. Full sync is available only when explicitly requested.

One MCP tool call processes a bounded slice so an interrupted agent process cannot lose its place. A large archive may return `in_progress`; call the tool again with the same browser selection to resume the server checkpoint. Only `success` means every required X source reached a verified completion boundary. Rate limits, safety pauses, and partial folder failures are reported explicitly and are never presented as success.

The tool scans supported local browser profiles and syncs one readable X session at a time. If setup saved an account/profile choice, the tool uses that choice. If multiple active X handles are detected and no saved or explicit choice exists, the tool returns a `needs_selection` response with the detected handles; run it again with `xHandle` to choose one. If handles are unavailable but multiple readable browser profiles are found, run it again with the chosen `sessionId`. It does not select inactive accounts inside X's account switcher. To sync a different account inside the same browser profile, switch to that account in X first, then run sync again.

`get_saved_x_post`

Read one saved post by id.

`read_saved_x_posts`

Batch-read the complete safe stored context for up to 20 candidate posts before judging relevance. The response reports requested, returned, and missing counts so an agent cannot honestly claim to have read more posts than it received.

`add_saved_x_note`

Append a note to one saved post.

`save_x_to_socialmemory`

Save one supported X post or X Article only after the user explicitly asks. The tool accepts one URL plus an optional user-authored note and tags. Socialmemory validates the URL and retrieves authoritative X content through its shared Manual Add engine; the agent never submits post text, author, media, or provider payloads. Failures use the MCP error signal and must not be reported as success.

`merge_saved_x_tags`

Add tags to one saved post without removing existing tags.

`create_socialmemory_result_set`

Create a web link that opens exactly the selected saved posts in the socialmemory app.

`get_socialmemory_status`

Show archive counts, latest saved item time, latest sync time, and latest sync status.

## Privacy Model

The sync runs on the user's own machine. It reads the local browser session so it can see the user's own X likes and bookmarks, then uploads normalized saved-post data to the user's private socialmemory cloud archive.

The selected browser profile and X account stay local. Socialmemory uploads normalized saved-post data and non-sensitive run/version counters, but it does not attach the originating browser profile, X handle, X user id, or local run metadata to each saved post. Raw cookies and local browser paths are never uploaded.

The MCP connector does not print the private token in tool responses or logs.

## Troubleshooting

If sync says it cannot find the local X session:

1. Open Chrome, Chromium, Brave, or Edge on the same Mac.
2. Sign into X.
3. Open the X bookmarks page once.
4. Run `sync_x_memory` again.

If sync reports multiple active X handles:

1. Pick the handle you want to import.
2. Run `sync_x_memory` again with `xHandle`, or run `socialmemory sync --x-handle HANDLE`.
3. Sync other X handles one at a time.

If search works but sync is skipped:

The socialmemory server is protecting the account from repeated refreshes. Wait until the cooldown time shown in the response, then try again.

If meaning search fails:

The socialmemory server may not have Meaning search configured or ready. Continue with the word-retrieved candidates and explain the reduced coverage when it affects the answer.