facetmark · Integrations and backups

The browser extension#

Search your bookmarks from the address bar, and save the page you are on without leaving it. The extension talks to the same local server the web page does.

Start the server: facetmark serve.
Load the extension from extension/ in the repository — Chrome: chrome://extensions, developer mode, Load unpacked.
Open its options. If the server is on the default port it pairs itself; otherwise paste the output of facetmark token.

Verify the connection

Search for a known bookmark in the extension and verify the result. Requests go to your configured service, which may call configured models. For remote use, check the URL, token and browser permissions.

Claude, Cursor, and anything else speaking MCP#

facetmark ships an MCP server, so an assistant can search your bookmarks as a tool instead of you pasting links into a chat window.

run it by hand first

facetmark mcp

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "facetmark": {
      "command": "facetmark",
      "args": ["mcp"]
    }
  }
}

Cursor takes the same shape in its own MCP settings. If facetmark is not on the PATH the editor sees, give the absolute path — that is the failure in nearly every report of “the tool never appears”.

what the assistant can and cannot do

It can search, read a bookmark, list sittings and ask a question over your library. It cannot delete anything, cannot write settings and cannot reach outside the database.

Verify tool access

Restart the client, check that facetmark tools appear, then search for a known title. GUI clients may not inherit your terminal PATH or environment; use an absolute executable path and explicit environment settings when needed.

karakeep#

If you keep your links in karakeep, facetmark can index from there instead of from a browser export.

See the karakeep integration reference. Compare a small sample against direct retrieval before connecting your full library.

Measured, and worth knowing before you commit

A round trip through karakeep's own keyword extraction cost 0.81 points of Recall@5 (CI95 −2.44 to +0.81) and agreed with the direct index on the top result 79.06 % of the time. The vocabulary collapses: 19,016 distinct terms became 13. The verdict recorded in the repository is roundtrip_unfaithful — usable, not equivalent. Index the pages directly if you can.

The command line#

Everything the page does, and a few things it does not. Add --help to any of them.

Command	Does
`facetmark import`	Read a bookmarks export in
`facetmark browsers`	Find bookmark files already on this machine
`facetmark index`	Build or top up the index
`facetmark reindex`	Build it all again from scratch
`facetmark search`	Search from the shell
`facetmark show`	Everything about one bookmark
`facetmark sessions`	List the sittings
`facetmark stats`	The Library screen, as text
`facetmark health`	Find dead links
`facetmark serve`	The web page and the API
`facetmark mcp`	The MCP server
`facetmark token`	Print the pairing token
`facetmark config path`	Where settings are written
`facetmark config show`	Every setting, masked
`facetmark migrate`	Bring an old database forward
`facetmark demo`	A fake library, to look around in
`facetmark eval`	Re-run the retrieval measurements
`facetmark version`	Version

facetmark demo is the honest way to decide whether you want this: it builds a library out of generated pages, with no key and no network, so you can click every screen before importing anything of your own.

Back up and restore#

Portable bookmark export

shell

facetmark export bookmarks-backup.json

The export preserves bookmark data; derived indexes must be rebuilt after import. Verify restoration in a separate data directory before touching your existing library.

shell

facetmark import bookmarks-backup.json
facetmark index

Full backup including text and vectors

Find the database path with facetmark stats. Stop the service and all CLI / MCP processes using it before copying the database. If -wal / -shm files remain, do not discard them; use SQLite backup facilities for a consistent snapshot.

After restoring

Restore into a separate directory, run facetmark stats against that database, compare counts and search a known title. Keep the original backup before upgrading. Store configuration and pairing tokens separately; they can contain secrets.