Skip to content
Docs menu

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.

View .md

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

  1. 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: value lines. So "is the phone deductible" finds the row Mobile phone bills whose Deductible is Partly, even though the body never says "deductible".
  2. 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.
  3. The two lists are merged by reciprocal rank fusion, each note keeps its best passage as the snippet.
  4. 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 CPU

Once 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.

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