org-semantic — search a tree of org-mode notes by meaning or by words

None of which helps if what you want is to see it work before deciding. Any public collection of org files will do, and these three need nothing installed — least of all org-roam, whose vaults are plain org files with :ID: properties and #+filetags: that org-semantic reads on their own:

The first is the one to reach for. Point the vault straight at the clone; the PDFs and LaTeX beside the notes are simply not .org, so nothing looks at them. Say that it is bilingual, or nothing is classified and lang: has nothing to narrow by — one language declared is the answer for every note:

git clone --depth 1 https://github.com/denialbb/braindump
echo '{ "languages": ["en-US", "it-IT"] }' > bilingual.json

org-semantic index braindump/roam --lexical --config bilingual.json  # 2863 chunks in 0.5s
org-semantic search braindump/roam "algoritmo lang:it-IT" --lexical

The search needs no --config of its own: a policy is remembered once given, so later runs against that vault answer under it.

The semantic index over the same notes is around a minute on e5-small, which is the model to pick there — an English-only one will rank the Italian half badly. Then ask it something in English that the notes answer in Italian, which is the thing no word search can do:

org-semantic index braindump/roam --model e5-small
org-semantic search braindump/roam "what happens when a process is scheduled off the cpu"

One note in that vault is UTF-16 rather than UTF-8, so index names it and carries on without it. That is the tool saying what it left out, not a bad clone.

A binary someone else compiled is a binary you are trusting on their word, and not everyone wants to. Every release carries its own source archive for that reason — org-semantic-<version>-src.tar.gz, with its hash in the same SHA256SUMS as the binaries — so you can verify what you downloaded, read it, and build it:

V=0.3.0
BASE=https://github.com/alberti42/org-semantic/releases/download/v$V
curl -LO $BASE/org-semantic-$V-src.tar.gz
curl -LO $BASE/SHA256SUMS

# `shasum -a 256' on macOS, `sha256sum' on Linux; both read the same file.
grep "org-semantic-$V-src.tar.gz" SHA256SUMS | shasum -a 256 -c -

tar xzf org-semantic-$V-src.tar.gz && cd org-semantic-$V
cargo build --release          # target/release/org-semantic
make test                      # optional, and it all runs from the archive

Then put target/release/org-semantic on your PATH, or copy it into org-semantic-install-directory where Emacs finds it with nothing configured.

Pin this archive rather than the Source code (tar.gz) GitHub attaches by itself. GitHub generates that one on demand and has changed how it compresses it before, moving the checksum of archives already published and breaking everyone who had pinned one. Ours is built with git archive and gzip -n, so a given tag is the same bytes for ever.

It holds what builds and tests the project, and not the whole repository: the screenshots and the vendored HTML theme are left out, which is also what keeps it MIT throughout. The two test suites run from it unchanged — which is worth knowing, since reading the code and then running its tests is the point of building this way.

There is no Intel macOS build, and cargo build will not make you one. The ONNX Runtime this links against is fetched as a prebuilt library by ort, and ort publishes none for x86_64-apple-darwin. The build stops with:

error: ort-sys@2.0.0-rc.13: no prebuilt binaries available for target x86_64-apple-darwin

Rosetta is not a way round it — it translates x86₆₄ binaries, and there is no x86₆₄ binary to translate.

There is a workaround, which is not tested here and is offered as a starting point rather than a supported path: install ONNX Runtime yourself and tell ort to link against it instead of downloading one.

brew install onnxruntime
ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
ORT_PREFER_DYNAMIC_LINK=1 \
  cargo build --release

Two things to know before you try it. ORT_LIB_LOCATION must point at the lib/ subdirectory and not at the prefix, or you get a different and more confusing error about not being able to link to the build; and ORT_PREFER_DYNAMIC_LINK=1 is required, since without it ort still attempts a static link that the Homebrew keg does not provide.

What you get is no longer one self-contained binary. It loads libonnxruntime.dylib from wherever Homebrew put it, so it breaks if that is upgraded or removed, and it is not something you can copy to another machine. That is the reason this is a hint and not the build we ship.

The recipe comes from headroomlabs-ai/headroom#1797, which hit the same wall. Note that their version also sets ORT_STRATEGY=system, which does nothing here: that variable belonged to an older ort and the version pinned in this project no longer reads it. ORT_LIB_LOCATION is what does the work.

The package lives in lisp/. Put it on your load-path and tell it where the binary is, if it is not already on your PATH:

