@squirrelnotes.app/mcp 2.1.0 → 2.1.1-test.341

package/README.md

@@ -12,10 +12,12 @@ The passphrase lives in `claude_desktop_config.json` on your machine and is pass
 
 | Risk | Mitigation |
 |------|------------|
-| Passphrase in config file | Stored on disk in a local config file; protect it with OS user permissions and full-disk encryption |
-| Passphrase in process memory | Env var; cleared when process exits |
+| Passphrase in config file | Stored on disk in a local config file; protect it with OS user permissions and full-disk encryption. Anyone who can read this file has your passphrase. |
+| Passphrase and key in process memory | The process derives your data key once, on its first tool call, and holds it in memory until the process exits, even while it is idle between requests. The MCP server never writes it to a file or a log. The operating system can still put it on disk, through swap or a crash dump, and a debugger running as your user can read it, as all of these could already read the passphrase in the process's environment. |
 | Decrypted content visible to AI | This is the intended behaviour — AI agents need to read your notes |
 
+**Ending a running session.** Because the stdio process holds your data key for its whole life, **changing your passphrase in the app does not stop a session that is already running.** A passphrase change only re-wraps the key; it does not change it. To end a running session, **revoke or rotate the API key** (Settings → API & Data). An idle process keeps the key until its next request that reaches the API-key guard. On that request the server rejects the key and the process drops it (the reference is released, not zeroed). A request that fails before the guard (a 400 or 413 from the body parser, an API Gateway 429, or a 5xx) does not drop the key, but serves no data. The process drops the key when the server answers 401 "Invalid API key" (a missing, unknown, revoked or rotated key), or 403 "API access requires a Pro subscription" (the key is valid but the account is no longer Pro). **After a revoked or rotated key**, every later call fails until the process is restarted with a valid key. **After a Pro lapse** the key is still valid, so every call fails only while the account is not Pro: once you subscribe again, the next call derives your data key afresh and the session works again, without a restart. A 403 that a route raises for another reason, such as a shared note you do not own, leaves the key held. Quitting the MCP client also ends the process.
+
 ---
 
 ## Tools
@@ -31,7 +33,7 @@ The passphrase lives in `claude_desktop_config.json` on your machine and is pass
 | `update_note` | Updates title, content, or pinnedAt on a note. |
 | `delete_note` | Soft-deletes a note (recoverable). |
 | `pin_note` | Pins or unpins a note (appears at top of sidebar). |
-| `append_to_note` | Appends markdown content to an existing note. Avoids race conditions vs get → update. |
+| `append_to_note` | Appends markdown content to an existing note. Saves the agent a get → update, but it is **not** race-free: it reads the note and writes it back whole, and the server has no version check, so an edit made elsewhere in between is overwritten. |
 | `set_note_tags` | Replaces all tags on a note. |
 | `search_notes` | Fast title-only search across all notes. |
 | `search_note_content` | Full-content search (slow — decrypts all notes). Use only when title search fails. |
