@popoastier/socialmemory-mcp

Local MCP connector for socialmemory.

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

It lets local agents such as Codex and Claude Code:

• 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: @popoastier/socialmemory-mcp
• public repo: https://github.com/popoastier/socialmemory-mcp
• release path: GitHub workflow in .github/workflows/publish.yml

Before releasing, verify:

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

The package name must stay @popoastier/socialmemory-mcp, and the package repository must stay https://github.com/popoastier/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:

npx -y --package @popoastier/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:

npx -y --package @popoastier/socialmemory-mcp socialmemory status
npx -y --package @popoastier/socialmemory-mcp socialmemory doctor

Remove the locally stored credential:

npx -y --package @popoastier/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 in:

Settings -> Agent access -> Connect Codex

Run the generated setup command:

npx -y --package @popoastier/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.

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:

npx -y --package @popoastier/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:

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

Restart Codex after adding the connector, then ask:

check my socialmemory status

Claude Code Setup

The socialmemory web app generates the full command in:

Settings -> Agent access -> Connect Claude Code

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

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

The advanced env-token fallback still works:

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

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

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

Remove the locally stored credential. If SOCIALMEMORY_AGENT_TOKEN is still set in the shell, commands will keep using that env token.

socialmemory status

Show the current credential source and archive/sync status.

socialmemory doctor

Check Node.js, credential storage, credential presence, server access, and whether the selected local browser profile is signed into X.

socialmemory setup codex

Install socialmemory in Codex, choose the local X account/profile to use for sync, run browser login, verify setup with doctor, run a full first sync if the archive is empty or has never synced, and print archive status.

socialmemory sync

Run local X sync from this machine. Options:

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

Search saved X likes and bookmarks. Supports keyword, meaning, and hybrid modes.

Search responses include a ready-to-use linked answer. When an agent mentions saved X posts from search, it should preserve each direct X post URL and include the socialmemory result-set link when one is returned.

sync_x_memory

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

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.

add_saved_x_note

Append a note to one saved post.

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.

Sync records include safe source metadata such as browser label, profile label, profile hash, active X handle, and X user id. Raw cookies and local browser paths are not 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. Use keyword search first.