Guide

01Install

Python 3.10 or newer, on Windows, macOS or Linux. The base install has no compiled machine-learning dependency; vector search comes from sqlite-vec, which is a SQLite extension.

pip install facetmark
# or, if you use uv:
uv pip install facetmark

facetmark version

With local embeddings

Only needed if you want to embed pages on your own machine instead of through an endpoint. This pulls in PyTorch and sentence-transformers, which is a few hundred megabytes.

pip install "facetmark[local]"

From source

git clone https://github.com/88lin/facetmark
cd facetmark
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

pytest -q                 # 1,514 tests
ruff check src tests scripts

Where your data lives

One directory, chosen per platform, holding one SQLite file. Override it with FACETMARK_DATA_DIR, or point any command at a specific file with --db.

Inside it: facetmark.db and pairing-token.txt. That is the whole installation footprint. Deleting the directory uninstalls the data.

Try it with no key and no network

facetmark demo generates a synthetic library, indexes it with a deterministic offline provider, and runs three searches against it. It is how the terminal on the front page was recorded.

facetmark demo --size 60

02Get your bookmarks in

Import is one-way and read-only. facetmark reads a browser profile or an exported file, and never writes to either.

Chromium-family: no export needed

Chrome, Edge, Brave, Vivaldi, Chromium, Opera and Opera GX all keep bookmarks in a JSON file that facetmark can find on its own. Reading it is safe while the browser is running.

facetmark browsers        # what it can see
facetmark import          # import, if there is exactly one

If more than one profile is installed, the choice is not guessed — importing the wrong person's bookmarks is worse than one extra command. The candidates are printed and you pass the one you want:

facetmark import "$HOME/.config/google-chrome/Default/Bookmarks"

Firefox and Safari: export to HTML first

facetmark import ~/Downloads/bookmarks.html

What import reports

The same command handles Netscape HTML and Chrome JSON, and prints what it did rather than a spinner. On one real 1.7 MB export with 96 folders nested four deep, it parsed 1,710 entries, inserted 1,701, merged 9 duplicates and skipped 1 as non-indexable.

03Model access

facetmark reaches models through one OpenAI-compatible endpoint. There is deliberately no provider-specific branching anywhere in the codebase: one base_url plus one api_key covers OpenAI, DeepSeek, Kimi, Zhipu, SiliconFlow, Aliyun Bailian, together.ai, Azure OpenAI, Ollama, vLLM, LM Studio and any internal gateway that speaks the same shape.

Two model roles are used. A chat model writes enrichment (summary, topics, entities, key points) and candidate intent queries. An embedding model turns page bodies into vectors.

Through an endpoint

export FACETMARK_API_KEY=sk-...
export FACETMARK_BASE_URL=https://api.openai.com/v1
export FACETMARK_CHAT_MODEL=gpt-4o-mini
export FACETMARK_EMBED_MODEL=text-embedding-3-small
export FACETMARK_EMBED_DIM=1536

Instead of environment variables you can drop a .env file next to where you run the command. Same names, same prefix.

FACETMARK_API_KEY=sk-...
FACETMARK_BASE_URL=https://api.deepseek.com/v1
FACETMARK_CHAT_MODEL=deepseek-chat

Shared or free endpoints

On endpoints where a listed model can be absent, out of quota, or unable to honour response_format, set a fallback chain. It is empty by default on purpose: a paid endpoint returning an error is telling you something, and swallowing it is worse than failing.

export FACETMARK_CHAT_MODEL_FALLBACKS=deepseek-chat,qwen-plus

The provider records which model actually answered each call. Any report built on a failover chain has to publish that mix.

Local embeddings, no key

Runs the embedding model on your own machine through sentence-transformers. Combined with an empty API key, nothing except page fetching leaves the machine.

pip install "facetmark[local]"

export FACETMARK_EMBED_BACKEND=local
export FACETMARK_EMBED_MODEL=bge-m3
export FACETMARK_EMBED_DIM=1024
export FACETMARK_LOCAL_EMBED_PATH=/path/to/bge-m3   # unset = download
export FACETMARK_LOCAL_EMBED_MAX_SEQ=1024

No model at all

Everything still installs and runs. You keep both lexical facets, saving sessions, the domain and link graph, and link health. You lose the content facet and the intent facet. facetmark search --quick is the explicit lexical-only path and makes no model call.

04Build the index

facetmark index

One command runs every stage in order. Each stage is idempotent and fingerprinted, so running it again after adding fifty bookmarks does the work for fifty bookmarks, not for the whole library.

Useful flags

How fingerprints work

• Enrichment is keyed on the hash of the page body. Same body, no second chat call.
• Embedding is keyed on the reconstructed embed text, not on the body. So if enrichment changes and the embed text changes with it, the stale vector is detected rather than trusted — which is how the karakeep round-trip damage was caught.
• Sessions and edges are rebuilt from scratch each run; they are cheap and depend on the whole library.

facetmark reindex throws away every derived artefact and rebuilds from the bookmarks themselves. facetmark migrate brings an older database up to the current schema, taking a snapshot first unless you pass --no-backup.

