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

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.
Files changed (3) hide show
  1. package/README.md +222 -13
  2. package/dist/stdio-handler.js +1809 -444
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -111,12 +111,15 @@ 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), with the app's trigram matching. 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 prefix counting half) 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 (as an example only, correct hits on real memories have had a `semanticScore` of 0.42), 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. `query` is optional when `category` or `entity` 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` or `entity` filter. A record that fails to decrypt or verify is skipped and counted (`unverifiable`), never shown. |
115
- | `remember_memory` | Saves one memory (`text`, `category`, `entity`, optional `tags`, `sourceNoteId`). It is never pinned: only you pin, in the app. Returns near-duplicates so the agent can supersede instead of adding a copy. |
116
- | `supersede_memory` | Replaces an active memory: 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. Both records are written unpinned, even if the old one was pinned. |
117
- | `invalidate_memory` | Marks an active memory as wrong. The text is kept; the memory is written unpinned. |
118
- | `get_memory_profile` | No inputs. The memories you have pinned (payload field `pinned`; only you pin, in the app), active ones only, most recently updated first (ties by id), cut at whole memories once text plus entity passes about 300 tokens (characters ÷ 4); the first is always included. Each item carries `needsReview`, `reviewedAt` and `provenance`. With nothing pinned it says that only you pin, in the app, and to list your preferences with `search_memory` (`category: "preference"`, no query) instead; the tool description and the server's instructions say the same, since a new store has nothing pinned. Also the resource `memory://profile`, with the same content, and named in the server's instructions so an agent loads it at the start of a session. Reads only the list, like `search_memory`. |
119
- | `import_memories_from_note` | Turns a note (`noteId`) into candidates, one per list item and one per paragraph, with the heading above as the entity and `category` (default `entity_fact`) on each. Left out: struck-through text (`~~x~~` or `~x~`; a candidate struck through entirely is dropped), checked tasks (`[x]`) with everything nested under them, thematic breaks, and everything under a heading for undecided content until the next heading (ATX or setext) of the same or a higher level. Those headings start with "Open questions", "Questions", "Not decided", "Undecided", "Discussed but not decided", "Ideas", "Todo", "To do", "Parking lot" or "Scratch", case-insensitive, singular or plural, with or without a leading number ("3. Open question", "TODOs"); a line that is only bold text ("**Open questions**") counts as such a heading until the next heading or bold-only line. The match is a deliberately broad prefix match that errs on the side of skipping: "Ideas for the launch" and "Questions answered" are skipped too; only a heading that does not start with one of these words is kept ("Scratchpad", "Decided ideas"). `dryRun` defaults to `true` (returns candidates only); with `dryRun: false` it writes up to 100. The note is never changed. |
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 of three or more characters that begins a memory word at most twice its length, so `penicil` half-matches "penicillin" but `ad` never matches "admin" and `end` never matches "endpoint") 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 (as an example only, correct hits on real memories have had a `semanticScore` of 0.42), 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
+ | `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
+ | `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
+ | `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. |
118
+ | `record_conflict` | Records that two active memories (`id`, `withId`) make competing claims, with a `reason` (1–500 characters): for when the agent cannot yet tell which is right. Both stay active, searched, ranked and filtered as before; each stores an entry `{ with, reason, recordedAt }` for the other inside its encrypted payload, and both then read as `disputed: true`. Both are flagged for review and written unpinned. Writes `id` first, then `withId`. Refused, with nothing written, for the same memory twice (before any request), a memory that is not active, a conflict already recorded on both, a memory already in 10 open conflicts, or a memory that would be too long to store once encrypted with the entry added and room left for any later single write (the widest reason, state, `supersededBy` and `modifiedBy` an invalidate, a resolve or a supersede adds), so those can still write it (its conflicts count toward the size, and a reason outside the Latin alphabet takes more room, so this can come before 10). Both sides are checked before anything is written. If the second write fails, the answer is an error that says the conflict is already in effect (the first side lists it) and that calling again completes it; calling again writes only the missing side. Answers `{ ids, written, disputed, needsReview }`. |
119
+ | `resolve_conflict` | Settles an open conflict: `supersedeId` becomes superseded by `keepId`, with `evidence` (1–500 characters) as its reason; its text and its record of the conflict are kept. `keepId` stays active, drops its entry for the other memory, keeps its other open conflicts, and is flagged. No new memory is written. Refused, with nothing written, for the same memory twice (before any request), a memory that is not active, or two memories with no open conflict between them. Writes the loser first; if the kept memory's write then fails, the answer is not an error: `keptUpdated` is `false`, with a `note` saying the resolution took effect. Answers `{ keptId, supersededId, keptUpdated, needsReview, note }`. |
120
+ | `memory_history` | Read-only. The server's change history of your memories: one entry per write (`create`, `update`, `supersede`, `delete`), oldest first, from `GET /public/memory/history`. Optional `since` (an ISO 8601 date, read as UTC midnight, or a date-time with seconds and `Z` or an offset; inclusive), `id` (one memory, deleted ones included), `entity` (case-insensitive, matched on either snapshot on your machine and never sent; a delete has no snapshot, so filter by `id` to see one), `limit` (1–50, default 20) and `cursor` (the previous call's `nextCursor`, with the same filters). Answers `{ entries, nextCursor, unverifiable }`; each entry has `at`, `operation`, `actor` (`{ kind: "app", keyPrefix: null }` for a write from the app, `{ kind: "api-key", keyPrefix }` for a write through an API key, whose `keyPrefix` is the key's first 12 characters as shown in Settings → API & Data, or `null` if the server could not read it), `id`, `relatedId` (a supersede's other memory), `revisionBefore`, `revisionAfter`, and `before`/`after`. See "Change history" below. |
121
+ | `get_context` | Read-only. One bounded briefing for the start of a session, which the server's instructions now tell an agent to call first. Optional `entity` (trim + lower-case, as `search_memory`), `tags` and `excludeTags` (`search_memory`'s rule), `decisionStatus` (default `["decided"]`, the decisions section only) and `since` (`memory_history`'s shape, and a real instant from year 0001; default the last 7 days; a malformed value is refused before any request). Answers `{ notice, since, profile, conflicts, decisions, due, changes, approxTokens, unverifiable }`: `profile` is exactly `get_memory_profile`'s answer without its notice (with a tag filter, only the pinned memories that pass); `conflicts` lists active memories in an open conflict, oldest conflict first, each with its `conflicts`; `decisions` the active decisions in `decisionStatus`, newest first; `due` has `stale` (most overdue first), `expiringSoon` (last valid day today to 7 days ahead in the memory's zone, soonest first) and `needsReview` (`{ count, oldestFlaggedAt }` only, since only you review); `changes` lists each memory written since `since`, newest last write first, with `writes`, `operations`, `lastAt`, `lastActor`, `deleted` and the memory as it is now (`null` when deleted or not loaded). `since` is echoed. See "Session briefing" below. |
122
+ | `get_memory_profile` | No inputs. The memories you have pinned (payload field `pinned`; only you pin, in the app), active ones only, most recently updated first (ties by id), cut at whole memories once text plus entity passes about 300 tokens (characters ÷ 4); the first is always included. References, and decisions that are not decided, are left out even when pinned, before the budget is counted. Each item carries `needsReview`, `reviewedAt`, `provenance`, `decision`, `createdAt`, `createdBy`, `modifiedBy`, `origin`, `sourceRef`, `validUntil`, `validUntilZone`, `stale`, `overdueDays`, `disputed` and `conflicts` as `search_memory`'s results do. With nothing pinned it says that only you pin, in the app, and to list your preferences with `search_memory` (`category: "preference"`, no query) instead; the tool description and the server's instructions say the same, since a new store has nothing pinned. Also the resource `memory://profile`, with the same content. The server's instructions point an agent at `get_context` at the start of a session, which includes this profile, and say the profile alone still works. Reads only the list, like `search_memory`. |
120
123
 
