mindmark 0.1.3

Local semantic search over your browser bookmarks — on-device embeddings, no cloud.

🔖 mindmark

Your bookmarks, finally searchable.
Ask in natural language — mindmark remembers what you saved.

100% local · No cloud · No API keys · Nothing leaves your machine

---

Table of Contents

• Features
• Prerequisites
• Install
• Quick Start
• Usage
• How It Works
• Storage Layout
• Uninstall
• Development
• License

---

✨ Features

Command	What it does
mindmark index <file>	Parse an exported bookmarks HTML file, embed every bookmark locally, store vectors in SQLite
mindmark find "query"	Semantic search over titles, folders, domains, and URL slugs — returns top-K with similarity scores
mindmark open "query"	Search and open the best match in your default browser
mindmark stats	Show index size, model info, top domains, and top folders

🔌 Works offline after the first run. Embeddings run on-device via fastembed (ONNX Runtime, ~130 MB one-time model download).

---

📋 Prerequisites

Requirement	Details
Python 3.9+	python.org/downloads — on Windows, check "Add Python to PATH" during setup
pip	Bundled with Python — verify with pip --version or pip3 --version
Internet	Needed only once to download the embedding model (~130 MB). Everything after that is offline

💡 Windows tip — Python PATH

If you installed Python from the Microsoft Store, python and pip are already on your PATH.
If you installed from python.org, make sure you checked "Add Python to PATH" during setup.

---

📦 Install

Recommended — pipx (isolated + globally on PATH)

pipx install mindmark

Don't have pipx?

pip install --user pipx && pipx ensurepath    # then restart your terminal

Or on macOS with Homebrew: brew install pipx

Alternative — pip with a virtual environment

macOS / Linux:

python3 -m venv .venv && source .venv/bin/activate
pip install mindmark

Windows (PowerShell):

python -m venv .venv; .venv\Scripts\Activate.ps1
pip install mindmark

Windows (Command Prompt):

python -m venv .venv && .venv\Scripts\activate.bat
pip install mindmark

Editable install for development

git clone https://github.com/sukanth/mindmark.git
cd mindmark
pip install -e .[dev]

---

⚡ Quick Start

1️⃣ Export your bookmarks

Browser	How
Edge	edge://favorites → ⋯ → Export favorites → save as HTML
Chrome	chrome://bookmarks → ⋮ → Export bookmarks → save as HTML
Firefox	Ctrl+Shift+O (Cmd+Shift+O on macOS) → Import and Backup → Export Bookmarks to HTML

2️⃣ Build the index

# macOS / Linux
mindmark index ~/Downloads/bookmarks.html

# Windows (PowerShell)
mindmark index "$env:USERPROFILE\Downloads\bookmarks.html"

First run downloads the embedding model (~130 MB) and caches it locally. Every run after that is instant and fully offline.

3️⃣ Search in natural language

mindmark find "python async tutorial"
mindmark find "react hooks best practices" -k 5
mindmark find "helm chart examples" --domain github.com
mindmark find "docker compose setup" --folder devops

4️⃣ Open a result directly

mindmark open "k8s cheat sheet"           # opens the best match
mindmark find "docker setup" --open 2     # opens result #2 from the list

💡 Tip — create a short alias

macOS / Linux — add to ~/.bashrc or ~/.zshrc:

alias mm='mindmark open'
mm "docker setup"

Windows — add to your PowerShell $PROFILE:

Set-Alias mm mindmark
mm open "docker setup"

5️⃣ JSON output for scripting

Pipe results into fzf, jq, Alfred, Raycast, PowerToys Run, or any tool that accepts JSON:

# macOS / Linux
mindmark find "istio service mesh" --json | jq '.[].url'

# Windows (PowerShell)
mindmark find "istio service mesh" --json | ConvertFrom-Json | ForEach-Object { $_.url }

---

📖 Usage

Filters

Narrow down results without changing your query:

mindmark find "useful tools" --domain github.com     # only github.com results
mindmark find "useful tools" --folder work/kusto      # only bookmarks in matching folders
mindmark find "useful tools" -k 20                    # return top 20 instead of 10

Re-indexing