What indexing costs

Money is dominated by enrichment: roughly one small chat call per page, so a 1,700-page library on a cheap model is cents. Wall time is dominated by fetching, and fetching is deliberately slow — FETCH_PER_HOST_CONCURRENCY is 2 and there is a minimum interval between hits on one host.

For a sense of scale: that real 1,700-bookmark library, indexed with --no-fetch, produced 322 saving sessions, 9,132 edges, 1,386 distinct domains and 1,775 vectors.

05Search

facetmark search "the post about keeping vectors in sqlite"
facetmark search "sqlite-vec" -n 20 --explain
facetmark search "error EADDRINUSE" --quick

Profiles and rungs

--config accepts any pre-registered rung, any shipped profile, and about twenty exploratory ablations. facetmark eval --help documents the rung syntax; the rungs themselves are listed in search/pipeline.py.

What the ranking is made of

Selected facets each return up to CANDIDATES_PER_FACET hits. Reciprocal rank fusion combines them as sum_f w_f / (k + rank_f) with k = 60. Then context, decay and rerank run in that order, and one-hop graph expansion is returned as a separate group — not mixed into the ranking, because it was measured as an addition, not a replacement.

Reading a saving session

facetmark sessions -n 20     # recent saving episodes
facetmark show 412 --body    # one bookmark as JSON
facetmark stats              # index size and coverage

06Serve: HTTP API and the pairing token

facetmark serve        # 127.0.0.1:8787

The token

Minted on first run into pairing-token.txt in your data directory. Send it as the x-facetmark-token header.

facetmark token             # print it
facetmark token --rotate    # invalidate the old one

TOKEN=$(facetmark token)

curl -s http://127.0.0.1:8787/health

curl -s -X POST http://127.0.0.1:8787/search \
  -H 'content-type: application/json' \
  -H "x-facetmark-token: $TOKEN" \
  -d '{"q":"vectors inside sqlite","limit":5}'

POST /search

Every route

07The local page

facetmark serve also hosts a search page. It is the one interface that needs nothing installed beyond facetmark itself — no browser extension to load, no editor to configure, no curl.

facetmark serve
# facetmark 1.6.1  http://127.0.0.1:8787
# open the search page:     http://127.0.0.1:8787/app
# pairing token written to: ~/.facetmark/pairing-token.txt

Plain HTML, CSS and ES modules inside the Python package: no Node, no bundler, no build artefact that can go stale against the server it talks to. Because the page is served by the same process as the API it is same-origin, which is also why it cannot be hosted anywhere else — CORS on this service is restricted to browser-extension origins.

Two views

What the markers on a row mean

The same vocabulary the extension popup uses. In the page each one carries a one-line explanation on hover; the table is here so you can read them all at once.

Rows in that second group carry a chip for the edge that reached them — same sitting (saved in the same browsing session), similar (close in meaning), replaced by, same page, same site. The weights behind those names are in the settings table.

How the page gets the token

It asks GET /app/boot, which is the only route that can hand out the pairing token, and only when both the caller and the address in the request are loopback. On your own machine both are true and the page pairs itself with nothing to copy.

Keyboard

Language and theme

English and Chinese, switched in the header and remembered. Without a stored choice the page follows the browser’s language. The theme switch cycles system → light → dark and shares its stored key with this site, so a reader who picked dark here gets dark there. Everything animated is inside a prefers-reduced-motion query.

08Paging: limit, offset and depth

Every search surface takes limit, offset and depth, and every search response reports the window it actually served rather than echoing what you asked for.

facetmark search "kafka rebalance" -n 20
facetmark search "kafka rebalance" -n 20 -o 20 --depth 60

The CLI prints the --offset and --depth for the next page whenever there is one. Over HTTP the same three fields go in the POST /search body:

{
  "hits": [ ],
  "limit": 20,          // served, after clamping
  "offset": 20,
  "depth": 60,          // the depth this ranking ran at
  "total": 137,         // ranked so far; a floor when capped
  "has_more": true,
  "depth_capped": false
}

Why depth is a parameter and not an implementation detail

Page size and retrieval depth used to be the same number: asking for more rows quietly retrieved deeper, and result 51 was unreachable at any page size because the pool was 50 rows regardless. Now the page is a window onto a pool whose size you can see and pin.

The two ceilings

MAX_PAGE_SIZE (200) bounds one page. MAX_CANDIDATE_DEPTH (2000) bounds the pool behind all of them, and hitting it is what sets depth_capped. Both are clamped in one place, before any query runs, so an oversized request costs nothing and is answered with the window that was actually served.

09Browser extension

Manifest V3, for Chromium-family browsers. It talks to 127.0.0.1:8787 and nothing else — those are its only required host permissions.

1. Download facetmark-extension.zip from the releases page and unzip it.
2. Open chrome://extensions, turn on Developer mode, choose Load unpacked and select the unzipped folder.
3. Run facetmark serve in a terminal and leave it running.
4. Run facetmark token, open the extension's options page, and paste the token.
5. Press Ctrl+Shift+K (Cmd+Shift+K on macOS) and search.

