Connect it to the rest of your desk

The database is one SQLite file and everything here is a different door into it: your browser, your editor, your agent, your shell.

01The 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.

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

Nothing is uploaded and there is no account. If the server is not running, the extension does nothing at all.

02Claude, 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.

03karakeep

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

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.

04The command line

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

CommandDoes
facetmark importRead a bookmarks export in
facetmark browsersFind bookmark files already on this machine
facetmark indexBuild or top up the index
facetmark reindexBuild it all again from scratch
facetmark searchSearch from the shell
facetmark showEverything about one bookmark
facetmark sessionsList the sittings
facetmark statsThe Library screen, as text
facetmark healthFind dead links
facetmark serveThe web page and the API
facetmark mcpThe MCP server
facetmark tokenPrint the pairing token
facetmark config pathWhere settings are written
facetmark config showEvery setting, masked
facetmark migrateBring an old database forward
facetmark demoA fake library, to look around in
facetmark evalRe-run the retrieval measurements
facetmark versionVersion

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.

05Backing it up, and moving it

One file. Copy it and you have copied everything — bookmarks, text, vectors, graph, history.

find it
facetmark stats
Stop the server first

The database runs in WAL mode, so a copy taken while something is writing can miss the tail of the log. Stop facetmark serve, copy, start it again.

  • Moving machines: copy the file, then facetmark migrate if the versions differ.
  • Your bookmarks are also still in your browser. The worst case is re-importing and rebuilding, which costs time and a few model calls, not data.
  • The config file is separate and holds your API key. Back it up somewhere you would put a password, or not at all.