# xmark

chat with your X (Twitter) bookmarks. xmark pulls your saved tweets, embeds them with OpenAI, and answers questions in plain english using Claude — with citations linking back to the original tweet.

website: https://www.xmark.dev
api: https://api.xmark.dev
docs: https://www.xmark.dev/docs
llms-full.txt: https://api.xmark.dev/llms-full.txt
openapi: https://api.xmark.dev/openapi.json
status: https://www.xmark.dev/api/health
help: https://www.xmark.dev/help

## what xmark is

- a personal search-and-chat layer over a user's X (Twitter) bookmarks
- semantic retrieval (pgvector + OpenAI embeddings) over the full bookmark contents
- Claude (claude-sonnet) answers grounded in the user's bookmarks with [N] citations
- developer REST API at api.xmark.dev with scoped API keys + webhooks
- MCP server (@jclvsh/xmark) so AI clients like Claude Code can query your bookmarks

## what xmark is not

- not a bookmark manager (read-only mirror of X bookmarks; remove unbookmarks on X too)
- not an X analytics dashboard (no engagement insights or follower metrics)
- not a public search engine (each user's bookmarks are private — RLS-gated per user)
- not a tweet archiver — bookmarks-only, no general timeline ingest

## quick start

1. sign in with Google at /auth/signup
2. connect your X account on /bookmarks (separate OAuth flow for bookmark read access)
3. click sync — xmark pulls and embeds your bookmarks
4. open /chat and ask questions in plain english

## developer + AI client access

create a scoped API key at /settings/api, then:

- CLI: `npx -y -p @jclvsh/xmark xmark search "..."`
- MCP server (Claude Code / Cursor / Claude Desktop): `npx -y -p @jclvsh/xmark xmark-mcp`
- REST: https://api.xmark.dev/bookmarks, /chat, /bookmarks/search, /bookmarks/sync, /conversations, /conversations/{id}/messages, /usage

set `XMARK_API_KEY` in your env before running.

## pricing

free tier: 20 chats/month, 1 sync/day. pro: $5/month — unlimited chat + sync.
CLI + MCP + REST API all included.

## tech stack

- Next.js 16 + React 19 + Supabase Postgres (with pgvector)
- Twitter (X) OAuth 2.0 with PKCE for bookmark read access
- OpenAI text-embedding-3-small for semantic search (1536 dims)
- Anthropic claude-sonnet for chat answers
- Stripe for billing

## see also

- https://api.xmark.dev/llms-full.txt — full API reference
- https://api.xmark.dev/openapi.json — OpenAPI 3.1 spec
- https://www.xmark.dev/docs — REST API reference
- https://www.xmark.dev/help — FAQ
- https://www.xmark.dev/compare — vs Pocket, Readwise, Glasp, native X