121
124
  - **Every agent write is live and flagged.** It sets `needsReview: true`,
122
125
  `author: 'agent'` and `flaggedAt` inside the ciphertext. `flaggedAt` (ISO
@@ -128,16 +131,174 @@ MCP does not (R-038).
128
131
  1), so older memories without it still open. A flagged memory is still searched
129
132
  and used: the flag is for you, not a gate (ADR-0418 §5). The flag is set by
130
133
  the MCP, so a modified client could leave it off (R-038).
134
+ - **Stale memories are flagged, never demoted** (features 0037 and 0039).
135
+ Every memory the tools return (search results, listings, near-duplicates,
136
+ profile items) carries `validUntil` (the stored date, or `null` when there
137
+ is none or it cannot be read), `validUntilZone` (the IANA zone the date is
138
+ read in: the zone stored with it, else the default zone; `null` with no
139
+ date), `stale` (true once today's date in that zone is after `validUntil`)
140
+ and `overdueDays` (calendar days past it in that zone, `null` when not
141
+ stale). A memory dated 2027-04-20 in `Australia/Sydney` is not stale until
142
+ midnight starting 21 April in Sydney (2027-04-20T14:00Z, since Sydney is
143
+ +10 that day), and is 1 day overdue from then. Only calendar dates are
144
+ compared, so a daylight-saving change cannot make it a day out. Dates
145
+ written before zones existed have no stored zone and are read in the
146
+ default zone. `stale` is worked out on your machine at read time, for any
147
+ category and any state, and is never stored. It does not change the
148
+ ranking or the scores, so a stale memory can still come first: the
149
+ descriptions tell the agent to check `stale` before relying on it. The
150
+ date and zone are inside the encrypted payload (`v` stays 1), so the
151
+ server never sees them, and they are never logged. A stored date that is
152
+ not a real `YYYY-MM-DD` date is ignored (`null`), and a stored zone that is
153
+ not a known IANA name is read as no zone; the memory is still returned.
154
+ The app shows the date (with its zone when it is not the browser's), shows
155
+ "Out of date" on an active memory whose date has passed, and lets you set,
156
+ change or clear it.
157
+ - **Decisions and references** (feature 0043). Two categories join the
158
+ four. A `decision` is a choice with a status (`proposed`, `discussed`,
159
+ `decided`, `reversed` or `disputed`) and, optionally, a rationale, a day and
160
+ who reached it. By default `search_memory` returns decided decisions only,
161
+ alongside every other memory, and the profile includes a pinned decision
162
+ only when it is decided. A `reference` is a lookup value, such as a cloud
163
+ ID or a URL, filed under its key as the entity; it stays out of every
164
+ search and listing that does not ask for `category: "reference"`, and out
165
+ of the profile even when pinned. Every memory the tools return carries
166
+ `decision` (`null` unless the memory is a decision; otherwise `{ status,
167
+ rationale, date, by }`, any field `null` when not set or unreadable). The
168
+ status and details are inside the encrypted payload, so the server never
169
+ sees them, and none is logged. MCP versions before this one, and app tabs
170
+ on an older build, cannot read either category: they count such memories
171
+ as unverifiable.
172
+ - **Who wrote a memory, and where its claim came from** (feature 0044).
173
+ Every memory the tools return carries `createdAt` and `createdBy`
174
+ (`{ author, via, client, tool }`: who created it, written once and never
175
+ changed by a later write), `modifiedBy` (same shape: who last superseded,
176
+ invalidated, edited or restored it; `updatedAt` is the last write's time),
177
+ `origin` and `sourceRef`. A stored time (`createdAt`, `updatedAt`,
178
+ `reviewedAt`, `flaggedAt`) that is not an ISO instant, which only a writer
179
+ outside these builds and the app can store, reads `null` rather than
180
+ being passed on. Superseding or invalidating a memory, here or in
181
+ the app, no longer rewrites its `author` and `provenance`. Memories written
182
+ before this version carry `null` for the four new keys, and their `author`
183
+ and `provenance` may name whoever last changed them. Origin, writer and
184
+ source are self-asserted by whoever writes the memory, not verified; an
185
+ agent write is still flagged for review. A `sourceRef` is data, never
186
+ fetched or opened by the MCP or the app, and the descriptions tell agents
187
+ not to follow it on a memory's say-so. All of them are inside the encrypted
188
+ payload (`v` stays 1) and none is logged. A value of the wrong shape reads
189
+ as `null`; the memory is still returned. Older MCP versions and app tabs
190
+ keep the new keys on the memories they rewrite, but still overwrite
191
+ `author` and `provenance`, and a supersede or edit there loses `sourceRef`
192
+ on the new memory (R-087).
193
+ - **Conflicts between memories** (feature 0048). Every memory the tools
194
+ return carries `disputed` (true when it is in an open conflict) and
195
+ `conflicts` (its open conflicts, oldest first: `{ with, reason,
196
+ recordedAt }`, `with` being the other memory's id). A conflict is open
197
+ while both memories are active and either one lists the other, so a
198
+ half-written record still counts, and it ends when it is resolved or when
199
+ either memory is superseded or invalidated (a `supersede_memory` moves it
200
+ to the new memory). A memory that is not active is never disputed.
201
+ Disputed memories stay live: ranking and filters are unchanged. This is
202
+ not a decision's `disputed` status, which is a status on one decision;
203
+ neither conflict tool changes it. The entries are inside the encrypted
204
+ payload (`v` stays 1) and no reason or evidence is logged. A malformed
205
+ entry is ignored; the memory is still returned. Older MCP versions and app
206
+ tabs ignore the entries and show nothing disputed; their supersede or edit
207
+ writes the new memory without them, which ends the conflict (R-088).
208
+ - **Change history** (feature 0051). The server records every successful
209
+ memory write, from the app or through an API key, in the same transaction:
210
+ who (`app`, or `api-key` with the key's 12-character prefix, which names a
211
+ key, not who used it; the client and tool names stay in the encrypted
212
+ `createdBy`/`modifiedBy`), when, which operation, and the memory's
213
+ ciphertext before and after. `memory_history` decrypts each snapshot on
214
+ your machine under its own id and revision, so a snapshot moved to another
215
+ memory or revision does not open: it is `null` and counted in
216
+ `unverifiable`, as is an entry the server sent in the wrong shape. A
217
+ snapshot is the memory's stored fields (`text`, `category`, `entity`,
218
+ `tags`, `state`, `needsReview`, `pinned`, `author`, `reason`,
219
+ `supersedes`, `supersededBy`, `sourceNoteId`, `provenance`, `createdBy`,
220
+ `modifiedBy`, `origin`, `sourceRef`, `validUntil` and its stored
221
+ `validUntilZone`, `decision`, the stored `conflicts` and `updatedAt`), with
222
+ nothing computed from the clock or other memories (no `stale`, no
223
+ `disputed`). `before` and `after` are also `null` when there is none (a
224
+ create has no before, a delete neither) and once the memory is deleted in
225
+ the app, which erases its content from its history (the entries stay).
226
+ Only the snapshots are authenticated: `actor`, `operation`, `relatedId`
227
+ and `at` are asserted by the server, not authenticated by the encryption,
228
+ so a server that lied about who made a change or when would not be caught.
229
+ `at` is when the write's transaction started, so an entry can commit after
230
+ one with a later `at` and be missing from a page read just before: to read
231
+ new entries later, start `since` a little before the last `at` you read (a
232
+ minute, say) rather than resuming from a saved cursor, and skip the entries
233
+ you already have. The server also limits history reads to 60 a minute per
234
+ account (per server container), answered with a 429.
235
+ History entries are never returned as memories: `search_memory` and the
236
+ profile never read them, and no tool writes, changes or deletes them. With
237
+ `entity`, a call makes at most five requests, so fewer than `limit` entries
238
+ with a `nextCursor` means more may match; without it, one. History is
239
+ always fetched, never served from the 60 s list cache. The server keeps
240
+ an account's newest 1,000 entries and every entry from the last
241
+ 30 days, up to the newest 10,000; an older entry is removed by later
242
+ writes. Writes before it began recording have none. The log line carries the three counts only (no id, entity, `since`,
243
+ cursor, prefix or snapshot field).
244
+ - **Session briefing** (feature 0052). `get_context` puts together what an
245
+ agent would otherwise fetch in five or more calls at the start of a
246
+ session: the pinned profile, then the flags (open conflicts, decisions in
247
+ effect, memories past or near their `validUntil`, and how many wait for
248
+ your review), then what changed since `since` (pass the end of the last
249
+ session; the default is the last 7 days). Each list section holds at most
250
+ 10 memories (`changes` 20), and outside the profile, which keeps its own
251
+ 300 tokens, all sections share about 2,000 tokens (each item's text,
252
+ entity, tags, a decision's rationale and `by`, and each of its conflicts,
253
+ reason, other id and time, and its `updatedAt`, characters ÷ 4), filled in the order conflicts, decisions, stale,
254
+ expiring, changes and cut at whole memories: a memory too large for what is left is skipped and counted in `omitted`,
255
+ and the next one is tried. Each section says how many matched (`total`) and
256
+ how many it left out (`omitted`); a memory in two sections counts twice.
257
+ Items are compact (`id`, `text`, `category`, `entity`, `tags`, `state`,
258
+ `needsReview`, `pinned`, `decision`, `validUntil`, `validUntilZone`,
259
+ `stale`, `overdueDays`, `disputed`, `updatedAt`); `search_memory` returns
260
+ every field. `entity` narrows every section but the profile; tags narrow
261
+ every section and are a convenience, not access control;
262
+ there is no `scope` filter yet. References are never included, in any section.
263
+ `decisionStatus` narrows only the decisions section, so a proposed decision
264
+ that is disputed or out of date is still flagged. `changes` reads the
265
+ server's history (at most five pages of 50, oldest first): `complete` is
266
+ `false` when there was more, which means the most recent changes are the
267
+ ones missing, so call again with a later `since`. If the history cannot be
268
+ read (a network error, a server without the history route, a 5xx),
269
+ `available` is `false` with a fixed note and the rest of the briefing is
270
+ still returned; a rejected key (401) or an account no longer Pro fails the
271
+ call, as every memory tool does. It writes nothing, uses the 60 s list
272
+ cache, and logs one line of counts (no text, entity, tag, `since`, id, key
273
+ prefix or reason).
131
274
  - **Agents cannot delete or pin memories.** No tool sends a `DELETE`, and
132
275
  `/public/memory` has no delete route. No agent write is pinned, so a pinned
133
276
  memory that an agent supersedes or invalidates leaves your profile until
134
277
  you pin it again (product owner, 2026-10-12). You delete and pin them in
135
278
  the app.
136
- - **Search matches ASCII letters and digits only**, as the app's search does:
137
- accented and non-Latin letters are ignored, so text written only in them
138
- cannot be found, and near-duplicate detection cannot see it. A query with no
139
- searchable characters says so.
140
- - **Up to 60 s stale.** Search and the profile reuse the decrypted list for up
279
+ - **Search ignores case and accents on Latin letters**, as the app's search
280
+ does: `cafe` finds "Café", `strasse` finds "Straße", and near-duplicate
281
+ detection compares them the same way. Word matching works in any script:
282
+ Greek, Cyrillic or Korean by words, and Chinese, Japanese, Thai, Lao, Khmer
283
+ and Myanmar, written without spaces, by pairs of characters (a
284
+ one-character query counts half for each pair holding it), so a memory
285
+ in any of them can be found by its words and is compared for
286
+ near-duplicates. A hyphenated word matches whole (`pihole` or `Pi-hole`),
287
+ and each of its parts counts half; a hyphenated query word also counts
288
+ half, once per memory, where its parts are written apart as consecutive
289
+ words in the same order (`end-to-end` finds "end to end tests", ranked
290
+ below "end-to-end tests", but not "moved to Leeds at the end of June"),
291
+ and the same holds for near-duplicates and the supersede check; a query word of one or two letters
292
+ matches only that whole word, or a hyphenated word's part of the same
293
+ spelling (half). Still not matched: other forms of a word
294
+ (`тёмная` does not find "тёмную", `live` finds "lives" only by the
295
+ half-word rule, and a two-syllable Korean query such as `서울` does not
296
+ find "서울에", where a particle is attached), and accents on letters of other scripts still count
297
+ (`σκυλος` does not find "σκύλος"). A query with no letter or digit in any
298
+ script says so. `search_notes` and `search_note_content` are unchanged:
299
+ they also ignore case and Latin accents, and other scripts match there as
300
+ typed.
301
+ - **Up to 60 s stale.** Search, the profile and `get_context` reuse the decrypted list for up
141
302
  to 60 s, so a change made in the app, or a revoked key, can take up to 60 s
142
303
  to show in a running session (product owner, 2026-10-12; R-036). Writes
143
304
  from this process, and a rejected key, clear it at once.
@@ -172,6 +333,9 @@ opt in, change `args` to `["-y", "@squirrelnotes.app/mcp-embeddings"]` and add
172
333
  - Tools, inputs and output keys are identical (`ranking` says `hybrid` when
173
334
  meaning was used). If the model is refused or
174
335
  cannot load, search is this package's lexical search.
336
+ - A hit holding every query word still ranks above every hit that does not,
337
+ and age discounts only the meaning part of a hit's score; the companion's
338
+ README gives the formula.
175
339
 
176
340
  This package has no ML dependency: `onnxruntime-node` is installed only by the
177
341
  companion (ADR-0442).
@@ -417,7 +581,8 @@ tail -f /tmp/squirrel-mcp.log
417
581
  Each line goes to stderr and, when `SQUIRREL_LOG_FILE` is set, is also appended to that file.
418
582
 
419
583
  - `upload_attachment_from_path` progress: **the local file path it reads**, which can contain a plaintext filename; the file's size and MIME type; the new attachment id; the S3 PUT status code; and the confirmed attachment id. Leave `SQUIRREL_LOG_FILE` unset if those paths should not be kept on disk.
420
- - Memory tools: the tool name, memory ids, counts (memories searched, results, unverifiable records, imports created, profile items and omitted) and, on failure, the HTTP status or `network`. Never memory text, entities, tags or reasons.
584
+ - Memory tools: the tool name, memory ids, counts (memories searched, results, unverifiable records, profile items and omitted) and, on failure, the HTTP status, or `network` with the cause's error code when Node gives one (for example `network (ECONNREFUSED)`). Never memory text, entities, tags, reasons, `validUntil` dates or zones, a decision's status, rationale, date or decidedBy, or an origin or `sourceRef`. A refusal logs a fixed code only (for example `remember_memory refused (decision-without-status)`).
585
+ - One start-up line when `SQUIRREL_TIMEZONE` is set to a name this machine does not know. It names the variable only, never its value or the machine's zone.
421
586
  - With the embeddings companion only: one start-up line saying whether local
422
587
  embeddings are ready or were not loaded (with a reason and, at most, a file
423
588
  name), and, once, a runtime or vector-file failure. Never a vector or a query.
@@ -425,9 +590,52 @@ Each line goes to stderr and, when `SQUIRREL_LOG_FILE` is set, is also appended
425
590
 
426
591
  Not logged:
427
592
 
428
- - An S3 PUT failure. The tool throws it, with S3's status and response body, and the MCP client shows it as the tool's error. The log has only the status line above.
593
+ - An S3 PUT failure. The tool throws it as `S3 upload failed (<status>)`, adding S3's error code when the response names one (for example `S3 upload failed (403 SignatureDoesNotMatch)`), and the MCP client shows it as the tool's error. The rest of S3's response (its message, the object key, the signed request) is never in the error or the log. The log has only the status line above. A PUT that gets no answer at all is thrown as `storage PUT (attachment upload) → no response (…)` with the cause's error code (see [Troubleshooting network errors](#troubleshooting-network-errors)); the upload URL is never in it.
429
594
  - A wrong passphrase. It is no longer caught at startup: the key is derived on the first tool call, and a wrong passphrase fails that call (and every later one) with an error returned to the client.
430
595
  - The passphrase, the API key, the data key and any decrypted content.
596
+ - A share token. An error from `update_share_settings`, `republish_share` or `revoke_share` names the path as `/public/shared-notes/{token}/…`, and the token is taken out of the server's answer too.
597
+
598
+ ### Troubleshooting network errors
599
+
600
+ When a request gets no HTTP answer, the tool error names the error code Node reports and says what it means, for example:
601
+
602
+ ```
603
+ Squirrel API GET /public/notes → no response (network error: UNABLE_TO_GET_ISSUER_CERT_LOCALLY — Node does not trust the server's TLS certificate; …)
604
+ ```
605
+
606
+ The memory tools put the same `(network error: …)` part in their own sentence, which adds that nothing is known to have been written. Only the code is shown, never the underlying error's message, which can contain URLs, host names or certificate details. A code Node adds later is named without an explanation; `network error, cause unknown` means Node gave no code.
607
+
608
+ **A certificate your browser trusts but Node does not.** `NODE_EXTRA_CA_CERTS` is only for **your own locally trusted certificate**, such as an `mkcert` certificate for an API you run on this machine. Against the hosted service (`https://api.squirrelnotes.app`) an untrusted certificate means the connection may be intercepted: do not add a CA to make the error go away; find out what is between you and the server first.
609
+
610
+ For your own certificate: Node ignores the operating system's certificate store, so add the CA file to the server's `env` in your MCP client config:
611
+
612
+ ```json
613
+ "env": {
614
+ "SQUIRREL_API_BASE_URL": "https://localhost:3001",
615
+ "NODE_EXTRA_CA_CERTS": "/path/to/rootCA.pem"
616
+ }
617
+ ```
618
+
619
+ For `mkcert`, the file is `rootCA.pem` in the directory `mkcert -CAROOT` prints. Node versions that support the `--use-system-ca` flag can read the system store instead, but `NODE_EXTRA_CA_CERTS` works on every supported version and is the one to use.
620
+
621
+ | Code | Meaning |
622
+ |---|---|
623
+ | `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `UNABLE_TO_GET_ISSUER_CERT`, `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, `SELF_SIGNED_CERT_IN_CHAIN`, `DEPTH_ZERO_SELF_SIGNED_CERT`, `CERT_UNTRUSTED` | Node does not trust the server's certificate. For your own local certificate, set `NODE_EXTRA_CA_CERTS` as above; for the hosted service, do not add a CA (the connection may be intercepted). |
624
+ | `CERT_HAS_EXPIRED` | The server's certificate has expired. |
625
+ | `CERT_NOT_YET_VALID` | The certificate is not valid yet; check this machine's clock. |
626
+ | `ERR_TLS_CERT_ALTNAME_INVALID` | The certificate does not name the host in `SQUIRREL_API_BASE_URL`. |
627
+ | `ERR_SSL_WRONG_VERSION_NUMBER`, `ERR_SSL_PACKET_LENGTH_TOO_LONG` | The server did not answer in TLS: `SQUIRREL_API_BASE_URL` probably says `https://` for a port that serves plain HTTP. Check its scheme and port. |
628
+ | `ECONNREFUSED` | Nothing is listening at that host and port; check the API is running and the URL is right. |
629
+ | `ENOTFOUND` | The host does not resolve; check the URL and DNS. |
630
+ | `EAI_AGAIN` | The DNS lookup failed for now; check the network, then retry. |
631
+ | `EHOSTUNREACH` | There is no route to the host; check the URL and the network, VPN or firewall. |
632
+ | `ENETUNREACH` | This machine has no route to the server's network; check its connection or VPN. |
633
+ | `ETIMEDOUT`, `UND_ERR_CONNECT_TIMEOUT` | The connection timed out; check the network, proxy or firewall. |
634
+ | `UND_ERR_HEADERS_TIMEOUT` | The server accepted the connection but sent no response in time; retry later. |
635
+ | `ECONNRESET`, `UND_ERR_SOCKET` | The connection closed before the server answered; retry later. |
636
+ | `ERR_INVALID_URL` | `SQUIRREL_API_BASE_URL` is not a valid URL. |
637
+
638
+ The attachment upload's storage PUT goes to the upload URL the API returns, not to `SQUIRREL_API_BASE_URL`, so every code whose sentence names that variable says something else for it: the host and connection codes say to check the network, the two `ERR_SSL_` codes that the API may have the wrong scheme for its storage endpoint.
431
639
 
432
640
  ---
433
641
 
@@ -439,4 +647,5 @@ Not logged:
439
647
  | `SQUIRREL_API_KEY` | ✅ | Your API key from Settings → API & Data (requires Pro tier) |
440
648
  | `SQUIRREL_PASSPHRASE` | ✅ | Your encryption passphrase — never leaves your machine |
441
649
  | `SQUIRREL_LOG_FILE` | — | Absolute path to a log file. When set, all stderr output is also appended to this file. |
650
+ | `SQUIRREL_TIMEZONE` | — | The default zone for memory `validUntil` dates: an IANA name such as `Australia/Sydney`, used when an agent gives a date without `timezone`, and to read dates stored without a zone. Unset or empty: the machine's zone. Set it on a host that runs on UTC (a server or container) so dates follow your own calendar. An unknown value logs one line naming the variable and falls back to the machine's zone. Read once at start-up. |
442
651
  | `SQUIRREL_MEMORY_EMBEDDINGS`, `SQUIRREL_MEMORY_MODEL_DIR`, `SQUIRREL_MEMORY_CACHE_DIR` | — | Read only by the opt-in embeddings companion (`@squirrelnotes.app/mcp-embeddings`); see its README. |