Just rerun mindmark index <file>. It clears and rebuilds the index. The model is cached, so re-indexing 800+ bookmarks takes only seconds.

Swap the embedding model

mindmark index bookmarks.html --model BAAI/bge-small-en-v1.5              # default, 384-dim
mindmark index bookmarks.html --model sentence-transformers/all-MiniLM-L6-v2
mindmark index bookmarks.html --model BAAI/bge-base-en-v1.5               # 768-dim, higher quality

Switching models triggers a full re-embed automatically. See the fastembed supported models list.

---

🧠 How It Works

Bookmarks HTML                                  "python async tutorial"
      │                                                  │
      ▼                                                  ▼
  ┌────────┐    ┌──────────┐    ┌──────────┐     ┌──────────┐
  │ Parse  │───▶│  Embed   │───▶│  Store   │     │  Embed   │
  │  HTML  │    │ (ONNX)   │    │ (SQLite) │◀────│  query   │
  └────────┘    └──────────┘    └──────────┘     └──────────┘
                                      │                │
                                      ▼                ▼
                                ┌──────────────────────────┐
                                │  Dot-product similarity  │
                                │   → top-K results        │
                                └──────────────────────────┘

1. Parse — A stateful tokenizer reads the Netscape bookmarks HTML and extracts every link with its full folder path.
2. Embed — Each bookmark becomes a rich text string (title | folder | domain | path) and is passed through a BGE/MiniLM ONNX model. Vectors are L2-normalized.
3. Store — Vectors live as float32 blobs in a single SQLite file. For 800–10,000 bookmarks this is simpler than a vector DB and still sub-millisecond.
4. Search — Encode the query, compute dot products against all vectors, return the top-K.

---

🗂️ Storage Layout

What	macOS / Linux	Windows	Override
Index database	~/.mindmark/index.db	%LOCALAPPDATA%\mindmark\index.db	--db flag or MINDMARK_DB env var
Home directory	~/.mindmark/	%LOCALAPPDATA%\mindmark\	MINDMARK_HOME env var
Embedding model	~/.cache/fastembed/	%LOCALAPPDATA%\fastembed\	Managed by fastembed

---

🗑️ Uninstall

pipx uninstall mindmark    # if installed with pipx
pip uninstall mindmark      # if installed with pip

Remove stored data (optional)

The index and cached model are stored outside the package:

macOS / Linux:

rm -rf ~/.mindmark              # index database
rm -rf ~/.cache/fastembed        # cached embedding model (~130 MB)

Windows (PowerShell):

Remove-Item -Recurse "$env:LOCALAPPDATA\mindmark"     # index database
Remove-Item -Recurse "$env:LOCALAPPDATA\fastembed"     # cached embedding model

If you set a custom MINDMARK_HOME, remove that directory instead.

---

🛠️ Development

Contributions are welcome! See CONTRIBUTING.md for full details.

git clone https://github.com/sukanth/mindmark.git
cd mindmark
pip install -e .[dev]
pytest -q

Publishing to PyPI

First-time setup

1. Create an account at pypi.org
2. Generate an API token at pypi.org/manage/account/token/
3. Install build tools: pip install build twine

Test on TestPyPI first (recommended)

python -m build
python -m twine upload --repository testpypi dist/*
pipx install --index-url https://test.pypi.org/simple/ mindmark

Publish to PyPI

python -m build
python -m twine upload dist/*

Use __token__ as the username when prompted.

Alternative distribution methods

GitHub release

python -m build
gh release create v0.1.0 dist/*
# Users install:
pipx install https://github.com/sukanth/mindmark/releases/download/v0.1.0/mindmark-0.1.0-py3-none-any.whl

Standalone executable (no Python required)

pip install pyinstaller
pyinstaller --onefile -n mindmark -p src src/mindmark/__main__.py
# Creates: dist/mindmark (macOS/Linux) or dist/mindmark.exe (Windows)

Docker

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir .
ENTRYPOINT ["mindmark"]

docker build -t mindmark .
docker run --rm -v $HOME/.mindmark:/root/.mindmark \
    -v $HOME/Downloads:/downloads mindmark \
    index /downloads/bookmarks.html

---

📄 License

MIT — see LICENSE.