01Open it
facetmark serveThat prints a URL — http://127.0.0.1:8765 by default — and keeps running. Open the URL. Leave the terminal alone; closing it stops the server.
The server is bound to your own machine and the page hands itself a token when it can prove both ends are local. That is why there is no login screen and why there is nothing to create an account for.
If you reach it by any other name — a LAN address, a tunnel, a reverse proxy — the handshake is refused on purpose and the page asks you to paste the token instead. Get it with facetmark token.
There is one token and no rate limit. It is built to be reachable from the chair you are sitting in.
02The first time: three steps
On an empty library the page opens on a setup screen instead of on search, because a search box over zero bookmarks is a dead end. Three framed steps, in order, each one done from the browser:
- Bring your bookmarks in. Export from your browser (Bookmarks → Manage → Export) and drop the HTML file on the button. A Chrome
BookmarksJSON file works too; the importer sniffs which one you gave it. - Point it at a model, or don't. Paste an API key, or switch the embedding backend to local and skip the key entirely. Either way the page tests the connection before you rely on it.
- Build the index. One button. Seven stages, shown as they happen, with a log. You can close the tab and come back — the job runs in the server, not in the page.
Once all three frames carry a tick the screen offers you the search box and gets out of the way. It will not come back unless the library empties out again.
03The five tabs, and the gear
| Screen | What it is for |
|---|---|
| Search | The main event. Type, get ranked pages, see which of the four paths found each one. |
| Ask | A question in a sentence, answered from your own pages, with every sentence traceable to the bookmark it came from. It quotes; it does not invent. |
| Library | What the index actually contains: how many pages have text, how many have vectors, which links are dead, what is queued, what has never been opened. |
| Sittings | Bookmarks you saved in the same stretch of time, grouped. Useful when you remember when and nothing else. |
| System | Version, database path, provider, uptime. The screen you screenshot into a bug report. |
| ⚙ Settings | Model, limits, privacy, and the index job. Behind the gear rather than in the tab row, because you open it twice a year. |
“Sittings” is not a typo for settings. A sitting is a stretch of saving — the twenty tabs you filed at eleven at night. The gear is where settings live.
04How to read a result
A row is a rank, a title, where it came from, a snippet with your words marked, and then the part no other bookmark search shows you: the paths that found it.
A vector over the page body. Found it because the page is about your query, whether or not it uses your words.
Full-text search, by word and by character triple. Found it because your exact string is in it. This is the one that saves you when you remember a name.
Vectors over questions generated from the page. Found it because someone might ask your question of this page.
Not a rank at all: pages one hop away in the graph, shown in their own group under the results. Saved-next-to and semantically-near.
Under the badges is a short bar in the same colours. That is the mixture: how much each path put into this one fused score. Two gold-heavy rows and a violet-heavy one means the first two matched your spelling and the third matched your meaning — which is usually the moment you learn something about your own query.
- never opened — facetmark has never watched you open this one. A browser export carries no usage history at all, so on day one this is true of everything.
- The ⋯ button at the end of a row — opens the page's own panel without leaving the results: full text stats, links, the sitting it belongs to.
- More options — picks how many of the four paths run. The default runs one; the last rung runs all four and reranks. It is slower and it is measurably better on vague queries.
05Keys, and reading it your way
| Key | Does |
|---|---|
| / | Jump to the search box from anywhere |
| ↑ ↓ | Move through suggestions |
| Enter | Search, or take the highlighted suggestion |
| Esc | Close the panel, or clear the box |
| Tab | Every control, in reading order |
- The sun/moon control switches theme; it follows your system until you touch it, then it remembers.
- 中文 / EN switches language. It changes the interface, not your data.
- Everything is real text at real sizes, so browser zoom works, and so does selecting it and copying it.
- If your system asks for reduced motion, the page has no motion. Nothing waits for an animation before it will show you a number.
06When it misbehaves
| What you see | What it is |
|---|---|
| The page loads but asks for a token | You reached it by something other than 127.0.0.1 or localhost. Run facetmark token and paste, or use the local address. |
address already in use | Something else has the port. facetmark serve --port 8790. |
| Search returns nothing, library says 0 vectors | The index was never built. Gear → Run, or facetmark index. |
| Every result says never opened | Correct, and temporary. It starts meaning something after facetmark has seen you open a few pages through it. |
| The index job stops at fetch | Pages that will not load. It moves on; dead links show up in Library, and the pages still index on title alone. |