Build a semantic search engine that understands meaning

Every search box you have ever used, from a text editor to a wiki, works the same way: it looks for the words you typed. Type "wifi" and it finds pages with "wifi" on them. That breaks the moment the page uses different words for the same idea. A note explaining how a VPN keeps you safe on a cafe network might never contain the words "wifi", "laptop" or "protect", so a keyword search for "how do I protect my laptop on public wifi" walks straight past the one note that answers it.

A semantic search fixes that. It turns each passage into a list of numbers that stands for its meaning, does the same to your question, and returns the passages whose meaning sits closest. This mission builds that, end to end, over a folder of plain notes. It is deliberately not a chatbot: there is no model writing answers, no made-up text, nothing to upload. It is the retrieval engine that sits underneath tools like Build your own "chat with my files" app, shown on its own so you can see exactly how it ranks things.

Download the four kit files into a new folder. Save search.py, scale_sqlite.py and requirements.txt in the folder itself, and notes.md inside a sub-folder called corpus. Then set it up and run the headline comparison:

cd $HOME\Documents
mkdir semantic-search; cd semantic-search
# put search.py, scale_sqlite.py and requirements.txt here, and notes.md in a corpus\ sub-folder
uv venv --python 3.13
uv pip install -r requirements.txt
uv run search.py build
uv run search.py compare "how do I protect my laptop on public wifi"

cd ~/Documents
mkdir semantic-search && cd semantic-search
# put search.py, scale_sqlite.py and requirements.txt here, and notes.md in a corpus/ sub-folder
uv venv --python 3.13
uv pip install -r requirements.txt
uv run search.py build
uv run search.py compare "how do I protect my laptop on public wifi"

build cuts the notes into chunks and turns each one into numbers (the first run downloads the 90MB model, so give it a minute). compare then runs the same question two ways, keyword first, meaning second:

KEYWORD  "how do I protect my laptop on public wifi"
  1.   1.601  notes.md #7  ## Why a laptop feels slow Most of the time the disk is the bottleneck, not the processor....
  2.   0.000  notes.md #1  # Field notes: staying private and keeping your computer working FICTIONAL SAMPLE DOCUMENT...
  3.   0.000  notes.md #3  ## Password managers A password manager invents a long random secret for every account and...

MEANING  "how do I protect my laptop on public wifi"
  1.   0.425  notes.md #2  ## Tunnelling your traffic on an untrusted network A virtual private network routes everyt...
  2.   0.139  notes.md #3  ## Password managers A password manager invents a long random secret for every account and...
  3.   0.097  notes.md #1  # Field notes: staying private and keeping your computer working FICTIONAL SAMPLE DOCUMENT...

That is the whole point of the lesson in one screen. Keyword search put the note titled "Why a laptop feels slow" on top, because it contains the word "laptop", and then scored 0.000 for everything else: it could not see the VPN note at all. Meaning search put the VPN note ("Tunnelling your traffic on an untrusted network") first, even though that note never says wifi, laptop or protect. The rest of the lesson takes this apart so you can tune it and point it at your own notes.