PragmaSearch — local-first semantic search engine

PragmaSearch is a free, self-hosted semantic search engine — an open-source, local-first Algolia alternative. It combines vector (meaning-based) search and BM25 keyword search into one hybrid ranking, with typo tolerance, faceted filtering, and multilingual support — no cloud, no API keys, $0 per search.

Search "something for gaming" and get back an RTX 5090 — even though the word "gaming" appears nowhere in its title. The model runs on your own machine or server, so you replace your hosted-search bill with $0.

Paying $500/mo for hosted search on a 5,000-product shop? A small VPS is more than powerful enough to do it locally, for free. Try the live demo →

✨ Features

• 🧠 Semantic search — understands meaning via vector embeddings (Transformers.js), not just keywords
• 🔀 Hybrid ranking — fuses vector + BM25 keyword search with Reciprocal Rank Fusion, plus an exact-match boost for SKUs/brands/part numbers
• 🔤 Typo tolerance — opple → apple, configurable (length-scaled, à la Algolia)
• 🎛️ Filtering, faceting & pagination — refine by category / brand / price with live facet counts
• 🌍 Multilingual — English by default; any language via a multilingual model
• 📦 Zero infrastructure — one local index file, the model ships with the package; self-host on a $5 VPS
• 🪶 One runtime dependency — just the model runtime. Own your stack.
• ⚡ Fast — brute-force cosine + in-memory BM25; no vector database needed for small–mid catalogs

🆚 PragmaSearch vs hosted search

| | Algolia / hosted | PragmaSearch | |---|---|---| | Cost | $ per search / per record | $0 | | Hosting | their cloud | your machine / VPS | | API keys / signup | required | none | | Your data & user queries | leave your infrastructure | stay on your infrastructure | | Semantic (meaning) search | paid add-on | built in | | Typo tolerance | ✅ | ✅ | | Filtering · faceting · pagination | ✅ | ✅ | | Result highlighting | ✅ | ✅ | | Synonyms · ranking rules (boost/bury/pin) | ✅ | ✅ docs | | Analytics (top / zero-result queries) | ✅ | ✅ docs | | UI: widget + React + Vue | ✅ | ✅ widget · React · Vue |

Built for small-to-mid catalogs (≤ ~50k items). For million-SKU real-time catalogs with deep analytics and A/B testing, the hosted platforms still win — see the roadmap.

🚀 Quick start

npm install pragmasearch

# build the index from your catalog (a one-time pass over your own data)
npx pragmasearch index products.json

# search it — try a query whose words aren't in any title
npx pragmasearch search "something for gaming"

Programmatic API:

import { buildIndex, saveIndex, loadIndex, createSearcher } from "pragmasearch";

const index = await buildIndex(products);          // embed your catalog once
await saveIndex("pragmasearch-index.json", index); // one local file

const searcher = await createSearcher(await loadIndex("pragmasearch-index.json"));
const hits = await searcher.search("something for gaming", 5);

🔍 How it works

1. Index once (build time): each product is run through a small embedding model that ships with the package, turning it into a vector — a numeric fingerprint of meaning. Saved to a single local file alongside a BM25 keyword index.
2. Search anytime: the query is embedded locally, scored against the vectors (cosine) and the keyword index (BM25), fused with RRF, and the top matches are returned in ~tens of ms.

No registration. No account. No third-party service ever sees your catalog or your users' queries.

🖥️ Demo server

A small server serves a search UI + /api/search, with instant in-browser autocomplete, a faceted refinement sidebar (category / brand / price), pagination, and a Hybrid / Vector / Keyword toggle. Live demo →

npm install
npm run demo            # http://localhost:5173

Point it at any catalog/model by building an index and passing it: npx tsx demo/server.ts your-index.json. The query is embedded on your host — deploy on any persistent host (Railway / Render / Fly / VPS), see DEPLOY.md.

🌐 Models & languages

Default model is Xenova/all-MiniLM-L6-v2 (English, ~23 MB). For other languages, index with --model Xenova/multilingual-e5-small — query/passage prefixes are applied automatically. The model is recorded in the index, so query and document encoders always match. See the model table.

📚 Documentation

• Configuration reference — every option: indexing, search, filters, facets, synonyms, ranking rules, server env vars, models.
• Drop-in widget · React · Vue — embed search UI with the vanilla widget or native React/Vue components.
• Performance & VPS sizing — what CPU you need for ~50 ms search, RAM by catalog size, scaling.
• Deployment — Railway / Render / Fly / VPS, with Docker.
• Roadmap · Changelog

🗺️ Roadmap

Done: semantic + keyword hybrid search, typo tolerance, filtering, faceting, pagination, result highlighting, a drop-in widget + native React adapter (components + a headless hook), configurable searchable attributes & field weights, synonyms (multi-way + one-way query expansion), ranking rules (boost / bury / pin), incremental indexing (patch price/stock without re-embedding; upsert embeds only the delta), search analytics (top + zero-result queries, latency), custom ranking, a compact int8 index, signed multi-tenant tokens, language-aware tokenization, and a hardened production server (pragmasearch serve) — CLI + programmatic API + demo. Next: query-rule triggers, snippet windows, and a relevance benchmark — see ROADMAP.md.

💬 Community

Questions, ideas, or a use case we're missing? Open an issue or a discussion. Contributions welcome — see CONTRIBUTING.md.

❤️ Support

PragmaSearch is free and MIT-licensed. If it saves you a search bill, you can support ongoing development:

Or with crypto:

• ETH / ERC-20 — 0x6d9344F56E2dfF70751c37Fe2dF6aD12EDd48c11
• Solana — B6Sm1vzfs44Bzpy8VvncrnRfy7sByHUqrgHsDdKyMP2a

Every bit helps keep this maintained and free. 🙏

📄 License

MIT — free for commercial and personal use.