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

package/README.md

@@ -6,32 +6,17 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that
 
 ## ⚠️ Security Caveat — Read This First
 
-The MCP server necessarily decrypts your notes — that is its job. The security implications depend on which transport you use:
+The MCP server necessarily decrypts your notes — that is its job. It runs only as a local process on your machine (the stdio transport); there is no hosted MCP server.
 
-### stdio (local process) — recommended
-
-The passphrase lives in `claude_desktop_config.json` on your machine and is passed as an env var to the local process. It never leaves your machine, and decryption happens locally — similar to the standard Squirrel Notes app, where the passphrase is entered locally in the browser and not sent to the server. Compared with the Remote HTTP/Lambda transport below, stdio avoids sending your passphrase over the network, at the cost of storing it in a local config file.
+The passphrase lives in `claude_desktop_config.json` on your machine and is passed as an env var to the local process. It never leaves your machine, and decryption happens locally — similar to the standard Squirrel Notes app, where the passphrase is entered locally in the browser and not sent to the server. The cost is that the passphrase is stored in a local config file.
 
 | 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 |
 
-### Remote HTTP (Lambda)
-
-Your passphrase is sent over HTTPS to a Lambda function on every call.
-
-| Risk | Mitigation |
-|------|------------|
-| Passphrase sent over the network | HTTPS-only (API Gateway always TLS) |
-| Passphrase in server RAM during invocation | Stack-scoped variable; never assigned to module state; GC'd after invocation |
-| Passphrase in CloudWatch logs | Lambda code never logs headers |
-| Lambda container reuse retaining secrets | Passphrase is NOT module-scope — reused containers hold no residual secret |
-
-**You must trust:** AWS Lambda, the self-hosted MCP server code, and anyone with access to your CloudWatch logs.
-
-If this trade-off is not acceptable, use stdio transport instead.
+**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.
 
 ---
 
@@ -48,7 +33,7 @@ If this trade-off is not acceptable, use stdio transport instead.
 | `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. |
@@ -65,12 +50,90 @@ If this trade-off is not acceptable, use stdio transport instead.
 
 ### Attachments
 
-| Tool | Transport | Description |
-|------|-----------|-------------|
-| `list_attachments` | All | Lists all attachments for a note with decrypted filenames and metadata. |
-| `get_attachment_download_url` | All | Returns a presigned S3 download URL (expires in 5 minutes). |
-| `delete_attachment` | All | Permanently deletes an attachment from S3 and the database. |
-| `upload_attachment_from_path` | STDIO only | 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. |
+| Tool | Description |
+|------|-------------|
+| `list_attachments` | Lists all attachments for a note with decrypted filenames and metadata. |
+| `get_attachment_download_url` | Returns a presigned S3 download URL (expires in 5 minutes). |
+| `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).
 
 ---
 
@@ -142,28 +205,15 @@ Add both servers to `claude_desktop_config.json`:
 1. Claude calls `get_note(id)` (Squirrel MCP) to read the note
 2. Claude calls `write_file("/tmp/roadmap.md", content)` (Filesystem MCP)
 
-Every request requires two headers:
-
-```
-Authorization: Bearer sqn_<api_key>
-X-Passphrase: <your_passphrase>
-```
+The server needs an API key and your passphrase, both set as env vars in your client's config (see Setup). The API key is sent to the Squirrel Notes API in the `Authorization` header; the passphrase is never sent anywhere.
 
 Generate an API key in Squirrel Notes → Settings → API Key (requires Pro tier).
 
-Neither header is ever stored, cached, or logged by the server.
-
 ---
 
 ## Setup
 
-> **Which setup should I use?**
-> - **Claude Desktop** → use **stdio (recommended)** — no OAuth, passphrase stays on your machine
-> - **API automation / Cursor / other agents** → use **Remote HTTP (Lambda)**
-
----
-
-### Setup — Claude Desktop (stdio) ✅ Recommended
+### Setup — Claude Desktop, Cursor and other MCP clients (stdio)
 
 The stdio transport runs the MCP server as a local process on your machine. No OAuth, no network headers, no AWS account needed. Your passphrase is set as an env var in the config file and **never leaves your machine**.
 
@@ -232,47 +282,6 @@ Then reference the built file directly:
 
 ---
 
-### Setup — Remote HTTP (Lambda)
-
-Use this if you want to connect agents or tools that support remote HTTP MCP endpoints (Cursor, custom automations, etc.). This requires deploying to AWS and sending the passphrase over HTTPS on every call.
-
-#### 1. Deploy with CDK
-
-```bash
-cd infra
-npx cdk deploy SquirrelMcp
-```
-
-This creates:
-- A Lambda function running the MCP server Docker image
-- An HTTP API Gateway at `https://<id>.execute-api.<region>.amazonaws.com/mcp`
-
-The deployed URL is printed as a CDK output (`McpApiUrl`).
-
-#### 2. Configure your client
-
-```json
-{
-  "mcpServers": {
-    "squirrel-notes": {
-      "url": "https://<your-mcp-api-url>/mcp",
-      "headers": {
-        "Authorization": "Bearer sqn_<your_api_key>",
-        "X-Passphrase": "<your_passphrase>"
-      }
-    }
-  }
-}
-```
-
-> **Note:** Newer versions of Claude Desktop enforce OAuth 2.0 for remote HTTP servers and will reject this config. Use the stdio setup above for Claude Desktop.
-
-#### 3. Verify
-
-Ask Claude: *"List my Squirrel Notes"* — you should see decrypted note titles.
-
----
-
 ## Common Workflows
 
 Once configured, you can speak to Claude naturally. Some examples:
@@ -296,28 +305,15 @@ Once configured, you can speak to Claude naturally. Some examples:
 ## Local Development
 
 ```bash
-cd mcp
-npm install
-npm run dev
-```
-
-This starts an HTTP MCP server at `http://localhost:3002` pointing at the local backend (`http://localhost:3001`). No build step needed — `tsx` runs TypeScript directly.
-
-Smoke test with curl:
-
-```bash
-curl -s http://localhost:3002 -X POST \
-  -H "Authorization: Bearer sqn_<your_api_key>" \
-  -H "X-Passphrase: <your_passphrase>" \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .
+npm --prefix mcp install
+npm --prefix mcp run build      # builds dist/stdio-handler.js
+npm --prefix mcp test
 ```
 
-Or use the MCP Inspector for a browser UI:
+Point a client at `mcp/dist/stdio-handler.js` with `SQUIRREL_API_BASE_URL=http://localhost:3001` (the local backend), as in Option B above. Or open the MCP Inspector on it — set the three env vars in the Inspector's UI:
 
 ```bash
-npx @modelcontextprotocol/inspector http://localhost:3002
+make mcp-inspect
 ```
 
 ---
@@ -377,26 +373,29 @@ 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.
 
 ---
 
 ## Environment Variables
 
-### stdio transport
-
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `SQUIRREL_API_BASE_URL` | ✅ | Base URL of the Squirrel Notes backend API (e.g. `https://api.squirrelnotes.app`) |
 | `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. |
-
-### Lambda (HTTP) transport
-
-| Variable | Description |
-|----------|-------------|
-| `SQUIRREL_API_BASE_URL` | Base URL of the Squirrel Notes backend API |
-
-For Lambda, the API key and passphrase are passed per-request via `Authorization` and `X-Passphrase` headers — **not** environment variables.
+| `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. |