(add-to-list 'load-path "/path/to/org-semantic/lisp")
(require 'org-semantic-results)
(setq org-semantic-executable "/path/to/org-semantic")

;; Optional, and explained below: reindex a vault as its notes are saved, so
;; that a note written now is searchable a couple of seconds later rather than
;; after the next `M-x org-semantic-reindex'.
(org-semantic-auto-reindex-mode 1)

Or with use-package, which also gives somewhere to put the keys. There are no default global bindings and there will not be: C-c followed by a plain letter is reserved for you rather than for a package, so a recommendation is as far as this can go.

(use-package org-semantic-results
  :load-path "/path/to/org-semantic/lisp"
  :custom (org-semantic-executable "/path/to/org-semantic")
  :bind (("C-c n s" . org-semantic-find)
         ("C-c n S" . org-semantic-find-at-point)
         ("C-c n R" . org-semantic-reindex))
  ;; Optional, and one of the nicer things here: each passage is previewed
  ;; in its note as point reaches it, so `n' and `p' read the vault rather
  ;; than a list of it.  `f' in the results buffer toggles it either way.
  :hook (org-semantic-results-mode . next-error-follow-minor-mode)
  ;; Also optional: keep the indexes up to date as notes are saved, so
  ;; `C-c n R' is for what changed outside Emacs rather than for every edit.
  :init (org-semantic-auto-reindex-mode 1))

s searches, S searches for the region or the symbol at point, and R indexes. The C-c n prefix is what org-roam's own manual suggests for its commands, and these three compose with it rather than colliding — org-roam uses f, i, l, g, c and j, and none of those. Everything else — org-semantic-cancel, org-semantic-show-status, org-semantic-show-memory, org-semantic-restart, org-semantic-quit — is rare enough to leave on M-x.

That last line is the one worth explaining, since it is off by default and easy never to find. next-error-follow-minor-mode shows each passage in its note as point arrives, without selecting that window — so the list keeps point and the note keeps up. Without use-package it is the same one hook: (add-hook 'org-semantic-results-mode-hook #'next-error-follow-minor-mode). Called from a hook a minor mode enables rather than toggling, which is why this reads as it does and f still toggles.

org-semantic-auto-reindex-mode is the other optional line, and the situation it is for is this one: you write up a meeting, search for it twenty minutes later, and it is not there — because the index is from this morning and nothing has told it otherwise. With the mode on, saving a note reindexes the vault it belongs to two seconds after saving stops, and that question stops arising.

The wait is a debounce — org-semantic-auto-reindex-delay — so writing fifty notes with save-some-buffers costs one run rather than fifty, and a save landing while a run is going waits for it rather than being refused. A run of one changed note is about 70 ms: the note is re-chunked, and only the passages whose text actually moved are embedded again.

It says nothing when it works, which is ~org-semantic-auto-reindex-quietly=; set it to nil to see each run reported. Failures are not quiet — said once per vault, since an automatic feature that has stopped working looks exactly like one that is working.

Two things it deliberately will not do. It will not build an index that does not exist: that is minutes of embedding and a decision, so a vault with nothing built is named once, with M-x org-semantic-reindex as the thing to press. And it does not see notes that changed outside Emacs — a sync, a git pull, a rename in Dired — because a save is all it hears about.

Something else in your configuration may hear about those: a file watcher, or another package indexing the same notes and watching them for its own reasons. It can pass that on with org-semantic-auto-reindex-touch, and the change is then picked up as a save would be:

(org-semantic-auto-reindex-touch "/Users/you/notes")

It takes a vault and not a file, because a run is a vault-wide incremental scan: it needs to know that something changed and not what — which is also why a rename is caught by the arrival of the new name alone, the same scan finding the old one gone. Called with no argument it asks the current buffer, which is rarely what a watcher's callback wants. It is as cheap to over-call as a save: fifty touches inside the debounce are one run.

It does not need the mode, and is not disabled by it being off. The mode is one trigger — saves — and not the policy, so a configuration whose watcher already reports saves uses the touch alone and leaves the mode off; one that has no watcher uses the mode alone. Both together is allowed and costs one run, since they share the debounce. What the touch takes from the mode is its manners: the same delay, the same silence when it works, and the same refusal to build an index that does not exist.

So there are two levels of keeping current, and the first is enough for most people:

• org-semantic-auto-reindex-mode, above. Built in, one line, nothing else installed — and it hears about every note you write, which is most of what changes.
• A watcher, plus the touch. For the rest: a note renamed or deleted in Dired, a git pull, a folder arriving from Dropbox. Something has to be watching the filesystem, and org-semantic deliberately is not — serve has no lifetime beyond the editor that started it, so a watcher belongs on the Emacs side where it can be switched off.

The watcher can be Emacs's own filenotify, which is enough in a dozen lines. Watch the vault, touch on anything that looks like a note:

(require 'filenotify)

(defvar my/notes "/Users/you/notes")

(file-notify-add-watch
 my/notes '(change)
 (lambda (event)
   (when (and (memq (nth 1 event) '(created changed deleted renamed))
              (string-suffix-p ".org" (or (nth 2 event) "")))
     (org-semantic-auto-reindex-touch my/notes))))

That watches one directory and not its subdirectories, which is the honest limit of a short example rather than a simplification of it: watching a tree means walking it, adding a watch per directory, and adding another for every directory that appears later. Emacs gives you no recursive watch, and writing one properly is a small package in itself.

Which is the argument for vulpea, the companion worth naming here: if you keep notes in one, that work is already done. vulpea maintains its own database of what each note is — its :ID:, its title, its tags, what links to it — and with vulpea-db-autosync-mode on it watches the whole tree, subdirectories and newly created ones included, to keep that database current. Those watches see exactly what a save hook cannot. The two indexes then answer different halves of one question over one tree, and neither knows about the other's directory: .vulpea/ and .org-semantic/ sit side by side in the vault.

Hearing about what those watches found is one add-hook and no advice. vulpea-db-updated-functions is vulpea's single data-changed signal: it is called with (PATH COUNT) once per file whose database content changed, after the write or delete transaction commits — for an edit, for a note arriving, and, with a count of 0, for a removal.

(add-hook 'vulpea-db-updated-functions
          (lambda (_path _count)
            (org-semantic-auto-reindex-touch "/Users/you/notes")))

Both arguments are ignored on purpose. A reindex is a vault-wide incremental scan, so which file changed does not matter — and neither does the count, since 0 (the notes were dropped) and 3 (they were written) call for the identical scan. Committing first is what makes this better than an after-save-hook, which fires before vulpea's own update.

It needs a vulpea newer than 2.7.0: the hook landed in August 2026, after that release. On an older one the add-hook quietly succeeds and is never called, so that is the first thing to check if changes stop reaching the index. vulpea also reports per file, so its own first sync of a thousand notes fires this a thousand times — the debounce makes that one run.

Failing both, M-x org-semantic-reindex remains what catches up. Being behind costs nothing: a search says so when the index is a version old.

A passage is org text, so it is shown with org's own faces: emphasis, verbatim, headings, block markers and links all look as they do in the note. That is org-semantic-results-fontify, on by default, and it works by inserting the passage into a hidden org-mode buffer and copying the faces back — the trick magit uses for diffs.

Only faces are copied, and the characters are never touched. The nth line of a passage is line startLine + n of the note, which is what makes each line addressable and one day writable, so nothing here may replace or move text. Org's own keymap, invisible and display properties are therefore left behind.

Links are the exception. With org-link-descriptive on — the default, and what M-x org-toggle-link-display toggles — a link shows its description and its brackets are hidden, as in a note. That hiding is ours rather than org's: org 9.8 hides links through org-fold-core, which has to be initialised in the buffer doing the hiding, and a list of passages should not have to become an org buffer for it. The characters are all still there, since invisible hides rather than deletes; a link split across two lines is left alone, because hiding part of one would leave a line nobody can point at.

It costs about 0.8 ms a passage against 0.1 ms without, and needs org loaded, which it will be. Set the option to nil for plain text.

A fragment of a document is what org is being asked to fontify, and three things that might spoil that do not. Folding: the whole passage is fontified before its tail is hidden, so a hidden #+end_src still counts. Emphasis: a paragraph too long for one passage gives every piece of itself the whole paragraph's span, so what you see is always a complete paragraph. And blocks: a block is one paragraph however many blank lines are in it, and its #+begin_ line is inside the span, so a passage never shows one marker without the other. That last one took two fixes to be true.

One setting says which vault your notes are in. With a single vault that is the whole of it:

(setq org-semantic-vault-root "~/notes")

Every buffer then belongs to that vault, including the ones that are nowhere in particular — *scratch*, an agenda — so a search works from wherever you happen to be.

With several vaults, each one says which directory it is, in its own .dir-locals.el, and that overrides the setting for the notes inside it:

((nil . ((org-semantic-vault-root . t))))

t means "the directory this declaration came from"; a string names a subdirectory of it, for notes that live below the project that declares them. Emacs applies directory-local variables when a file is opened — and when Dired opens the directory — so a note in a declared vault arrives already knowing which one it is, before anything has been indexed. Leave the global setting nil, or point it at whichever vault should answer from everywhere else.

Nothing looks for the .org-semantic directory to work out where a vault is: it holds derived data, its place is not the vault's to promise, and a vault found that way would be found on one machine and not on another that keeps its indexes elsewhere — answering with a different vault rather than with none.

When the answer has to be worked out rather than written down, the global setting may be a function of no arguments instead. That is for the case where something else in your configuration already tracks which collection of notes is current — switching between vaults, or opening one per project — so that a fixed directory is the wrong answer and the right one changes during the session:

(setq org-semantic-vault-root
      (lambda () (and vulpea-vault-directory
                      (expand-file-name vulpea-vault-directory))))

Returning nil means there is no vault here, which is a complete answer — a search then says so rather than guessing. Keep it to a variable lookup: it is asked on every question about a vault, including once per save when org-semantic-auto-reindex-mode is on. An error in it is left to signal, since it is your code and a vault that cannot be worked out is worth seeing.

A function is legal only as the global value, never in a .dir-locals.el: a directory you merely visit could otherwise run whatever it liked, so Emacs refuses to apply one and org-semantic ignores it if it is marked safe by hand. A declaration says which directory a vault is; how to work one out is a decision for your own configuration.

Then M-x org-semantic-find from any note — or from Dired, or the agenda — searches the vault that note belongs to and shows what came back. The prompt says which ranking will answer — Semantic search for: or Lexical search for: — and M-s and M-l change it while the query is being typed, carrying across whatever has been typed so far. They are the same two keys the results buffer takes. One C-u asks which ranking to start from — the prompt there names the index each one reads, since they are two indexes and not two orderings of one — and two C-u ask about the length of the list as well:

org-semantic: semantic search for "vacuum bakeout procedure"
~/notes  ·  k=8 notes  ·  3 passages per note
6 notes, 11 passages in 0.31 s

Vacuum system  ·  2 passages
  0.780 (+2.4σ)  lab / vacuum.org > Bakeout > Turbo pump > lines 142–144 :lab:vac:
    The turbo pump was baked out at 120 °C for 48 h before the
    chamber was vented.  Pressure after the bake settled at
    2e-10 mbar, which is the best we have seen on this chamber.

  0.712 (+1.9σ)  lines 181–182
    A second bake was needed after the viewport swap: the copper
    gasket had been reused once too often.

A hit's address reads left to right and every part of it is a link: the directory opens in Dired, the note opens at its top, the section goes to its heading, and the two line numbers go to where the passage starts and where it ends — either end being somewhere you might want to be, the top to read it and the bottom to carry on past it. A one-line passage says line 8 instead, and so does one the note has outgrown, which has no span left to trust.

Only the leading passage of a section carries the whole address; the ones after it name their lines alone, since the path is unchanged and only the lines have moved.

A passage is shown as the note's own lines, in order and unaltered, so RET goes to the line under point rather than to the top of the section — which matters, since a section can run to hundreds of lines. It is wired into next-error, so M-g M-n walks the hits from anywhere.

The two pairs are two different questions: k and K widen the list, + and - deepen the notes already in it. A vault kept in a few large files answers a large k with very few hits until the second is raised too — see Vaults kept in a few large files.

A search sent while an index is running is answered from the version committed before it, and the header says so. Nothing is lost; the list is a moment behind.

If the index a search needs does not exist, the buffer says so and offers to build it — as something to press, rather than as a question asked while you were typing somewhere else. The same goes for an index whose layout is too old to read, and for a policy that has drifted since the index was built.

A prefix argument to M-x org-semantic-find asks for the ranking and the two limits instead of taking them from the settings. M-x org-semantic-reindex indexes the current vault from anywhere: plain trusts each note's timestamp, C-u re-reads and re-hashes every note, and C-u C-u rebuilds from scratch.

Nothing about org-semantic is Emacs-specific: search --json returns the hits as data rather than prose, and serve speaks JSON-RPC over a pipe, so any program that can start a process and write to its standard input can drive it — another editor, a script, or an agent doing retrieval before it answers.

serve keeps the process alive, so a query costs milliseconds instead of a model load:

$ org-semantic serve        # JSON-RPC 2.0 over stdio, LSP framing

That gap is the whole reason for a resident process: 8 ms is a keystroke, 1.6 s is not. The first figure is the model being read from disk and is paid once per process, so it scales with the model — bge-small-en takes about 300 ms where e5-small takes 1.6 s — while the warm figures do not depend on it.

Messages are framed the way LSP frames them, with a Content-Length header. That choice is for the client's sake: Emacs ships jsonrpc.el — the library Eglot runs on — so the editor needs no protocol code of its own. It starts the process with make-process, and request/response correlation and notifications come for free. No socket, no port, no authentication, and the server lives exactly as long as the editor does.

A session opens with initialize and the initialized notification, as LSP sessions do; jsonrpc.el and Eglot do this for you. Nothing is negotiated there — the package and the binary ship from one repository — but it is where the server says which version it is.

An index runs on a thread of its own, so the server keeps answering while it works. A search sent during a reindex is answered from the version committed before it, and marked indexing: true so you can say so in the UI. It is also slower — see below.

One server can hold several vaults, and the embedding model is loaded once for all of them. Nothing about embedding a query depends on which vault asked, so the weights are shared; what each vault adds is its own chunk table and vectors, a couple of megabytes for a small vault and about ten for a large one. Measured with the small English model: one vault costs 253 MB, three cost 256 MB.

When you are finished with a vault — the last buffer visiting it is gone, say — send close with its path. Its table and vectors are dropped, and the model with them if no other vault is using it.

What that buys is a ceiling rather than a refund. Opening and closing three vaults five times over settles at about 262 MB and stays there, so nothing accumulates; but the memory comes back to the system on the runtime's own schedule, which is unpredictable — sometimes seconds, sometimes not at the moment you looked. Do not wait for the number to fall.

A ceiling is the more useful thing, though, and it is why one server for all your vaults is the arrangement to prefer. One server per vault would give every byte back the moment it exited, but it pays for a whole model each time: two vaults open at once cost about 507 MB that way against 256 MB shared, three about 760 MB against the same 256 MB. Only if you visit vaults strictly one at a time do the two come out level. The protocol is identical either way, so this is the client's choice to make — but memory is not the reason to split.

Methods:

Both modalities take the same request and return the same shape, so an editor can offer one command with a toggle and never branch on the reply. Each hit carries an absolute file, the heading path, the headingLine, the passage's own startLine=/=endLine, and the :ID: when there is one.

The address of a hit is path and headingLine, and there is no second way to go. path is relative to the vault root — the directory holding .org-semantic — so it names the note uniquely and survives the whole tree being moved; file is the same thing made absolute, for convenience. headingLine is a line in the real file, counted over the raw text: the parser drops drawers, keywords and block bodies from what it indexes, but never from what it counts, so a fifteen line source block collapsed to [src bash] shifts nothing.

That line is where the heading owning the passage starts — or line 1 for text that sits above every heading. So a client opens the file and goes to the line, and it is on the section. There is nothing to resolve, match or choose: org supplies the subtree, the properties and anything else from the buffer. This holds for both modalities.

heading is for showing a hit in a result list, and is part of what was embedded; it is not a navigation anchor. id is an extra for the vaults that carry them.

text is the passage, read from the note when you search rather than stored in the index — so it is the real document, code blocks and tables included, not the filtered version that was embedded. startLine and endLine give the same range, for a client that would rather read or highlight it itself. A note that has moved since it was indexed yields an empty text rather than stale lines.

One consequence of headingLine naming the section: a section long enough to be divided yields several passages reporting the same path and headingLine. They remain distinct hits, and startLine=/=endLine separate them — so you can jump to the passage that matched rather than to the top of the section it sits in.

If you would rather see one result per section, --merge-by-section (mergeBySection over JSON-RPC) folds them: the section is scored by its best passage and spans all of them. It is off by default because the spans make each passage reachable on its own, and hiding the one that matched behind the top of its section throws that away. Which you want is a question about your result list, so it is the client's to answer.

One trap if you build an org link to the heading rather than jumping yourself: org-link-search prompts "Create new heading?" when it misses, which over emacsclient blocks every frame. Bind org-link-search-must-match-exact-headline to nil and pass the heading text unescaped.

k and perFile are the two caps described under vaults kept in a few large files; an editor showing such a vault raises the second.

An empty query returns no hits rather than an error, so it is safe to send on every keystroke; debouncing is the editor's policy, not the server's.

config is optional on search, and when present it is checked against what the index was built under — see what gets indexed for what that is for and what a client should do with the error. Leaving it out searches whatever is there, which is what the CLI does.

This tool was built so that you can find your own notes. That is the point of it, and everything above is about that. What follows is an extension some people will want, and nothing depends on it.

An AI assistant answering a question about your work has two options. It can answer from what it learnt during training — which knows nothing of your notes — or it can first go and read the relevant passages from them, and answer with those in front of it. The second is called retrieval-augmented generation, or RAG: retrieve first, then generate. The retrieval half is exactly what org-semantic does, and the assistant needs no model of its own to use it, since --json hands it the passages as data.

The awkward part is usually teaching the assistant when to search and how to read what comes back. A short instruction file does that, and one is included:

cp -R skills/org-semantic ~/.claude/skills/     # Claude Code

It tells the agent which of the two searches suits which question, that a surname is invisible to the semantic index and a paraphrase invisible to the lexical one, how to narrow with tag: and dir:, that z above about 2σ is a real match and below 1σ is not, that a lexical score means only "more than the ones below it", and that it should ask before spending minutes on an index. The file is plain Markdown — if your assistant takes instructions in some other form, it reads as documentation and translates easily.

Your notes stay where they are throughout. org-semantic never modifies them, and nothing leaves the machine: the embedding model runs locally, and the only thing the assistant sees is the passages it asked for.

Search prints 0.883 (+2.1σ). The first number is the similarity itself; the second says how far above the ordinary background it stands. Read the second one. (--json carries them as score and z.)

The reason is that these models do not spread their vectors over the whole space: they point in nearly the same direction, whatever the text. Take two passages with nothing to do with each other and they still score 0.563 under bge-small-en, or 0.801 under e5-small. So most of any score is a fixed background common to everything, which differs from one model to the next and tells you nothing about the hit in front of you:

The σ figure subtracts that background and measures what is left against how much scores normally vary — so +2.1σ means "well clear of the noise" in either model. The two disagree by 0.13 on the raw scale and land in the same place on this one. It also catches weak hits that look respectable: 0.826 under E5 is only +0.7σ, barely above the background.

The background is measured from the vectors themselves, by sampling 20,000 unrelated pairs when an index is loaded — about 37 ms, then kept in memory. Measuring rather than storing it means it can never disagree with the vectors it describes.

Lexical scores are left as they are, and carry no σ. BM25 has no fixed range: a score is a sum over the matched terms, weighted by how rare each is in the corpus and damped by document length, so it rises with both the rarity of what you asked for and the number of terms that hit. On the same vault, the top hit for atom scores 11.9, for LSCOLORS 21.6, and for Rabi oscillations 29.2 — which says nothing about which is the better answer to its own question.

So a BM25 number means only "more than the ones below it". It is not comparable between queries, between vaults, or with anything on the semantic side, and there is no noise floor to standardise it against — hence z: null for lexical hits in --json. Read the ordering, not the value.

Within a single note the passages show raw scores alone: they share the same offset, so the only comparison that matters there is between them.

No threshold is ever applied. z is presentation; what to do with it is the caller's business.

$ org-semantic models
name             dim  trained on
bge-small-en     384  English  (default)
bge-base-en      768  English
bge-large-en    1024  English
e5-small         384  100 languages
e5-base          768  100 languages
e5-large        1024  100 languages

org-semantic index ~/notes --model e5-small --full

Pick a multilingual model if your notes are not all in one language. With e5-small, an English query finds the German note it never mentions:

$ org-semantic search ~/notes "why do atoms get lost from the trap"
0.891  Trap physics            ← English
0.838  Atome in der Falle      ← German, never using those words
0.736  Ricetta                 ← unrelated

Each model keeps its own index, so you can build several and compare them without re-embedding for the one you already had:

$ org-semantic models ~/notes
name             dim  trained on      status
bge-small-en     384  English         built default
e5-small         384  100 languages   built
…

$ org-semantic search ~/notes "why do atoms get lost from the trap" --model e5-small

search --model selects between built indexes; it cannot impose a model on vectors built by another, because a query must be embedded by whatever embedded the corpus. With one index built it is used automatically; with several the default wins unless you name one. Naming a model you have not built is an error listing what you have.

Scores are only comparable within one model. BGE spreads its cosines widely (0.37–0.74 above); E5 compresses everything into roughly 0.73–0.93. Only the ranking carries meaning, never the absolute number.

fastembed offers forty models; these are the ones whose prefixes are known here. Each family expects its own — BGE prefixes only the query, E5 prefixes the indexed passage too — and the wrong convention costs retrieval quality silently, so a model is listed only once its prefixes have been checked. bge-small-en and e5-small have been run end-to-end; the base and large variants inherit their family's prefixes and have not been exercised here.

index follows the same convention as search: bare it builds the semantic index, --lexical builds the word index, and --both does the two in one command.

org-semantic index ~/notes                 # embeddings      ~200 s / 951 notes
org-semantic index ~/notes --lexical       # BM25             1.3 s
org-semantic index ~/notes --both          # both

languages and fold_diacritics affect only the lexical index, which is the only one that has a use for a language: they choose the stemmer.

They are separate artifacts with separate records of what they have seen, so each re-run only reads the notes that index is behind on. Both are incremental by default; --full rebuilds from scratch and --rehash re-reads every note, ignoring timestamps.

Embedding takes minutes and a 129 MB model; the lexical index takes a second and nothing but the notes. So refreshing keyword search after editing a few notes costs a second, and changing the folding or your language list rebuilds only the lexical index — those settings are hashed per index.

Without a flag, search ranks by meaning: your query is turned into a vector and compared against the vector of every passage.

With --lexical it ranks by words, using tantivy. That is ordinary keyword search, of the kind a search engine does: it keeps a list of which words appear where, and ranks a passage by BM25, the standard measure for this — rarer words count for more, a word appearing twice counts for less than twice, and long passages are not rewarded for their length. Words are reduced to their stem first, in the language of the note, so Sprachen finds Sprache.

It comes with a real query language — phrases, AND=/=OR=/=NOT, parentheses and field boosts — following tantivy's query syntax in full. A malformed query is reported as a syntax error rather than silently matching nothing.

Every term must match by default, since matching any of them would rank anything merely containing "oscillations" for the query "Rabi oscillations"; --any asks for that looser match when you want it.

One command, but never one merged result list: a phrase or a boolean means nothing to an embedding, so a fused list would mix hits that honoured your query with hits that could not.

The difference is not academic. Searching your notes for the surname Gehm:

$ org-semantic search ~/notes Gehm --lexical
13.187  2024-08-27 Heating rate in optical traps      ← the note citing Gehm 1998

$ org-semantic search ~/notes Gehm
0.819 (+0.5σ)  01 Deutsche Wörter 2024                  ← noise

A surname carries no meaning for an embedding model. Equally, why do the atoms heat up and get lost from the trap finds the right passage semantically and nothing at all lexically, since none of those words appear in it.

Plenty of people keep every project in one projects.org and every meeting in one meetings.org, rather than a file per note. org-semantic is built for that as much as for a file per note, but there is one number you will want to change.

A result is an outline node, not a file. A hit inside a four-thousand-line meetings.org is reported as the heading path that contains it, at the line where it starts, with the :ID: of the nearest enclosing node — so it points at the meeting, not at the file the meeting happens to live in.

You do not need :ID: for any of this. path, heading and line locate a hit on their own, and they stay correct: rename a note and the next index run sees the old path gone and the new one arrived, so the paths are rewritten — for free if the note has a #+title:, since nothing it embedded changed. Org itself only creates an :ID: when you ask (org-id-get-create, org-attach, or a package like org-roam), so most vaults have few, and a tool that hinged on them would work well for some people and badly for everyone else.

id is therefore a bonus rather than the handle: present, it is the nearest enclosing node's, and org can resolve it without consulting our index at all — useful when the index has not caught up with an edit. Absent, nothing is lost.

$ org-semantic search ~/notes "who is fixing the cryostat shaking"
0.883 (+2.4σ)  Meetings > Meeting 099 — cryostat vibration > Decisions
       meetings.org:1474
       id:mtg-0099-…

Two numbers bound the list, because two different things can crowd it out:

Both are applied to one list ranked by score, walked from the top. A note joins the list the moment its best passage comes up, so the k notes you get are the k notes with the highest-scoring single passage — nothing that was left out has a passage better than the best of one that got in. The passage cap then counts what has been taken from that note across all of its sections: three is three whether they come from one section or three, and a note with five sections each holding a hit shows its best three.

The consequence is worth knowing, because it is the one thing here that is not obvious: the list is not the best passages in the vault. A note already on the list may contribute a second or third passage that scores below the best passage of a note that was shut out. With k 2:

0.91  note A, passage 1     A joins the list
0.88  note B, passage 1     B joins the list
0.72  note A, passage 2     taken --- A has room
0.70  note A, passage 3     taken --- A is now full
0.69  note C, passage 1     dropped --- no room for a third note

That 0.69 loses to a 0.70 from a note you can already see, and that is the point of having two caps rather than one: without the note cap, three large files answer k 50 with everything they have and you never reach the fourth note. Raise k to see more places; raise the passage cap to go deeper into the places you already have.

The defaults suit a vault of one note per file, where a note matching in five places would otherwise spend the whole list on itself. Keep your year of meetings in a single file and that same cap becomes the thing in your way: every hit comes from one file, so three is all you will ever see, and raising k will not help — it counts files, and you have one.

# Three files, everything in them: ask for depth, not for more files.
org-semantic search ~/notes "cryostat vibration" --per-file 25

Nothing about indexing needs changing for large files. Notes are split at headings regardless of the file they sit in, and re-indexing costs what you actually edited: adding one meeting to a file of three hundred re-embeds that one meeting. Inserting it at the top, which moves every line number below it, still re-embeds only the one — a line is recorded with the passage but is not part of what was embedded.

A query may carry predicates, which narrow which chunks are searched before anything is embedded:

org-semantic search ~/notes 'tag:Literature estimating eigenvalues on hardware'
org-semantic search ~/notes 'dir:"01 Daily notes" atom sorting in a tweezer array'
org-semantic search ~/notes '-tag:Deutschlernen -tag:Computer atom heating'

Every predicate negates, with a leading -. Excluding a directory excludes everything under it, so -dir:archive also drops archive/2024/. A query may be nothing but exclusions — -todo:DONE on its own is every passage that is not done.

Quote a value containing spaces, and quote it whole: dir:"03 Literature review/Reviewed in 2024". Unquoted, the words after the first fall out as free text and the filter matches nothing. Directories are matched by whole component, so dir:"03 Lit" is not an abbreviation for 03 Literature review — it matches nothing at all.

A dir: is absolute when it starts with / or ~, and relative to the vault otherwise — the rule expand-file-name uses, so it is the one Emacs already taught you. All four of these name the same directory, which means a path pasted out of Dired works as it stands:

dir:"08 Conferences"                      # relative to the vault
dir:"./08 Conferences"                    # the same
dir:"/Users/me/notes/08 Conferences"      # spelled in full
dir:"~/notes/08 Conferences"              # and with a home directory

An absolute dir: outside the vault is an error rather than a search that finds nothing — "nothing matched" and "that directory is not in this collection" are different answers, and only one of them would be true.

Two things are decided by policy: which subtrees are indexed at all, and what happens to blocks.

Subtrees tagged :noexport: or :ARCHIVE: are left out — org's own markers for "not for consumption" and "put this away". Both inherit, so the rule covers a whole subtree, children included.

Blocks are treated differently by each index. Code embedded as prose pollutes a semantic search — a shell snippet lands near queries it has nothing to do with — but exact match is precisely what you want when hunting a flag or a function name. So by default the body of a src block is not embedded, and is searchable by word:

$ org-semantic chunks ~/notes "smb" | tail -1
    tail: "…autofs will pick it up.\n\n[src bash]\n\nAfterwards the volume survives…"

$ org-semantic chunks ~/notes "smb" --lexical | tail -1
    tail: "…mount_smbfs //user@server/share /Volumes/share -o nobrowse\n\nAfterwards…"

"placeholder" is why the first one still reads properly. Dropping the block outright would glue the paragraph before it to the one after — an adjacency the note never had — and lose the fact that a snippet was there at all, which is part of what the section is about. [src bash] keeps both, without forty lines of shell drowning the prose around it.

The whole policy lives in a file you own, named with --config. Copy config.example.json — it is exactly the defaults — and edit it:

{
  "languages": ["en-US", "de-DE"],
  "fold_diacritics": false,
  "blocks": {
    "src":     { "semantic": "placeholder", "lexical": true },
    "example": { "semantic": "placeholder", "lexical": true },
    "results": { "semantic": false,         "lexical": true },
    "quote":   { "semantic": true,          "lexical": true },
    "verse":   { "semantic": true,          "lexical": true }
  },
  "planning_line": { "semantic": false, "lexical": true },
  "chunk": { "semantic_tokens": 350, "lexical_chars": 1500 },
  "exclude_tagged": ["noexport", "ARCHIVE"],
  "todo_keywords": ["TODO", "DONE"]
}

languages and fold_diacritics configure the lexical index, which is the only one that stems anything — see Languages below. semantic takes true (embed it), false (drop it) or "placeholder"; lexical is a plain boolean, since labelling something in an exact-match index would only make [src] a searchable word. Babel #+RESULTS: and bare =: = fixed-width lines count as output, not prose. Quote and verse stay in both — they are prose someone chose to set off, not machine output.

chunk is how large a passage may get, and the two numbers are in different units on purpose. An embedding has a hard context limit, so the semantic budget is counted in the model's own tokens. Counting characters instead would be a proxy that drifts with the content: chars-per-token runs about 2 in LaTeX-heavy notes and 4 in prose, and German compounds tokenize worse than English, so one figure in characters means different amounts of context in different notes of the same vault — and how coarse a hit is should not depend on which language a note happens to be in.

BM25 has no context limit, and the word index deliberately loads no tokenizer — that is what keeps index --lexical to a second's work rather than a model download. Its budget is therefore in characters, which it can measure exactly, rather than an approximation of tokens it has no way to count.

The heading is prepended to every passage before it is embedded, so it comes out of the semantic budget once. Raise semantic_tokens for more context per hit and fewer, coarser hits; lower it for finer ones and a larger index.

planning_line is a heading's DEADLINE: / SCHEDULED: / CLOSED: line, and is split by index for the same reason Babel output is. A date carries almost nothing an embedding can use, and in a project file where nearly every heading has one it would open most passages with the same shape of noise — so it is dropped there. Looking one up by word is an ordinary thing to want, though, so the lexical index keeps it. Turn either round if your notes disagree.

Only the real thing is taken: org counts a planning line only on the line immediately after the heading and before the property drawer, and matches the keywords case-sensitively. A paragraph that opens "Deadline: we agreed on the first" is prose and stays, in both indexes.

todo_keywords is this vault's org-todo-keywords. It decides what a heading says: a keyword org knows is cut off the front of the title, and one it does not know stays there and is embedded with it. The default is org's own default and nothing more — TODO and DONE — so under it * NEXT Rewire the trap is a heading titled "NEXT Rewire the trap", which is exactly what your Emacs shows you until you configure NEXT. If you have configured it, say so here:

"todo_keywords": ["TODO", "NEXT", "WAITING", "DONE", "CANCELLED"]

Order does not matter — org's sequence order drives cycling, which nothing here does, so this is read as a set. Individual files may still add their own with #+TODO:, #+SEQ_TODO: or #+TYP_TODO:, including the fast-selection keys and logging specs org allows (WAIT(w@/!)), which are stripped down to the keyword.

Those values are the defaults, so the block above describes what you get with no config at all.

cp config.example.json ~/notes/indexing.json     # then edit it
org-semantic index ~/notes --both --config ~/notes/indexing.json

The policy is sticky. Once given it is cached, so later runs need not repeat --config — forgetting it is safe, which is what makes a sticky setting tolerable. It is compared by meaning, not by bytes: key order, whitespace and duplicates all hash the same, and a file that merely restates the defaults is indistinguishable from no file at all.

Changing it is refused, not obeyed. A config can change without you doing anything — a git pull brings someone else's edit — and re-embedding a corpus takes minutes, so the tool says what moved and waits:

$ org-semantic index ~/notes --both --config ~/notes/indexing.json
Error: the semantic index was built under a different policy —
       exclude_tagged: was [ARCHIVE, noexport], now []
       pass --full to rebuild under the new one, or restore the previous setting

Unknown keys are an error rather than ignored, for the same reason unknown flags are: a typo that does nothing looks exactly like a setting that does nothing.

chunks --config applies a policy without storing it or reindexing, so you can see what a change would do before paying for it. chunks previews the semantic index and chunks --lexical the word index, faithfully in each case: each is packed in its own unit, and only the lexical one carries a language. It says which one it is showing.

Over JSON-RPC the index method takes the same policy as a config object, so an editor can keep its own source of truth in whatever format suits it — a commented .eld, in Emacs's case — and pass it already parsed. Neither side needs a reader for the other's syntax.

That is also how todo_keywords is meant to be filled in from Emacs, rather than by hand: the editor already knows the answer, so it can send it. org-remove-keyword-keys does the stripping, so nothing has to be reimplemented:

(delete "|" (mapcan (lambda (s) (org-remove-keyword-keys (cdr s)))
                    (default-value 'org-todo-keywords)))

search takes config too, and checks it. A client whose policy comes from the user's own settings should send it with every query, not only when indexing — settings change between one search and the next, and an index built under the old ones answers from passages split by rules the user no longer holds. The check is a hash comparison, so it costs nothing per query.

On a mismatch the query fails rather than answering, and the error names the setting:

the semantic index was built under a different policy —
todo_keywords: was [DONE, TODO], now [DONE, NEXT, TODO]
reindex with `full` to rebuild under the new one, or restore the previous setting

which is what a client turns into your org-todo-keywords changed since this vault was indexed — reindex? Nothing is rebuilt without that answer.

It does not have to read that sentence to do so. Over JSON-RPC the same failure arrives labelled config-drift, with the settings that moved as a list of names — see errors you are meant to act on. The message is for showing; the label and the names are for deciding.

Two things a client should get right: send the policy on search as well as index, and latch the error into one prompt — the mismatch holds until the user acts, so a client searching as you type would otherwise raise it on every keystroke.

A note declares its language the way ltex-ls-plus already asks for it:

# ltex: language=de-DE

That takes effect from its own line onward, as ltex does, so a note may switch part-way — the marker forces a chunk boundary, since a chunk carries exactly one language. Placed between sections it costs nothing; placed mid-section it splits that section in two.

The keyword is always ltex. You do not need ltex installed to use it — # ltex: language=de-DE is an ordinary org comment — and if you do use it, the line you already wrote for grammar checking is the one this reads.

A language does two jobs, and only one of them is about stemming. It selects the stemmer that makes Sprachen find Sprache, which is the lexical index's business alone — an embedding is not stemmed. But it is also a fact about the note, and lang:de is a reasonable thing to ask of either ranking, so both indexes record one and both honour the predicate.

Do not read that as multilingual semantic search. Retrieving across languages is a question about the embedding model — ask it in German and bge-small-en will not find your German notes, whatever they are labelled — and the answer is a multilingual model, e5-small or one of the large ones. lang: answers the other question, "show me only the German ones", which no model can.

Earlier versions narrowed search --lexical alone and refused lang: on the other side rather than quietly matching nothing, because the semantic index recorded no language at all. If yours does, rebuild it: index --full.

Otherwise languages names what the vault is written in, and how many you name decides everything else:

"languages": ["en-US"]                       one language: every undeclared note is English
"languages": ["en-US", "de-DE", "it-IT"]     several: each note is classified as one of these
"languages": []                              classified with no restriction, all 176

Classification is per note rather than per chunk, since a chunk can be a two-line heading. It uses fastText's lid.176 (938 kB), downloaded to $XDG_CACHE_HOME/org-semantic/ on first use — or under ORG_SEMANTIC_CACHE_HOME, see What it writes.

It is accurate on prose and guesses when there is no prose. Measured across a 951-note vault, auto placed English, German and Italian correctly; the 0.4% it got wrong were notes that are almost entirely attachment links or shell snippets, where it is classifying filenames. Listing your languages removes those — the answer is the best-ranked language among the ones you named, so a note cannot come back Portuguese because a screenshot filename looked like it. On the same vault that takes the misclassifications to zero.

Languages are matched on their primary subtag but stored as you wrote them, so de-DE stays de-DE rather than becoming fastText's bare de. The first one you name is the vault's default.

Settle the list before you first index, because changing it later is not cheap. Both indexes write a language onto every chunk, so both are refused until they are rebuilt under the new one — the word index in a second or two, the meaning index by re-embedding the corpus, which is minutes. Leaving the semantic index alone instead was the alternative and is worse: every note you did not touch keeps the label it had, so a language you have just added answers nothing, with no error and nothing in the log. The order counts as a change too, since the first entry is the default.

A misclassified chunk is stemmed wrongly and becomes harder to find, with nothing to indicate why. An explicit # ltex: language=… overrides the classifier — it wins even over a language list that doesn't mention it, because the list says what may be guessed, never what a note may state. The exception is a code the classifier doesn't know, which is a typo far more often than a language; that warns and falls back to the default. Such a marker is a line those notes want anyway, so ltex doesn't grammar-check your shell commands.

Lexical search stems each note in its own language: oscillation finds oscillations in English notes, Sprachen finds Sprache in German ones, and neither leaks into the other. Regional variants share a stemmer, so de-DE and de-AT are both German.

fold_diacritics folds accents, so eleves matches élèves. It is named for the case worth having; the filter is broader, mapping non-ASCII to ASCII generally, so æ becomes ae too. Off by default, and worth noting it does nothing for German — that stemmer already strips umlauts, so Worter finds Wörter regardless. It is French, Spanish and Portuguese that need it. Changing it rebuilds the lexical index once (0.2 s).

Tags follow org's own inheritance — #+filetags: plus every ancestor heading's tags — so a chunk under * Project :work: is found by tag:work whether or not its own subheading says so. Values with spaces take quotes; matching is case-insensitive; anything unrecognised (2:1, a URL) stays as search text.

Predicates are stripped before embedding, so query syntax never reaches the model — tag:work would otherwise have it looking for notes about the words "tag" and "work".

Everything goes in one hidden directory — beside your notes by default, or somewhere else entirely if you say so. No note is ever modified — org-semantic only reads them.

Your prose is not copied into the index. A chunk records where it came from — the note and a range of lines — not what it said. That is a fraction of the size, and it is also truer: a preview is read from the note itself, so a code block appears in full even though the index deliberately replaced it with [src bash] before embedding.

It costs a handful of file reads per query, for the handful of hits actually being shown, and it means a preview can be missing if a note has moved since it was indexed — which is the honest answer in that case, rather than showing text that is no longer there.

One directory per model, each complete in itself. The chunk table is duplicated rather than shared because a vector is paired to its chunk by position: a shared table would silently go stale for every model you did not index in that run, and a same-count-different-content mismatch is exactly what a length check cannot catch.

An index is replaced whole or not at all. A run builds the new one beside the old and commits it at the end, so killing index halfway leaves you with the previous index, or with none — never with one that answers from mismatched pieces. If it leaves you with none, the next command says so and rebuilds, rather than quietly returning the wrong notes.

The two indexes are independent. Each carries everything its own hits need and its own record of which notes it is behind on, so either can be built, rebuilt or deleted without disturbing the other — which is what makes index --lexical a one-second operation rather than a ten-minute one.

The two chunk differently, because they are bounded by different things — see chunk in the policy above.

Add /.org-semantic/ to the vault's .gitignore. All of it is derived, so rebuilding is always available: org-semantic index --full writes it again in one pass. Deleting the directory works too, with one caveat — if this vault keeps its notes elsewhere, vault.json (below) goes with it, and the vault then looks empty rather than unindexed.

markdown-vdb reaches a very similar architecture for Markdown — one Rust binary, the index on disk, notes never modified. What sets it apart is where the embeddings come from: an external provider — OpenAI, Ollama, any OpenAI-compatible endpoint — so a search reaches out to a network or a local model server, and an API key and its cost or a running server come with it. org-semantic runs the model inside its own process and calls nothing over the network. Its front-end is aimed at AI agents — it ships Claude Code skills rather than an Emacs package. (It also merges the two rankings into one list, using reciprocal rank fusion — a way of combining two orderings without needing their scores to be comparable. org-semantic keeps them as separate commands for now; see Status.)

mdvault also does BM25 + semantic over a Markdown vault, but it is a Python tool (uv tool install) that keeps everything in one SQLite file and answers Claude Code over MCP. org-semantic is a single static binary — no interpreter, no .db. Both have a resident mode, aimed differently: mdvault's serve is MCP so Claude Code can search a vault; org-semantic's is JSON-RPC/LSP so an editor can. Neither ships an Emacs package.

All of these are Markdown-first; org-semantic exists because none of them parse org.

org-supertag is org-native and shares the same instincts — local-first, no server, no Python, :ID:-addressed, incremental on (mtime, hash) — but solves the opposite problem. It turns #tag headings into a structured database: you define fields once (a #paper has authors, year, status), fill them through spreadsheet and Kanban views, and query with an S-expression DSL over tags and fields — (and (tag "task") (not (field "status" "done"))). That answers "all unread papers rated ≥4", a question about structure you authored. org-semantic answers "notes about X" where you tagged nothing and don't know the words — a question about meaning, needing no schema. org-supertag has no embeddings; org-semantic keeps no database and never writes to your notes. They are complementary rather than competing, over the same vault: org-supertag could even maintain the #tag markers org-semantic reads as tag: predicates. Reach for org-supertag when you want structured views and a query language; reach for org-semantic when you want to find the note you can't name in a vault full of prose.

org-db and emacs-rag-libsql, both by John Kitchin, are the closest in aim to org-semantic — semantic search over an org tree, driven from Emacs. Both split the work the same way: Emacs parses and navigates, a Python FastAPI server does the embedding and the vector search. org-db goes wide — CLIP image search, SQLite full-text, indexing linked PDF/DOCX/PPTX, gptel tools for an LLM; emacs-rag-libsql goes deep on ranking, a cross-encoder reranking the vector hits in a second stage. Both fuse vector and keyword into one hybrid result.

The difference is what you have to install and what has to be running. Each needs Python and uv, and pulls in sentence-transformers and torch — org-db also transformers, pillow, pymupdf4llm, python-docx, python-pptx — then a FastAPI process listening on a port for Emacs to reach over HTTP. org-semantic is one static binary: the embedding model runs in-process through a statically linked ONNX Runtime, nothing binds a port, and serve is a stdio child the editor starts and owns, not a daemon.

vulpea is not in the table above because it answers a different question and has no embeddings in it at all. It indexes what a note is — its :ID:, its title, its tags, its metadata, what links to it — and gives you a query API and completing-read over that. org-semantic indexes what a note says. Over one tree the two compose about as well as two packages can: .vulpea/ and .org-semantic/ sit side by side in the vault, each owning its own, and neither is told about the other's.

Two concrete reasons to run both. You can name a note with vulpea and find one you cannot name with org-semantic — vulpea-find when you know it is the note about the Rabi paper, C-c n s when all you have is "that thing about pulse areas". And vulpea already watches the filesystem to keep its own database current — the whole tree, new subdirectories included — which is the one thing org-semantic does not do at all. Those watches can keep both indexes current, including the changes a save hook cannot see; see Searching from Emacs for how to hear about them.