Command and API reference

Install#

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,700+ 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.

The data directory holds the database, pairing token and optional configuration. Back up the database and secrets separately; confirm paths with facetmark stats and facetmark config path.

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

See also: Quickstart

Get 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.

See also: Quickstart

Model access#

Online models share one OpenAI-compatible base_url and api_key. Verify that the endpoint supports the chat and embedding capabilities you need. A compatible gateway, self-hosted service or local embedding backend can cover missing capabilities.

The chat model generates summaries, topics, entities, key points and candidate questions. The embedding model converts page text and queries into vectors. Some derived content may be inferred from titles when bodies are missing.

Through an endpoint

export FACETMARK_API_KEY=sk-...
export FACETMARK_BASE_URL=https://api.openai.com/v1
export FACETMARK_CHAT_MODEL=gpt-6-luna
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-flash

Shared or free endpoints

Fallback chat models are tried in the configured order. Check that each is available on your account and endpoint; a fallback chain should not conceal incorrect endpoints or permissions.

export FACETMARK_CHAT_MODEL_FALLBACKS=deepseek-flash,deepseek-v4-pro

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

Local embeddings use sentence-transformers. After downloading the model, computation runs on the service machine; page fetching still contacts websites. If online chat is configured, summaries and synthesis may still call that provider.

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=BAAI/bge-m3   # or a local model directory
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.

See also: Models and configuration

Build the index#

facetmark index

Indexing runs in stages and reuses completed work by input fingerprint. New bookmarks or changes to text and model settings can require stages to run again; check the actual job output.

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

Cost depends on text length, models and provider pricing; start with a small sample. Fetching and site rate limits also affect duration. The default per-host concurrency is 2, with an interval between requests.

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.

See also: Quickstart

Search#

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

The query language#

Every search surface takes the same grammar: the web box, facetmark search, /search and /quick, the MCP tools, the karakeep plugin. It is a filter language, not a second ranker — a filter decides which pages are eligible and never moves a surviving page's score. Full reference: docs/query-language.md.

facetmark search "postgres domain:github.com -title:tutorial"
facetmark search "kafka added:<7d"          # saved this week
facetmark search 'title:encryption (signal|matrix)'
facetmark search "tag:work sort:date"       # a browse, newest first

Negation, phrases, alternation, wildcards

-facebook                    exclude a word
-domain:pinterest.com        exclude a whole site
"consumer group rebalancing"  an exact phrase
(security|privacy)           either word
domain:(github.com|gitlab.com)   either value
domain:*.github.io           * is any run of characters

Dates

A duration compares against the age of the bookmark, so added:>90d means older than 90 days. An absolute date compares against the timestamp directly, so added:>=2026-04-01 means on or after that day. The two read in opposite directions because both readings are the obvious one for their own form.

Sorting, and what a browse is

sort:date puts newest saves first; sort:-date puts oldest first. title, domain, url and opened are also supported. With filters or sorting but no free text, the query browses bookmarks without model calls. Lexical and local embedding search also avoid online embedding charges.

Your own tags

Netscape and pinboard exports carry a TAGS attribute, and it is kept: stored on the bookmark, returned with every hit, and queryable as tag:work. The match is on one whole element of the list, so tag:work never widens into workshop; use tag:(work|rust) for more than one. POST /bookmark and the MCP save_bookmark tool accept tags too, and re-importing a file unions the tags rather than replacing them.

Serve: HTTP API and the pairing token#

facetmark serve        # 127.0.0.1:8787

The token

The token is generated on first run and stored in pairing-token.txt in the data directory. Send Authorization: Bearer <token> or x-facetmark-token. Keep it out of public links and logs.

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

The local page#

facetmark serve provides the /app interface and HTTP API. The app includes search, synthesis, Library, Sessions and System; the gear opens Settings.

facetmark serve
# facetmark 2.0.0  http://127.0.0.1:8787
# open the search page:     http://127.0.0.1:8787/app
# pairing token written to the data directory
#   (facetmark config show lists the effective data_dir)

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.

Five tabs and administration entry points

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

Language and theme preferences are stored in the current browser and origin. The website and app use the same preference keys, but browser storage is not shared across domains. The interface respects reduced-motion preferences.

See also: Using the app

Paging: 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 controls how many results you see; retrieval depth controls the candidate pool. Reuse the response depth for subsequent pages to keep the ranking basis consistent.

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.

Browser 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

See also: Integrations and backups

MCP 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.

See also: Integrations and backups

karakeep 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.

See also: Integrations and backups

What 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.

Every 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

See also: Models and configuration

Every command#

Use facetmark COMMAND --help to check each command. Database commands generally support --db; many offer --json for scripts.

Running your own evaluation

Evaluation accepts JSONL queries with {text, qtype, target_url}, compares retrieval configurations on a specified library, and reports confidence intervals and paired tests. Fix the dataset and protocol before interpreting results.

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

See also: Integrations and backups

Troubleshooting#

Every model call returns 404

Check the complete provider base URL, including its path prefix (often /v1), and the available model name. A 404 can indicate the URL or model name; it does not by itself prove the API key is invalid.

“dimension mismatch” on index or search

The database dimension differs from FACETMARK_EMBED_DIM. Confirm the model output dimension, correct the configuration, restart the service and rebuild the index. Keep a database backup before changing it.

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.

See also: Quickstart