@squirrelnotes.app/mcp 2.2.1-test.353 → 2.2.1-test.355
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/stdio-handler.js +36 -24
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -111,7 +111,7 @@ MCP does not (R-038).
|
|
|
111
111
|
|
|
112
112
|
| Tool | Description |
|
|
113
113
|
|------|-------------|
|
|
114
|
-
| `search_memory` | Finds memories by the words in their text, entity and tags: BM25 over the decrypted set, times a recency decay per category (half-life 30 days for `project_state`, a year for preferences and mental models, two years for entity facts, decisions and references). Word matching reads every script: a hyphenated word is one word (`pihole` and `Pi-hole` both find "Pi-hole"), and a hyphenated query word also half-matches its parts written apart, in order (`end-to-end` finds "end to end"); Chinese, Japanese, Thai, Lao, Khmer and Myanmar text, written without spaces, is matched by pairs of characters. Common English words and contraction fragments (a built-in list of 144: "what", "does", "he", "is", the "s" of "what's"…) are dropped from the query unless it has nothing else. The response names its `ranking` (`lexical` here; `hybrid` with the embeddings package; `none` for a listing) and `total` (matches before `limit`). Each hit has `score`, which orders that response only, and two scores that compare across searches: `lexicalScore` (0–1, the share of the query's content words the memory holds; a part of a hyphenated word counts half, as does a query word
|
|
114
|
+
| `search_memory` | Finds memories by the words in their text, entity and tags: BM25 over the decrypted set, times a recency decay per category (half-life 30 days for `project_state`, a year for preferences and mental models, two years for entity facts, decisions and references). Word matching reads every script: a hyphenated word is one word (`pihole` and `Pi-hole` both find "Pi-hole"), and a hyphenated query word also half-matches its parts written apart, in order (`end-to-end` finds "end to end"); Chinese, Japanese, Thai, Lao, Khmer and Myanmar text, written without spaces, is matched by pairs of characters. Common English words and contraction fragments (a built-in list of 144: "what", "does", "he", "is", the "s" of "what's"…) are dropped from the query unless it has nothing else. The response names its `ranking` (`lexical` here; `hybrid` with the embeddings package; `none` for a listing) and `total` (matches before `limit`). Each hit has `score`, which orders that response only, and two scores that compare across searches: `lexicalScore` (0–1, the share of the query's content words the memory holds; a part of a hyphenated word counts half, as does a query word that begins a word of the memory's text or tags at most twice its length: four or more characters, or three Latin letters only as the plural (a three-character word in another script keeps the half-word rule; `penicil` half-matches "penicillin" and `tag` "tags", but `use` never matches "user", `end` never matches "ended" or "endpoint", and `ad` never matches "admin"); an entity's words match only whole or by a hyphenated part (feature 0058)) and `semanticScore` (cosine similarity; always `null` in this package). Hits come in rank order, and the tool suggests no cut-off: a low score means lower confidence, not a wrong answer, and no score is a threshold (with the companion's gte-small model most memories score between about 0.75 and 0.95, related or not, so scores are compared within one response), so an agent is told to check low-scoring hits against the question before dismissing them (ADR-0444, amended 2026-10-13). `lexicalScore` is delivered rounded to two places. Each result also carries `validUntil`, `validUntilZone`, `stale` and `overdueDays` (see "Stale memories are flagged, never demoted" below), and `createdAt`, `createdBy`, `modifiedBy`, `origin` and `sourceRef` (see "Who wrote a memory" below); they never change the order or the scores. Optional `tags` keeps only memories carrying at least one listed tag (any of); optional `excludeTags` leaves out memories carrying any listed tag, and wins when a tag is in both lists. Each list takes at most 20 tags of 1–50 characters; tags match whole, ignoring case, accents on Latin letters (`cafe` and `café` are one tag here) and surrounding spaces, and an empty list is the same as leaving it out. The tag filters narrow which memories are ranked or listed; they do not change scores. They are a convenience, not access control: an agent that leaves them out sees every memory (scope enforced by the server is a separate, later piece of work). Optional `decisionStatus` (one to five of `proposed`, `discussed`, `decided`, `reversed`, `disputed`, default `["decided"]`) picks which decisions are returned; it applies to decisions only, so every other memory passes, and a decision whose stored status cannot be read counts as `proposed`. References are returned only with `category: "reference"`; to fetch one by its key, pass `category: "reference"` and the key as `entity`, with no query (see "Decisions and references" below). `decisionStatus` always has a value, so it never turns a call into a listing on its own. Optional `disputed` (`true` or `false`) keeps only memories in an open conflict, or only those in none (see "Conflicts between memories" below). Optional `entity` keeps only memories filed under that entity, matched whole, ignoring case, accents on Latin letters and surrounding spaces (`Zoe` finds "Zoë"; the same rule fetches a reference by its key). `query` is optional when `category`, `entity`, `tags`, `excludeTags` or `disputed` is given: the matching memories are then listed, newest first, `limit` at a time; pass `nextCursor` back as `cursor` for the next page (`null` on the last, and always `null` for a search). A memory edited during a walk can be missed, so compare the count against `total` or start again. With neither a query nor a filter, the call is refused. The decrypted list is reused for up to 60 s, and re-read after any write from this process. Reads every page of `GET /public/memory` and searches the decrypted set on your machine; it never asks the server for one memory, so the server cannot tell which ones were consulted. Leaves out superseded and invalidated memories unless asked; `searched` counts the memories that state filter let through (active, plus superseded or invalidated when asked for), before any `category`, reference, decision-status, `entity`, tag or `disputed` filter; `total` counts after them. A record that fails to decrypt or verify is skipped and counted (`unverifiable`), never shown; the tool description tells the agent that a non-zero count means some memories could not be read (a wrong key or tampering, for example) and to ask you to check them in the app. |
|
|
115
115
|
| `remember_memory` | Saves one memory (`text`, `category`, `entity`, optional `tags`, `sourceNoteId`, `validUntil`, `timezone`, `origin`, `sourceRef`). `origin` says where the claim came from: `user_stated`, `agent_inferred`, `agent_suggested_user_accepted` or `external_source`; left out, none is stored (there is no default). `sourceRef` (1–500 characters after trimming) points at the source: a URL, ticket, channel or note id, beside `sourceNoteId`. Anything else is refused and nothing is written. `validUntil` is the last day the memory holds, written `YYYY-MM-DD`, for a fact that expires (a deadline, a project's current state); anything else, such as `2026-02-30`, `31/10/2026` or a date-time, is refused and nothing is written. A past date is accepted, and the memory is stale at once. Without it, no date is stored. The date is a calendar day in `timezone`, an IANA zone name such as `Australia/Sydney` (any letter case; stored in its canonical spelling). Without `timezone`, the default zone is stored with the date: `SQUIRREL_TIMEZONE` if it is set, else this machine's zone. Abbreviations (`AEST`, `EST`), UTC offsets (`+10:00`), fixed `Etc/GMT±N` zones and unknown names are refused with a fixed message that does not repeat the value, and nothing is written. `timezone` without `validUntil` is refused too (nothing is sent). With `category: "decision"`, `decisionStatus` is required, and `decisionRationale` (1–500 characters), `decisionDate` (`YYYY-MM-DD`, past or future, no zone) and `decidedBy` (1–100 characters) are optional; with any other category the four are refused. Either refusal, and a malformed `decisionDate`, sends nothing. It is never pinned: only you pin, in the app. Returns near-duplicates (references and decisions of every status included) so the agent can supersede instead of adding a copy. |
|
|
116
116
|
| `supersede_memory` | Replaces an active memory (`id`, `text`, `reason`): the old one is kept, marked superseded and linked to the new one. Guarded by the memory's revision, so a concurrent change is refused (409), not overwritten. Optional `entity`, `category` and `tags` refile it: the new memory takes the values given, each one omitted keeps the old value, and `tags: []` clears the tags; the limits are `remember_memory`'s (entity 1–200 characters after trimming, one of the six categories, at most 20 tags of 1–50 characters). The decision inputs: an omitted `decisionStatus`, `decisionRationale`, `decisionDate` or `decidedBy` keeps the old decision's value, a value replaces it, and `null` clears a detail (not the status). Refiling into `decision` needs a `decisionStatus` unless the old memory is a decision; refiling out drops the status and details; decision inputs with another category are refused, before any request when that category is given, after the one read of the old memory when it is not. The old memory keeps where it was filed, so its history shows the move; the note it came from (`sourceNoteId`) carries over and cannot be changed. The `reason` is stored on both memories: on the old one as why it was replaced, on the new one as why it changed. The old memory keeps its `author`, `provenance`, `createdBy`, `createdAt`, `origin` and `sourceRef` exactly as stored; this call is recorded in its `modifiedBy`. Optional `origin` describes the new text and is stored on the new memory only (left out, the new memory has none). Optional `sourceRef`: omitted keeps the old memory's, a value replaces it, `null` clears it. Optional `validUntil` and `timezone` (as in `remember_memory`): with `validUntil` omitted, the new memory keeps the old one's date and its stored zone (a date with no zone stays without one, and a zone this machine does not know is not carried); a date replaces it, in `timezone` or else the default zone (never the old memory's zone); `null` clears the date and the zone. `timezone` with `validUntil` omitted or `null` is refused. The old memory keeps its own date and zone. Changing the date alone does not lift the unrelated-text check below. Both records are written unpinned, even if the old one was pinned: only you pin, in the app. A disputed memory's open conflicts move to the new memory, with their reasons and times, so it is disputed with the same memories; the old one keeps its own record of them. A new text that shares almost no words with the old one (relatedness below 0.25: the share of one text's words, stopwords aside, found in the other, a half-word prefix or a part of a hyphenated word counting half, the larger of the two directions) is refused and nothing is written: the message names the memory's id only and tells the agent to use `remember_memory` for a separate fact, or to call again with `confirmUnrelated: true` if the text really replaces it. Refiling does not lift this check: it applies whatever `entity`, `category` or `tags` you pass. Accents on Latin letters are ignored first ("Zoë" compares as "Zoe"), and text in any script is compared (Greek and Cyrillic by words, Chinese and Japanese by pairs of characters); only text with no letter or digit in any script (most emoji, or punctuation, alone) is not checked. The check runs on your machine on the decrypted texts, the same way with or without the embeddings package, and logs a fixed line (`supersede_memory refused (unrelated)`) with no memory content. |
|
|
117
117
|
| `invalidate_memory` | Marks an active memory as wrong. The text is kept; the memory is written unpinned. It keeps its `author`, `provenance`, `createdBy`, `createdAt`, `origin` and `sourceRef`; this call is recorded in its `modifiedBy`, and the answer's `author` is the memory's stored author. |
|
package/dist/stdio-handler.js
CHANGED
|
@@ -23272,16 +23272,22 @@ function codePoints(s) {
|
|
|
23272
23272
|
}
|
|
23273
23273
|
return n;
|
|
23274
23274
|
}
|
|
23275
|
+
function prefixCounts(term, total, lastUnit) {
|
|
23276
|
+
const n = codePoints(term);
|
|
23277
|
+
if (n < PREFIX_MIN_CODE_POINTS || n >= total || 2 * n < total) return false;
|
|
23278
|
+
if (n !== PLURAL_ONLY_CODE_POINTS || !isAscii(term)) return true;
|
|
23279
|
+
return total === n + 1 && lastUnit === 115;
|
|
23280
|
+
}
|
|
23275
23281
|
function matchWeight(term, w) {
|
|
23276
23282
|
if (term === w.word) return 1;
|
|
23277
|
-
if (w.prefixable && w.word.startsWith(term)) {
|
|
23278
|
-
|
|
23279
|
-
if (n >= PREFIX_MIN_CODE_POINTS && 2 * n >= codePoints(w.word)) return PREFIX_WEIGHT;
|
|
23283
|
+
if (w.prefixable && w.word.startsWith(term) && prefixCounts(term, codePoints(w.word), w.word.charCodeAt(w.word.length - 1))) {
|
|
23284
|
+
return PREFIX_WEIGHT;
|
|
23280
23285
|
}
|
|
23281
23286
|
return w.parts.includes(term) ? PART_WEIGHT : 0;
|
|
23282
23287
|
}
|
|
23283
|
-
function
|
|
23284
|
-
|
|
23288
|
+
function memoryWordsOf(p) {
|
|
23289
|
+
const entity = memoryWords(p.entity).map((w) => w.prefixable ? { ...w, prefixable: false } : w);
|
|
23290
|
+
return [...memoryWords(p.text), ...entity, ...memoryWords(p.tags.join(" "))];
|
|
23285
23291
|
}
|
|
23286
23292
|
function hasSearchableText(query) {
|
|
23287
23293
|
return memoryWords(query).length > 0;
|
|
@@ -23358,11 +23364,13 @@ function weighWords(words, terms, tf, exact) {
|
|
|
23358
23364
|
if (w.prefixable && prefixLengths.length > 0 && w.word.length > (prefixLengths[0] ?? 0)) {
|
|
23359
23365
|
const total = codePoints(w.word);
|
|
23360
23366
|
const bmp = total === w.word.length;
|
|
23367
|
+
const lastUnit = w.word.charCodeAt(w.word.length - 1);
|
|
23361
23368
|
for (const k of prefixLengths) {
|
|
23362
23369
|
if (k >= total) break;
|
|
23363
23370
|
if (2 * k < total) continue;
|
|
23364
|
-
const
|
|
23365
|
-
|
|
23371
|
+
const prefix = bmp ? w.word.slice(0, k) : codePointPrefix(w.word, k);
|
|
23372
|
+
const t = index.get(prefix);
|
|
23373
|
+
if (t !== void 0 && t !== same && !half.includes(t) && prefixCounts(prefix, total, lastUnit)) half.push(t);
|
|
23366
23374
|
}
|
|
23367
23375
|
}
|
|
23368
23376
|
for (const part of w.parts) {
|
|
@@ -23406,7 +23414,7 @@ function scoreMemoriesWithCoverage(query, memories, now2) {
|
|
|
23406
23414
|
const coverages = [];
|
|
23407
23415
|
const exact = new Uint8Array(terms.length);
|
|
23408
23416
|
for (const m of memories) {
|
|
23409
|
-
const words =
|
|
23417
|
+
const words = memoryWordsOf(m.payload);
|
|
23410
23418
|
lengths.push(words.length);
|
|
23411
23419
|
const row = new Float64Array(terms.length);
|
|
23412
23420
|
exact.fill(0);
|
|
@@ -23449,27 +23457,31 @@ function textCoverage(text, other) {
|
|
|
23449
23457
|
return coverageAgainst(text)(other);
|
|
23450
23458
|
}
|
|
23451
23459
|
function coverageAgainst(text) {
|
|
23460
|
+
const against = coverageOfWordsAgainst(text);
|
|
23461
|
+
return (other) => against(memoryWords(other));
|
|
23462
|
+
}
|
|
23463
|
+
function coverageOfWordsAgainst(text) {
|
|
23452
23464
|
const { terms, parts } = queryTermsWithParts(text);
|
|
23453
23465
|
if (terms.length === 0) return () => 0;
|
|
23454
23466
|
const termIndex = indexTerms(terms, parts);
|
|
23455
23467
|
const tf = new Float64Array(terms.length);
|
|
23456
23468
|
const exact = new Uint8Array(terms.length);
|
|
23457
|
-
return (
|
|
23469
|
+
return (words) => {
|
|
23458
23470
|
tf.fill(0);
|
|
23459
23471
|
exact.fill(0);
|
|
23460
|
-
weighTerms(
|
|
23472
|
+
weighTerms(words, termIndex, tf, exact);
|
|
23461
23473
|
return coverageOf(tf, exact);
|
|
23462
23474
|
};
|
|
23463
23475
|
}
|
|
23464
23476
|
function termCoverageAgainst(text) {
|
|
23465
|
-
const against =
|
|
23466
|
-
return (p) => against(
|
|
23477
|
+
const against = coverageOfWordsAgainst(text);
|
|
23478
|
+
return (p) => against(memoryWordsOf(p));
|
|
23467
23479
|
}
|
|
23468
23480
|
function supersedeRelatedness(oldText, newText) {
|
|
23469
23481
|
if (!hasSearchableText(oldText) || !hasSearchableText(newText)) return null;
|
|
23470
23482
|
return Math.max(textCoverage(newText, oldText), textCoverage(oldText, newText));
|
|
23471
23483
|
}
|
|
23472
|
-
var WORD_RUN, ASCII_WORD_RUN, SELECTORS, NO_SPACE_SCRIPT, JOINER, MARK2, GROUP_TESTS, GROUP_CACHE_LIMIT, groupCache, distinct, NO_PARTS, PREFIX_MIN_CODE_POINTS, DECAY_HALF_LIFE_DAYS, BM25_K1, BM25_B, PREFIX_WEIGHT, PART_WEIGHT, DAY_MS2, STOPWORDS, NT_STEMS, SCAN_MAX_TERMS, SUPERSEDE_RELATEDNESS_MIN;
|
|
23484
|
+
var WORD_RUN, ASCII_WORD_RUN, SELECTORS, NO_SPACE_SCRIPT, JOINER, MARK2, GROUP_TESTS, GROUP_CACHE_LIMIT, groupCache, distinct, NO_PARTS, PREFIX_MIN_CODE_POINTS, PLURAL_ONLY_CODE_POINTS, DECAY_HALF_LIFE_DAYS, BM25_K1, BM25_B, PREFIX_WEIGHT, PART_WEIGHT, DAY_MS2, STOPWORDS, NT_STEMS, SCAN_MAX_TERMS, SUPERSEDE_RELATEDNESS_MIN;
|
|
23473
23485
|
var init_memory_search = __esm({
|
|
23474
23486
|
"src/memory-search.ts"() {
|
|
23475
23487
|
"use strict";
|
|
@@ -23493,6 +23505,7 @@ var init_memory_search = __esm({
|
|
|
23493
23505
|
distinct = (xs) => [...new Set(xs)];
|
|
23494
23506
|
NO_PARTS = Object.freeze([]);
|
|
23495
23507
|
PREFIX_MIN_CODE_POINTS = 3;
|
|
23508
|
+
PLURAL_ONLY_CODE_POINTS = 3;
|
|
23496
23509
|
DECAY_HALF_LIFE_DAYS = {
|
|
23497
23510
|
preference: 365,
|
|
23498
23511
|
mental_model: 365,
|
|
@@ -23664,17 +23677,17 @@ var init_memory_search = __esm({
|
|
|
23664
23677
|
});
|
|
23665
23678
|
|
|
23666
23679
|
// src/memory-rank.ts
|
|
23667
|
-
function semanticPart(similarity, minSimilarity) {
|
|
23680
|
+
function semanticPart(similarity, minSimilarity, semanticSpan) {
|
|
23668
23681
|
if (similarity === null) return 0;
|
|
23669
|
-
return Math.min(1, Math.max(0, (similarity - minSimilarity) /
|
|
23682
|
+
return Math.min(1, Math.max(0, (similarity - minSimilarity) / semanticSpan));
|
|
23670
23683
|
}
|
|
23671
|
-
function fusedScore(m, minSimilarity) {
|
|
23672
|
-
return W_LEX * m.lexicalScore + (1 - W_LEX) * semanticPart(m.similarity, minSimilarity) * m.decay;
|
|
23684
|
+
function fusedScore(m, minSimilarity, semanticSpan) {
|
|
23685
|
+
return W_LEX * m.lexicalScore + (1 - W_LEX) * semanticPart(m.similarity, minSimilarity, semanticSpan) * m.decay;
|
|
23673
23686
|
}
|
|
23674
|
-
function fuseScores(members, minSimilarity) {
|
|
23687
|
+
function fuseScores(members, minSimilarity, semanticSpan) {
|
|
23675
23688
|
const cosine = (m) => m.similarity ?? Number.NEGATIVE_INFINITY;
|
|
23676
23689
|
const banded = (m) => {
|
|
23677
|
-
const half = fusedScore(m, minSimilarity) / 2;
|
|
23690
|
+
const half = fusedScore(m, minSimilarity, semanticSpan) / 2;
|
|
23678
23691
|
return m.lexicalScore >= FULL_WORD_MATCH ? FULL_MATCH_BAND + half : half;
|
|
23679
23692
|
};
|
|
23680
23693
|
return members.map((m) => ({ m, score: banded(m) })).sort(
|
|
@@ -23688,13 +23701,12 @@ function memoryEmbeddingText(p) {
|
|
|
23688
23701
|
function aboveFloor(similarities, minSimilarity) {
|
|
23689
23702
|
return similarities.filter((m) => m.similarity >= minSimilarity);
|
|
23690
23703
|
}
|
|
23691
|
-
var W_LEX,
|
|
23704
|
+
var W_LEX, FULL_WORD_MATCH, FULL_MATCH_BAND;
|
|
23692
23705
|
var init_memory_rank = __esm({
|
|
23693
23706
|
"src/memory-rank.ts"() {
|
|
23694
23707
|
"use strict";
|
|
23695
23708
|
init_memory_context();
|
|
23696
23709
|
W_LEX = 0.3;
|
|
23697
|
-
SEMANTIC_SPAN = 0.4;
|
|
23698
23710
|
FULL_WORD_MATCH = 1;
|
|
23699
23711
|
FULL_MATCH_BAND = 0.5;
|
|
23700
23712
|
}
|
|
@@ -23999,7 +24011,7 @@ async function rankForSearch(query, all, eligible, semantic, key, now2) {
|
|
|
23999
24011
|
updatedAt: p.updatedAt
|
|
24000
24012
|
};
|
|
24001
24013
|
});
|
|
24002
|
-
const ranked = fuseScores(members, scored.minSimilarity).map(({ id, score }) => hit(id, score, similarity));
|
|
24014
|
+
const ranked = fuseScores(members, scored.minSimilarity, scored.semanticSpan).map(({ id, score }) => hit(id, score, similarity));
|
|
24003
24015
|
return { ranked, fused: true };
|
|
24004
24016
|
}
|
|
24005
24017
|
function listByRecency(eligible) {
|
|
@@ -25019,7 +25031,7 @@ var init_memory = __esm({
|
|
|
25019
25031
|
CONFLICT_HELP = "Each memory carries `disputed` (true when it is in an open conflict) and `conflicts` (its open conflicts, oldest first: `{ with, reason, recordedAt }`, where `with` is the other memory's id). A conflict, recorded with record_conflict, links two memories that make competing claims. It is open while both are active and either one lists the other, so it ends when it is resolved with resolve_conflict or when either memory is superseded or invalidated (a supersede_memory moves it to the new memory). A memory that is not active is never disputed. Disputed memories stay live: they rank and filter exactly as before, so check `disputed` before relying on one. This is not a decision's `disputed` status, which is a status on one decision, set with decisionStatus and filtered by it; neither conflict tool changes it.";
|
|
25020
25032
|
REMEMBER_ORIGIN_HELP = "Pass `origin` when you know where the claim came from: user_stated (the user said it), agent_inferred (you concluded it), agent_suggested_user_accepted (you suggested it and the user agreed) or external_source (a document, ticket, page or other source); leave it out rather than guess. Pass `sourceRef` to point at the source. Both are recorded as you state them, and the memory is still flagged for the user to review.";
|
|
25021
25033
|
TIMEZONE_ARG_HELP = "The IANA time zone validUntil is a calendar day in, e.g. Australia/Sydney. Default: SQUIRREL_TIMEZONE if set, else this machine's zone. Only with validUntil";
|
|
25022
|
-
SEARCH_MEMORY_DESCRIPTION = `Search the user's long-term memories (short facts and preferences saved by agents or the user). Ranks active memories by their relevance to the query: matching words in the text, entity and tags, and, when the user has installed local embeddings, similar meaning. Common English words (stopwords such as "what", "does", "he", "is") are ignored by word matching unless the query has nothing else. Word matching ignores case and accents on Latin letters (\xE9 matches e, \xDF matches ss, as in the app's search) and works in any script: Chinese, Japanese, Thai, Lao, Khmer and Myanmar text, written without spaces, is matched by pairs of characters. A hyphenated word matches whole ("pihole" or "Pi-hole" finds Pi-hole), and each of its parts counts half; a hyphenated query word also counts half where its parts are written apart, in order ("end-to-end" finds "end to end"). Other forms of a word are not matched (\u0442\u0451\u043C\u043D\u0430\u044F does not find \u0442\u0451\u043C\u043D\u0443\u044E), and accents on letters of other scripts still count. The response says which ranking ran: "hybrid" (words and meaning), "lexical" (words only) or "none" (a listing). Each hit has \`score\`, which orders this response only and cannot be compared across searches: without local embeddings it is BM25 times a recency weight; with them, the fused value is 0.3 \xD7 lexicalScore plus 0.7 \xD7 semanticScore rescaled (0 at the
|
|
25034
|
+
SEARCH_MEMORY_DESCRIPTION = `Search the user's long-term memories (short facts and preferences saved by agents or the user). Ranks active memories by their relevance to the query: matching words in the text, entity and tags, and, when the user has installed local embeddings, similar meaning. Common English words (stopwords such as "what", "does", "he", "is") are ignored by word matching unless the query has nothing else. Word matching ignores case and accents on Latin letters (\xE9 matches e, \xDF matches ss, as in the app's search) and works in any script: Chinese, Japanese, Thai, Lao, Khmer and Myanmar text, written without spaces, is matched by pairs of characters. A hyphenated word matches whole ("pihole" or "Pi-hole" finds Pi-hole), and each of its parts counts half; a hyphenated query word also counts half where its parts are written apart, in order ("end-to-end" finds "end to end"). Other forms of a word are not matched (\u0442\u0451\u043C\u043D\u0430\u044F does not find \u0442\u0451\u043C\u043D\u0443\u044E), and accents on letters of other scripts still count. The response says which ranking ran: "hybrid" (words and meaning), "lexical" (words only) or "none" (a listing). Each hit has \`score\`, which orders this response only and cannot be compared across searches: without local embeddings it is BM25 times a recency weight; with them, the fused value is 0.3 \xD7 lexicalScore plus 0.7 \xD7 semanticScore rescaled from the model's floor (0 at the floor or below, 1 a set span above it; for the bundled gte-small model, 0 at a cosine of 0.836 or below and 1 at 0.92 or above) times the recency weight, so age discounts only the meaning part; a hit holding every query word scores 0.5 plus half the fused value and any other hit half of it, so those hits come first, \`score\` never rises down the list, and of two hits with the same recency weight (same age and category) on the same side of 0.5, one at least as high on both scores ranks first. Two scores can be compared across searches: \`lexicalScore\` (0\u20131, the share of the query's words, stopwords aside, that the memory contains; a part of a hyphenated word counts half, and so does a query word that begins a word of the memory's text or tags at most twice its length: four or more characters ("deploy" finds "deploys"), or three Latin letters or digits followed only by "s" ("tag" finds "tags", "use" does not find "user"; a three-character word in another script keeps the half-word rule); the entity's words count only whole or by a hyphenated part) and \`semanticScore\` (the cosine similarity of meaning, null unless the ranking is hybrid). Hits are in rank order. A low score means lower confidence, not a wrong answer, and no score is a cut-off, so check low-scoring hits against the question before dismissing them. semanticScore is a cosine, from -1 to 1; with gte-small most memories score between about 0.75 and 0.95, related or not, so compare it between the hits of one response, not with a fixed number. If nothing answers the question, search again with two or three other phrasings, including the specific words the memory itself would use (a product, place, tool or person), before concluding that nothing is stored, and before saving a memory that may already exist. \`tags\` keeps only memories carrying at least one of the listed tags (any of); \`excludeTags\` leaves out memories carrying any of its tags, and wins over \`tags\` when a tag is in both. Tags match whole, case-insensitive and ignoring accents on Latin letters after trimming spaces (so \`cafe\` and \`caf\xE9\` are the same tag here); an empty list is the same as leaving it out. Tags are a convenience filter, not access control: a call that leaves them out sees every memory. \`decisionStatus\` picks which decisions to return (any of the listed statuses; default ["decided"]); it applies to decisions only, so every other memory passes. \`entity\` matches the whole entity, ignoring case, accents on Latin letters and surrounding spaces (so \`Zoe\` finds Zo\xEB). References (category "reference") are returned only when \`category\` is "reference": to fetch one by its key, pass category "reference" and the key as \`entity\`, with no query. Like tags, these filters are a convenience, not access control. \`disputed: true\` keeps only memories in an open conflict, and \`disputed: false\` only those in none; like the other filters, it can be used with no query. Without a query, a category, entity, tag (\`tags\` or \`excludeTags\`) or \`disputed\` filter lists the matching memories, newest first, \`limit\` (at most 20) at a time: pass the response's \`nextCursor\` as \`cursor\` for the next page (null on the last). \`total\` is how many match in all; a memory edited during a walk may be missed, so compare against \`total\` or start again. \`searched\` counts the memories considered: active ones, plus superseded or invalidated ones when asked for, before the category, reference, decision-status, entity, tag and disputed filters. \`unverifiable\` counts the stored memories that failed to decrypt or verify (damaged, tampered with, or not sealed under this key): they are skipped and never shown. A non-zero count means some memories could not be read, so tell the user to check their memories in the app. ${STALENESS_HELP} ${DECISION_HELP} ${WRITER_HELP} ${CONFLICT_HELP} ${NEEDS_REVIEW_HELP} Superseded and invalidated memories are left out unless asked for.`;
|
|
25023
25035
|
SUPERSEDE_MEMORY_DESCRIPTION = "Replace an active memory with a corrected one. The old memory is kept as superseded (history is never lost) and the new one is linked to it. Both are flagged for the user to review. To refile it, pass `entity`, `category` or `tags`: the new memory takes them, each one omitted keeps the old value, and `tags: []` clears the tags; the old memory keeps where it was filed, so the history shows the move. The reason is stored on both memories: on the old one as why it was replaced, on the new one as why it changed. Neither memory is pinned afterwards, even if the old one was: only the user pins, in the app. `validUntil`: omitted keeps the old memory's date and its zone, a date replaces it (read in `timezone`, else the default zone, `SQUIRREL_TIMEZONE` or this machine's), `null` clears both; the old memory keeps its own. `timezone` needs a date. Decision fields: an omitted `decisionStatus`, `decisionRationale`, `decisionDate` or `decidedBy` keeps the old decision's value, a value replaces it, and `null` clears a detail (the status cannot be cleared). Refiling into \"decision\" needs a `decisionStatus` unless the old memory is a decision, refiling out drops them, and passing them with another category is refused. The old memory keeps its own. `origin` describes the new text and is stored on the new memory only. `sourceRef`: omitted keeps the old memory's, a value replaces it, `null` clears it. The old memory keeps its author, provenance, `createdBy`, `origin` and `sourceRef`, and records you in `modifiedBy`. A disputed memory's open conflicts move to the new memory, which is disputed with the same memories; the old one keeps its own record of them. A new text that shares almost no words with the old one is refused as a different memory, whatever `entity` or `category` you pass: if it is a separate fact, use remember_memory; if it really replaces this memory, call again with `confirmUnrelated: true`. Text with no letter or digit in any script (most emoji, or punctuation, alone) is not checked. " + NEEDS_REVIEW_HELP;
|
|
25024
25036
|
RECORD_CONFLICT_DESCRIPTION = `Record that two active memories make competing claims, when you cannot yet tell which is right. Both stay active and in effect: they are searched, ranked and filtered as before. Each stores the conflict, with your reason, in its encrypted record, and both read as \`disputed: true\`, each with the other in \`conflicts\`, until it is resolved. Both are flagged for the user to review and unpinned (only the user pins, in the app). A conflict links two memories: for three or more, record each pair. A memory can be in at most ${MAX_OPEN_CONFLICTS} open conflicts. Calling it again for a conflict recorded on one side only (after a failed write) writes the missing side; a conflict already recorded on both is refused. When you know which claim is right, use supersede_memory (or resolve_conflict once a conflict is recorded); when one is simply wrong, invalidate_memory. This does not change a decision's status: to mark a decision itself disputed, supersede it with decisionStatus "disputed". ${CONFLICT_HELP} ${NEEDS_REVIEW_HELP}`;
|
|
25025
25037
|
RESOLVE_CONFLICT_DESCRIPTION = "Settle an open conflict recorded with record_conflict. The memory `supersedeId` becomes superseded by `keepId`, with `evidence` as its reason; its text, history and record of the conflict are kept. `keepId` stays active, drops its entry for the other memory, keeps its other open conflicts, and is flagged for the user to review. No new memory is written: to replace both with a corrected claim, use supersede_memory, and when neither is right, invalidate_memory. Refused unless the two are in an open conflict. It does not change a decision's status. If the write to `keepId` fails after `supersedeId` was superseded, the answer has `keptUpdated: false` and a `note`: the resolution still took effect. " + NEEDS_REVIEW_HELP;
|
|
@@ -26342,7 +26354,7 @@ var init_memory_semantic = __esm({
|
|
|
26342
26354
|
}
|
|
26343
26355
|
await this.writeChain;
|
|
26344
26356
|
scored.sort((a, b) => b.similarity - a.similarity || (a.id < b.id ? -1 : 1));
|
|
26345
|
-
return { similarities: scored, minSimilarity: embedder.minSimilarity };
|
|
26357
|
+
return { similarities: scored, minSimilarity: embedder.minSimilarity, semanticSpan: embedder.semanticSpan };
|
|
26346
26358
|
} catch {
|
|
26347
26359
|
this.state = { kind: "off" };
|
|
26348
26360
|
this.options.log("memory: semantic search failed in the embedding runtime; using lexical search for the rest of this session");
|
package/package.json
CHANGED