What it gives you

Options

10MCP server

facetmark mcp runs a FastMCP server on stdio, so an MCP client such as Claude Desktop can search your library, read a saving session, and save a page.

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

Add "--db", "/path/to/facetmark.db" to args to point at a specific library, or "--mock" to try it with no key. Environment variables are read the same way as for every other command.

Nine tools

Three resources

• bookmark://{id} — one record as JSON.
• session://{id} — one saving episode.
• facetmark://stats — index size and coverage.

11karakeep plugin

karakeep is a self-hosted bookmark manager with a pluggable search provider. This plugin puts facetmark behind its search box, so karakeep keeps the UI and facetmark does the retrieval.

1. Copy the plugin into karakeep's plugin package.
2. Register it in the exports map.
3. Load it after meilisearch, because the plugin manager hands out the last provider registered.
4. Point it at a running facetmark service.

cp -r integrations/karakeep/search-facetmark \
  /path/to/karakeep/packages/plugins/search-facetmark

// packages/plugins/package.json — exports map
"./search-facetmark": "./search-facetmark/index.ts"

// packages/shared-server/src/plugins.ts, in loadAllPlugins()
await import("@karakeep/plugins/search-meilisearch");
await import("@karakeep/plugins/search-facetmark");  // must come after

export FACETMARK_URL=http://127.0.0.1:8787
export FACETMARK_TOKEN=$(facetmark token)
facetmark serve

How the contract is kept honest

• Upstream karakeep types are pinned by blob SHA in integrations/karakeep/typecheck/upstream-pins.json, and CI runs tsc --noEmit against them.
• The wire format is captured in integrations/karakeep/contract/wire.json and replayed by tests/test_karakeep_contract.py.
• That replay test caught a real one: at offset 1 of a single match, the correct answer is hits: [] with totalHits: 1. An empty hits array is not the same as no results.

To uninstall the bridge, drop the karakeep_doc table. enrichment.source_hash == 'karakeep' is reserved and means the bridge may overwrite that row; any other value means a real model wrote it and the bridge leaves it alone.

12What is in the database

One SQLite file. Open it with any SQLite browser; nothing is encrypted, obfuscated or proprietary. If you stop using facetmark, your data is still readable.

Link health and the cold layer

facetmark health                       # what is known
facetmark health --check               # actually probe the network
facetmark health --check --no-save-recovered   # read-only sweep

The sweep can use DNS-over-HTTPS, the Wayback availability API and a reader proxy to distinguish “gone” from “your DNS is broken”. Use --no-save-recovered before measuring anything against a library, so the sweep stays read-only apart from the health log.

13Every setting

Prefix every name with FACETMARK_ as an environment variable, or put it unprefixed in a .env file. Defaults below are the shipped values.

Storage

Model access

Local embeddings

Fetching

Enrichment and intents

Sessions, retrieval and decay

Link health and service

14Every command

Every command takes --db to point at a specific database file or data directory. Most take --json.

Running your own evaluation

This is the part of facetmark that matters most and the part nobody else has used yet. Give it a JSONL file of {text, qtype, target_url} and it will run any set of rungs against your own library with bootstrap confidence intervals and a McNemar test on the paired differences.

facetmark eval --no-build \
  --queries my-queries.jsonl \
  --rungs A,C,full \
  --bootstrap 10000 --concurrency 4 \
  --out report.json

15Troubleshooting

Every model call returns 404

The base URL is missing /v1. This is the most common setup failure by a wide margin, and the error surfaces as a provider error, so it reads like a credentials problem.

“dimension mismatch” on index or search

The embedding dimension recorded in meta at first build no longer matches FACETMARK_EMBED_DIM. facetmark refuses to mix vector dimensions rather than silently return nonsense. Either restore the old dimension, or re-embed everything with facetmark index --force.

Enrichment silently does nothing

The stored source_hash already equals the current body hash, so the fingerprint says the work is done. That is correct behaviour, and facetmark index --force overrides it.

Vectors exist but results are bad

Usually the embed text changed after the vector was written — for example because enrichment was replaced by a bridge. Re-embed with facetmark index --force. If results are bad on a fresh index instead, check whether you are accidentally on the mock provider: facetmark stats reports the embedding model in use.

disk I/O error from SQLite

SQLite cannot run reliably on some network and FUSE filesystems. Move the data directory to local disk with FACETMARK_DATA_DIR.

Fetching is slow, or pages come back empty

Both are usually intentional. robots.txt is honoured and per-host concurrency is capped at 2 with a minimum interval between hits. Some sites simply refuse. A page with no body still indexes — the pipeline falls back to a title-only fingerprint — it is just weaker. Use --no-fetch if you want a fast, shallow index.

The extension cannot reach the service

Check three things in order: facetmark serve is actually running; the endpoint in options matches the host and port it bound; the token in options matches facetmark token. If you rotated the token, the extension needs the new one.

Something else

facetmark stats and facetmark health print what the index actually contains, which resolves most confusion. Beyond that, open an issue — the --json output of the failing command is the most useful thing to paste.