@squirrelnotes.app/mcp-embeddings 2.2.0 → 2.2.1-test.353

package/README.md

@@ -2,8 +2,8 @@
 
 `@squirrelnotes.app/mcp-embeddings` is the Squirrel Notes stdio MCP server
 with **semantic memory search**. `search_memory` finds a memory by its meaning
-as well as its words, so *"what coffee do they order?"* can find *"Orders a
-flat white with oat milk"*.
+as well as its words, so *"food allergies"* finds *"Is allergic to peanuts"*,
+which shares no word with it.
 
 It is the same server as [`@squirrelnotes.app/mcp`](https://www.npmjs.com/package/@squirrelnotes.app/mcp):
 the same tools, the same inputs and the same output shape. It is built from the
@@ -100,16 +100,31 @@ The vector file can be deleted at any time; it is rebuilt when needed.
 
 - Without this package, `search_memory` is lexical: BM25 over the words of each
   memory's text, entity and tags, times a recency decay per category.
-- With it, two orders are fused by reciprocal rank fusion (k = 60): the
-  lexical order, and the semantic order (cosine similarity between the query
-  and each memory, times the same recency decay). Each order counts the decay
-  once, and the fused score is not multiplied again. A memory in both orders
-  ranks above one in only one.
-- A semantic match must reach a minimum similarity of 0.35. Below that, a
-  memory is returned only if its words match.
+- With it, the two scores each hit returns are fused (feature 0050, in place
+  of reciprocal rank fusion; feature 0054, "words win, age on meaning").
+  The fused value is 0.3 × `lexicalScore` + 0.7 × the semantic part × the
+  recency decay, where the semantic part is 0 at or below the 0.35 floor, 1
+  at a cosine of 0.75 or above, and linear between. The decay is applied
+  once, to the semantic part only, so age does not fade a memory's word
+  match. A hit that holds every query word (`lexicalScore` 1) scores 0.5 +
+  half the fused value, any other hit half of it: so those hits come first,
+  and `score` never rises down the list. Of two hits on the same side of 0.5
+  with the same recency weight (the same age and category), one at least as
+  high on both `lexicalScore` and `semanticScore`, and higher on one, ranks
+  first; ties go to the higher cosine. The weight 0.3
+  was chosen after measuring on the recall gate's corpus (any weight between
+  0 and 1 keeps that order); the span 0.4 was fixed before measuring and
+  belongs to this model's cosine range.
+- The members are the memories whose words match and those at or above the
+  0.35 floor. Below that, a memory is returned only if its words match.
+- An old memory matched by words keeps its word part whatever its age: only
+  the meaning part is discounted. One that holds every query word ranks above
+  any memory matched by meaning alone, and one that holds some of them can
+  still rank above a fresh memory matched by meaning alone (feature 0054,
+  settling proposal 0074's open question 2). Lexical search is unchanged: BM25
+  times the decay.
 - `score` is on a 0–1 scale here, and unbounded BM25 in the base package. It
-  orders one response only: a memory found by one order alone scores about 0.5
-  whatever its relevance. The keys are the same in both.
+  orders one response only. The keys are the same in both.
 - To judge a hit, use the absolute scores: `semanticScore` (the cosine
   similarity, reported for every hit, also those below 0.35 found by words) and
   `lexicalScore` (the share of the query's content words, stopwords aside).
@@ -121,9 +136,21 @@ The vector file can be deleted at any time; it is rebuilt when needed.
   2026-10-13). `semanticScore` is a cosine, −1 to 1
   (in practice about −0.1 to 0.9). `ranking` is `hybrid` when the semantic
   order ran, `lexical` while the model loads or after it fails.
-- Words outside ASCII letters and digits never match lexically, in either
-  package. Embeddings can find some of these memories (see *Recall*).
-- A query with no ASCII letters or digits always comes back with a `note`.
+- Accents on Latin letters are ignored by word matching in both packages
+  (`creme` finds "crème", `strasse` finds "Straße"). Word matching works in
+  any script in both packages: Greek, Cyrillic or Korean by words, and
+  Chinese, Japanese, Thai, Lao, Khmer and Myanmar, written without spaces, by
+  pairs of characters (a one-character query counts half for each pair
+  holding it). Other forms of a word are not matched (`тёмная` does not find
+  "тёмную", and a two-syllable Korean query such as `서울` does not find
+  "서울에", where a particle is attached), and accents on letters of other
+  scripts still count.
+  The model reads English: embeddings add little for other languages.
+- A hyphenated word matches whole (`pihole` or `Pi-hole`), and each of its
+  parts counts half; a query word of one or two letters matches only that
+  whole word, or a hyphenated word's part of the same spelling (half).
+- A query with no letter or digit in any script (most emoji, or punctuation, alone)
+  always comes back with a `note`.
   It says the query cannot be searched, unless the semantic ranking actually
   ran, in which case it says the results were found only by meaning.
 
@@ -143,8 +170,12 @@ is lexical too.
 
 **First searches.** Each memory is embedded once, then only again when it
 changes (its revision moves). A search spends at most 8 seconds embedding
-memories that have no vector yet; the rest still rank lexically until a later
-search embeds them. Measured on an Apple M1 Pro: 500 memories in 4.4 s, 5,000
+memories that have no vector yet. Until a later search embeds them, the rest
+have no `semanticScore`: they are returned only if their words match, and
+their fused value is at most 0.3, so during this warm-up a partial word
+match not yet embedded can rank below a memory found by meaning alone (a
+match on every query word still ranks first).
+Measured on an Apple M1 Pro: 500 memories in 4.4 s, 5,000
 in 26.7 s.
 
 ## Model integrity
@@ -173,7 +204,12 @@ recall@5 of lexical and hybrid search on 500 memories and 160 queries.
   zero-knowledge encryption makes unreadable.
 - Hybrid search must gain at least 15 points on paraphrased queries, and must
   not lose on exact-word queries.
-- The latest results are in ADR-0444 in the Squirrel Notes repository.
+- Since feature 0050 it also gates, by words alone, a small ranking set of
+  stand-ins for reported misses (hyphenated words, short fragments) and a
+  ten-query set in other scripts (lexical recall@5 at least 0.8), and reports
+  recall@1 and MRR beside recall@5.
+- The latest results are in ADR-0444 and the feature 0050 notes in the
+  Squirrel Notes repository.
 
 ## Environment variables