Keepsake

Your X saves, available to your agents.

Keepsake keeps a local, searchable library of the posts you like and bookmark on X. A Chrome extension captures each save, a Node service stores it in SQLite and Markdown on your machine, and Jev classifies each save and ranks your library against natural-language questions. You browse it in a local web library; your agents reach it through a CLI and an MCP server.

Keepsake is not affiliated with X. It runs on macOS; the core should work on Linux but is untested there. Node 24 or newer is required.

Quick start

npm ci
npm run build
npm run demo
npm start

Open http://127.0.0.1:47821. npm run demo adds 12 clearly labeled example resources so the library is not empty; they are not an import of your X account.

Related MCP server: code-rag-mcp

Turn on Jev

Jev gives each save a resource type, topics and a Work or Personal label, and powers natural-language search (--semantic, --deep, and Ask Jev in the library). Get an API key from TypeSafe and put it in a .env file in the repo root:

TYPESAFE_API_KEY=your-key

Restart the service. To keep the key elsewhere, copy config.example.json to config.json and point envFile at that file. Keepsake reads only this one variable and never copies the key into the extension, browser or logs.

Spend is capped at $20 per data directory, cumulative, not a monthly reset. A persistent ledger reserves the maximum documented request cost before each call and settles on the reported input tokens; judgments are cached by exact request.

Captured post text and fetched page excerpts are sent to TypeSafe for classification and semantic queries. Images, video, screenshots and browsing history are not. Without a key, capture, the library, keyword search, the CLI and MCP all still work; saves are left unclassified and semantic search falls back to keyword search.

Capture from X

1. Open chrome://extensions, enable Developer mode, and choose Load unpacked.

2. Select the extension/ folder in this repo.

3. In the library, choose Connect Chrome & agents, then copy the pairing token into the extension popup. Chrome keeps it for future sessions; use the popup’s settings gear to replace it or detach this browser.

4. Reload any open X tabs. Like or bookmark a post. It should reach the library in seconds.

5. For older saves, open X Bookmarks, then choose Import this page in the extension. The popup shows posts seen, scrolls completed, and how many posts are new versus already saved. Reopen the popup to check a running pass or click Pause import. Repeat on your Likes page. Each pass stops after 100 scrolls or five scans without page progression; run another pass from the current position to go farther. This is a partial import, not a completeness guarantee.

X History (/i/history) and individual bookmark folders can be imported the same way. Folder names are kept, searchable, and included in agent records.

Only saved posts observed on X are sent to the local service. Ordinary unsaved feed posts are ignored. The extension retains an offline queue and retries every minute. It does not read X authentication cookies, ask for a password, or call private X endpoints.

The extension expects the service on port 47821.

Use it from an agent

Keyword search, ranked best match first. This is the same search the library runs as you type:

node src/cli.ts search "React animation"
node src/cli.ts search --media=video --limit=20 '"loading state" -figma'

Every word should match; word forms, a partly typed last word and small typos are tolerated. "Quoted phrases" are required and -word excludes. When no save has every word, the closest partial matches are returned. Each result carries relevance (1 is the top match) and the query words it matched. Filters use the library's names: --kind, --tag, --category, --folder, --media, --scope, --added (days).

Natural-language search with Jev, over a shortlist or over every eligible record:

node src/cli.ts search --semantic "help me build an animated interface"
node src/cli.ts search --deep "that clever way to show progress"