@@ -55,6 +57,84 @@ The passphrase lives in `claude_desktop_config.json` on your machine and is pass
 | `delete_attachment` | Permanently deletes an attachment from S3 and the database. |
 | `upload_attachment_from_path` | Uploads a file from a local path — **no file bytes in context**. Use after `write_file` (Filesystem MCP) to attach Claude-generated files. See [Filesystem MCP companion](#filesystem-mcp-companion-stdio-only) below. |
 
+### Memory (Pro, feature 0031)
+
+Short, atomic memories about you that an agent can recall in later sessions.
+Each memory is encrypted on your machine under your data key, bound to its id
+and revision (AES-GCM with AAD `sqn-memory-v2:<id>:<revision>`), so the server
+stores only ciphertext. Someone holding only your API key cannot put an older
+version back, or another memory's ciphertext in its place: it does not open.
+**What this does not stop:** the server, or whoever operates it, returning a
+whole older row (its ciphertext *and* its older revision). That opens, and
+undoes later changes, because this MCP keeps no record of the revisions it has
+seen. The app (PR 1b) will notice a revision lower than the one it cached; the
+MCP does not (R-038).
+
+| Tool | Description |
+|------|-------------|
+| `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. 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. A record that fails to decrypt or verify is skipped and counted (`unverifiable`), never shown. |
+| `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. |
+| `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. |
+| `invalidate_memory` | Marks an active memory as wrong. The text is kept; the memory is written unpinned. |
+| `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. 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`. |
+| `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. `dryRun` defaults to `true` (returns candidates only); with `dryRun: false` it writes up to 100. The note is never changed. |
+
+- **Every agent write is live and flagged.** It sets `needsReview: true`,
+  `author: 'agent'` and `flaggedAt` inside the ciphertext. `flaggedAt` (ISO
+  8601 UTC) is when the memory was flagged: the app's review badge counts 24
+  hours from it (ADR-0419 §4) and clears it to `null` when you review. A new
+  memory gets now. Superseding or invalidating a memory that is already
+  flagged keeps its time, and a supersede's new memory inherits it, so an
+  agent cannot restart the clock. It is optional in the payload (`v` stays
+  1), so older memories without it still open. A flagged memory is still searched
+  and used: the flag is for you, not a gate (ADR-0418 §5). The flag is set by
+  the MCP, so a modified client could leave it off (R-038).
+- **Agents cannot delete or pin memories.** No tool sends a `DELETE`, and
+  `/public/memory` has no delete route. No agent write is pinned, so a pinned
+  memory that an agent supersedes or invalidates leaves your profile until
+  you pin it again (product owner, 2026-10-12). You delete and pin them in
+  the app.
+- **Search matches ASCII letters and digits only**, as the app's search does:
+  accented and non-Latin letters are ignored, so text written only in them
+  cannot be found, and near-duplicate detection cannot see it. A query with no
+  searchable characters says so.
+- **Up to 60 s stale.** Search and the profile reuse the decrypted list for up
+  to 60 s, so a change made in the app, or a revoked key, can take up to 60 s
+  to show in a running session (product owner, 2026-10-12; R-036). Writes
+  from this process, and a rejected key, clear it at once.
+- **Memory text is data, not instructions.** The server instructions and every
+  memory tool description tell the agent so, and to treat a memory as
+  unverified while `needsReview` is true. Results carry `author`,
+  `provenance` (`via`, the client's self-asserted name, capped at 100
+  characters, and the tool) and `reviewedAt`.
+- **Limits.** An account holds up to 5,000 memories and 4 MiB of memory
+  ciphertext; past either, writes return a clear "limit reached" error. Writes
+  are limited to 120 a minute per user, per route, per Lambda container
+  (ADR-0418 §9b, R-042), so not an exact account-wide limit.
+- **Errors and logs never contain memory text.** Log lines carry the tool name,
+  ids, counts and HTTP status only.
+- **stdio only.** The memory tools exist only in this stdio package
+  (ADR-0421 removed the hosted HTTP server).
+
+#### Semantic memory search (opt-in)
+
+This package's `search_memory` is lexical. The separate package
+[`@squirrelnotes.app/mcp-embeddings`](https://www.npmjs.com/package/@squirrelnotes.app/mcp-embeddings) is this same
+server (built from the same source and published from the same commit) with a
+local embedding model, so `search_memory` also finds memories by meaning. To
+opt in, change `args` to `["-y", "@squirrelnotes.app/mcp-embeddings"]` and add
+`"ONNXRUNTIME_NODE_INSTALL": "skip"` to `env`.
+
+- The model runs in the MCP process on your machine. Memory text is not sent
+  anywhere to be embedded. Search results still go to your agent.
+- Vectors are kept only in an AES-256-GCM file in your OS cache directory,
+  mode `0600`. They are never sent, logged or returned.
+- Tools, inputs and output keys are identical. If the model is refused or
+  cannot load, search is this package's lexical search.
+
+This package has no ML dependency: `onnxruntime-node` is installed only by the
+companion (ADR-0442).
+
 ---
 
 ## Filesystem MCP Companion (STDIO only)
@@ -293,8 +373,20 @@ tail -f /tmp/squirrel-mcp.log
 
 #### What's logged
 
-- S3 PUT failures (HTTP status + response body from S3)
-- Fatal startup errors (missing env vars, wrong passphrase)
+Each line goes to stderr and, when `SQUIRREL_LOG_FILE` is set, is also appended to that file.
+
+- `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.
+- 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.
+- With the embeddings companion only: one start-up line saying whether local
+  embeddings are ready or were not loaded (with a reason and, at most, a file
+  name), and, once, a runtime or vector-file failure. Never a vector or a query.
+- Fatal startup errors: missing `SQUIRREL_API_KEY`, `SQUIRREL_PASSPHRASE` or `SQUIRREL_API_BASE_URL`, or a failure to connect the stdio transport.
+
+Not logged:
+
+- 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.
+- 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.
+- The passphrase, the API key, the data key and any decrypted content.
 
 ---
 
@@ -306,3 +398,4 @@ tail -f /tmp/squirrel-mcp.log
 | `SQUIRREL_API_KEY` | ✅ | Your API key from Settings → API Key (requires Pro tier) |
 | `SQUIRREL_PASSPHRASE` | ✅ | Your encryption passphrase — never leaves your machine |
 | `SQUIRREL_LOG_FILE` | — | Absolute path to a log file. When set, all stderr output is also appended to this file. |
+| `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. |