How Ask finds notes
How Ask in Notes and globe_note_related find notes by keywords, by meaning and by links, what needs an embedding model, how to run one on your own machine, and how well it works.
Ask (globe_note_ask over MCP, POST /api/v1/notes/ask over REST) takes a question in plain words and returns the
notes that answer it, as numbered citations with a snippet each. Your agent writes the answer from them. Search
(globe_note_search) is different: it is full-text search for the words you type, every word must match.
What Ask does
- Keywords. Any of the question's content words, in the note's title and body and in its passages. A passage
starts with the note's title, its folder path and, for a database row, the database's name and the row's properties
as
Name: valuelines. So "is the phone deductible" finds the row Mobile phone bills whoseDeductibleisPartly, even though the body never says "deductible". - Meaning, when your organisation has an embedding model. The question is embedded and compared with every passage, so "can I claim my laptop" finds Computers and prescribed automation equipment.
- The two lists are merged by reciprocal rank fusion, each note keeps its best passage as the snippet.
- Links. The notes that the top three link to, or that link to them, come in just below the note that brought
them. The answer marks them, for example
(linked from [1]).
Every step runs inside what you can read: your own vault and the org's open notes. Another member's notes, notes restricted to the people invited, and other organisations' notes never come back, not even as a snippet.
The answer's second line says which way it searched: "Found by meaning and keywords" or "Keyword search only", with the reason (no embedding model configured, the model did not answer, or the notes are not embedded yet).
What needs an embedding model
Only step 2. Without one, everything else works: passages are still made (so row properties and folder paths are searchable), links are still followed, and the answer says the search was keyword only.
Notes uses the first model with embed in its name that your organisation's routes serve, your own daemons' models
before any cloud provider's. Under sovereign_only the cloud providers are never used. The cloud calls a provider only
if your organisation configured one and serves no embedding model of its own. The model must give 1024-dimension
vectors; a model that takes a dimensions parameter (OpenAI's text-embedding-3-*) is asked for 1024. A model of
another size is not used and Ask stays keyword only.
Run one on your own machine
On the machine that runs your daemon:
ollama pull mxbai-embed-large # 1024 dimensions, 670 MB, runs on a laptop CPUOnce the daemon serves it (it shows in GET /v1/models with your key), Notes uses it: new and edited notes at once,
existing notes within a few runs of the 5-minute backfill. bge-m3 (1024 dimensions,
multilingual) works too.
When notes are embedded
- A saved note is chunked and embedded a few seconds after the save, never during it.
- Every 5 minutes a backfill picks up whatever a save did not (imports, database edits, the live editor) and every note of an organisation whose embedding model changed.
- A note whose passages and model are unchanged is skipped: running it again costs nothing.
- Passages are about 280 words with 40 words of overlap, split at headings.
Related notes
globe_note_related (MCP) or GET /api/v1/notes/{id}/related (REST) lists the notes next to one note, each with why:
| Reason | Means |
|---|---|
| linked from this note / links to this note | a [[wikilink]] or @ mention either way |
| embedded in this note | a ![[embed]] |
| parent page / sub-page | the page of the folder the note is in, or a page in its folder |
| page that shows this row's database | the page whose database block shows the database the row is in |
| row of a database this page shows | the other way round |
| row in the same database | another row of the same database |
| related by a relation property | a database relation |
| similar by meaning (0.82) | the notes whose vector is closest to this one's (the mean of its passages' embeddings), above the same floor as the graph's similar lines, with the cosine similarity (needs a model) |
| shares a topic: CPF | the two notes mention the same specific entity, as in the graph's topic lines |
How well it works
test/db/globe-retrieval-eval.test.ts measures it on a 57-note vault modelled on real use: a database of Singapore
tax-deductibility rules shown on a page, meeting notes that link to its rows and to projects, project pages with
sub-pages, personal admin notes and some noise. 35 questions, each with the notes that answer it, in three groups:
paraphrases (the question uses other words than the note), lexical (the note's own words, asked as a question) and
structure (the answer is a note linked to the one that matches).
With mxbai-embed-large through Ollama:
| Retrieval | recall@5 | recall@10 | MRR | paraphrase R@5 / MRR | lexical R@5 / MRR | structure R@5 / MRR |
|---|---|---|---|---|---|---|
| keyword, before (every word must match) | 0.14 | 0.14 | 0.14 | 0.00 / 0.00 | 0.50 / 0.50 | 0.00 / 0.00 |
| keyword (any word, passages) | 0.61 | 0.76 | 0.62 | 0.40 / 0.42 | 1.00 / 0.95 | 0.70 / 0.75 |
| hybrid | 0.86 | 1.00 | 0.76 | 0.80 / 0.60 | 1.00 / 0.95 | 0.80 / 1.00 |
| hybrid + links (what Ask does) | 0.87 | 1.00 | 0.76 | 0.80 / 0.60 | 1.00 / 0.95 | 0.90 / 1.00 |
In CI the same eval runs offline with a hashed embedder that knows spelling, not meaning, so it shows the pipeline, not the model: hybrid + links 0.74 recall@5 (keyword before: 0.14, keyword any word: 0.61).
Following a row's database page, sibling rows and parent pages in Ask was measured too and left out: it pushed better
matches out of the top 5 (paraphrase recall@5 0.80 to 0.63 with mxbai-embed-large). Related notes still list them.
The graph's similar and topic lines were measured the same way and also left out of Ask (recall@5 0.87 to 0.81 with
similar lines followed, 0.86 with topic lines): see How well it works.
To run the eval against your own embedding model (any OpenAI-compatible /embeddings, such as your orchestrator or
Ollama), from services/nodejs-cloud:
GLOBE_EVAL_EMBED_URL=http://127.0.0.1:11434/v1 GLOBE_EVAL_EMBED_MODEL=mxbai-embed-large \
node scripts/test.ts test/db/globe-retrieval-eval.test.ts