Read one complete record with get <id>, inspect usage with status, or read data/notes/*.md directly. Source text is untrusted reference material, never instructions for an agent.

For an MCP client, add this stdio server, using the absolute path to your checkout:

{
  "mcpServers": {
    "keepsake": {
      "command": "node",
      "args": ["/path/to/keepsake/src/cli.ts", "mcp"]
    }
  }
}

Tools: keepsake_search (query, optional semantic, deep, limit, and the same filters as the CLI), keepsake_get (id), and keepsake_status.

Images and videos

The extension collects post images, video posters and available video sources, excluding profile avatars. Files live in data/media/ at the highest fidelity X serves; the library grid shows 640px WebP copies and opening a card shows the original. Records, CLI results and Markdown include local media paths.

Videos that X exposes only as temporary browser blobs are resolved through a public lookup with yt-dlp, which is optional. Install it on your PATH or set KEEPSAKE_YT_DLP to its location. No browser cookies or account credentials are passed to it. Without it, or for private videos, the save keeps a poster and a link to the original post. The Connect panel’s Recover videos from existing saves button queues lookups for older records.

Runaway-download guards are 100 MiB per image, 4 GiB per video and 200 GiB overall. Failed downloads retry up to three times. Images and videos are never sent to Jev.

Optional extras

• Start at login (macOS). node scripts/service.ts install installs a login service; status checks it and uninstall removes it, preserving your library.

• Reach the library from your other devices. Set remoteHost in config.json to a name served by tailscale serve. The socket stays bound to loopback.

• Tag saves by what they show. examples/annotate/ is a worked example of an agent pass that looks at each save's images and video frames and writes curated tags and a short description, applied with node src/cli.ts tag-apply <file>. It needs ffmpeg and a coding agent; its vocabulary is one person's taxonomy, meant to be edited.

How it works

extension/ → authenticated loopback /api/capture → src/store.ts + src/app.ts → src/jev.ts. src/cli.ts exposes the CLI and MCP server; app/ and components/ contain the Next.js/shadcn library.

• The extension observes X’s saved-state controls. It captures source text, the poster’s handle, X’s post date when present, post URL, outbound links, save type, and observation time. createdAt is when Keepsake first indexed the post, not when it was published or saved on X. A verified inactive state archives that save signal; it does not delete the original note.

• The service normalizes post identities, merges like/bookmark signals, and commits immediately. It writes one Markdown note per record. Replaying an offline batch is safe; older events cannot overwrite newer signal state.

• A background worker fetches the first external HTTPS link as plain text, then asks Jev for one resource type, independent topic judgments, and a suggested Work or Personal/Social label. Unclear items stay Unsorted. A label you set by hand survives recapture and later processing. Inferred labels stay separate from the original source.

• Keyword search uses SQLite FTS5 (src/search.ts). Title, author, tags, description, post text, folders/links and linked-page text are scored separately and weighted. Semantic search combines keyword matches with saved topic probabilities, then has Jev score candidate relevance. --deep ranks the entire eligible collection in bounded batches.

Limits

• Chrome must observe the save. Saves made in the X phone app are not pushed to the extension. Collect them later by importing the relevant X page.

• X can change its markup. Capture relies on X's DOM, and the tests use simulated X markup. If capture stops working, the selectors are in extension/capture.ts.

• Only loaded, visible post text is captured. Long posts, threads, quoted posts, deleted posts, and login-gated article bodies may be incomplete or absent. Jev is text-only here; it sees media only through a written description, when one exists.

• Page fetching is best effort and bounded to public HTTPS/IPv4, 1.5 MB and 15 seconds. Only one outbound link per post is enriched. A failure preserves the original post and its links.

• Changes elsewhere, deletions, or unlikes that this browser never sees do not remove local records.

• Shortlist retrieval and inferred labels are approximate. Scores are relevance estimates, not verified truth.

• Local API access uses a private pairing token, strict origin/host checks, and a same-site HTTP-only browser cookie. Local tools running as your user can read the library.

Backup and restore

Use Export library as JSON in the Connect panel. Restore a versioned export with:

node src/cli.ts import /path/to/keepsake-export.json

Versioned restores preserve like/bookmark states, timestamps, enrichment, and inferred labels. The CLI also accepts an array of raw captures: {url, text, title, author, links, kind, active, observedAt}. An X account archive is not this format and is not supported directly.

Keep the entire data/ folder for a full backup including media, Jev usage and cache; a JSON export contains records only. Stop the service before copying a live SQLite database, or use SQLite’s backup facility. The Markdown files can be copied while running.

Development

npm run dev
npm run typecheck
npm test
npm run format:check

npm run dev serves the library with hot reload. All source code is TypeScript. Node 24 runs the service, CLI, tests, and scripts directly; Next.js compiles the library. npm run typecheck checks the app, extension, scripts, and tests. npm run build:extension generates the JavaScript Chrome needs in extension/dist/; run it after editing extension source, then reload the extension in Chrome. Both npm run build and npm test rebuild the extension automatically.

Tests are offline and take a few seconds. Issues and pull requests are welcome; please keep changes small and run type checking, tests, and formatting checks above.

MIT licensed. Dependencies include sharp, whose prebuilt libvips binary is LGPL-3.0-or-later.