virlow-mcp 3.11.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Typelets Secure Notes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# virlow-mcp
+
+A local [MCP](https://modelcontextprotocol.io) server that gives any MCP-compatible AI
+client (Claude Code, Claude Desktop, Cursor, Codex, and others) durable memory and note
+access backed by [Virlow](https://virlow.com) — with your data end-to-end encrypted the
+entire time.
+
+## What it is
+
+virlow-mcp runs on your machine as a local process (`npx -y virlow-mcp`, launched by your
+AI client over stdio). It exposes 19 tools for two things:
+
+- **Memories** — short, durable facts ("the user prefers TypeScript", "this repo's CI
+  runs on self-hosted runners") that any AI tool can add, search semantically, and recall
+  across sessions and projects. Each memory is an ordinary encrypted note in your
+  **Memories** folder, so you can read, edit, reorganise, and trash them in the Virlow
+  app like anything else you have written.
+- **Notes** — full read/write access to your existing Virlow notes: search, list, read,
+  create, update, move, star, archive, and trash, plus folder management.
+
+Everything is **end-to-end encrypted, zero-knowledge**: the encryption key is derived
+from your Virlow master password inside this local process and never leaves it. Every
+memory and note is encrypted on your machine before it is sent to the Virlow API — the
+server stores only ciphertext. Decryption happens only in this local process, in memory —
+no decrypted text is ever written to disk.
+
+Your account credentials and master password are just as protected from the AI: they are
+entered exclusively into a local browser form served by this process, never passed
+through a tool call, and never seen by the AI model.
+
+## Install / configure
+
+virlow-mcp needs no separate install — `npx -y virlow-mcp` fetches and runs it directly.
+Add it to your client's MCP config:
+
+### Claude Code
+
+```
+claude mcp add virlow -- npx -y virlow-mcp
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "virlow": {
+      "command": "npx",
+      "args": ["-y", "virlow-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-local):
+
+```json
+{
+  "mcpServers": {
+    "virlow": {
+      "command": "npx",
+      "args": ["-y", "virlow-mcp"]
+    }
+  }
+}
+```
+
+### Codex CLI
+
+Codex's MCP config is TOML, not JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.virlow]
+command = "npx"
+args = ["-y", "virlow-mcp"]
+```
+
+### Self-hosting Virlow
+
+By default virlow-mcp talks to `https://api.virlow.com`. If you run your own Virlow API,
+point it there with an `env` block (JSON clients) or `env` table (Codex's TOML), e.g. for
+Claude Desktop / Cursor:
+
+```json
+{
+  "mcpServers": {
+    "virlow": {
+      "command": "npx",
+      "args": ["-y", "virlow-mcp"],
+      "env": { "VIRLOW_API_URL": "https://api.your-domain.com" }
+    }
+  }
+}
+```
+
+## First use
+
+1. Ask your AI client to run the **`unlock`** tool. This opens a browser window pointed
+   at a page served by the local virlow-mcp process — sign in with your Virlow account
+   email/password (and 2FA code, if enabled) and enter your master password there.
+2. Once the form succeeds, ask the AI to run **`status`** to confirm the vault is
+   unlocked and which account it's unlocked as.
+3. From then on, `add_memory`, `search_memory`, `search_notes`, and the rest of the tools
+   work normally until the vault locks again (see Security notes).
+
+## How memories are stored
+
+Memories live in a single folder marked as your memories root — shown with a brain icon
+in the app, and created by this process the first time you add one. Its **subfolders are
+namespaces**: `add_memory` with `namespace: "acme-api"` files the memory under
+`Memories/acme-api`, creating that subfolder if needed. Memories with no namespace sit in
+the root and are visible to every namespace's searches.
+
+Each memory is a **code note** holding YAML frontmatter above the fact itself:
+
+```
+---
+source: claude-code
+tags: [ui, preferences]
+confidence: high
+created: 2026-09-01T00:12:04.000Z
+---
+Prefers dark mode in every editor, including terminal themes.
+```
+
+The note's title is the memory's label. Because it is a code note, the app opens it in a
+plain text editor rather than the rich-text one, so nothing reformats it behind your back
+and every field is yours to edit.
+
+Everything about that is safe to change by hand:
+
+- **Edit the fact** and the next search reflects it — the memory re-embeds automatically.
+- **Edit the metadata** and the tools report your values.
+- **Break the YAML** and nothing is lost: the memory is simply read as all fact and no
+  metadata, still searchable, and the next `update_memory` rewrites it cleanly.
+- **Drag it to another subfolder** and its namespace follows.
+- **Trash it** and it stops being recalled, recoverable from Trash like any note.
+
+Deliberately *not* in the frontmatter: the memory's id, its label, and its namespace.
+Those are the note's id, its title, and the folder it sits in — duplicating them would
+just give you two versions to keep in sync.
+
+## Reaching your vault from a session that is not on this machine
+
+By default `virlow-mcp` speaks stdio, so your AI client spawns it as a child
+process and everything stays on one machine. `--http` serves the same 19 tools
+over HTTP instead, so a client that cannot spawn a local process — a cloud
+coding session, another laptop — can reach this vault:
+
+```bash
+npx -y virlow-mcp --http                 # loopback, random port
+npx -y virlow-mcp --http --port 8787     # pick the port
+```
+
+It prints the URL and the path to a bearer token, generated on first run and
+stored `0600` at `~/.virlow-mcp/http-token`. Every request must carry it:
+
+```
+Authorization: Bearer <token>
+```
+
+**Your vault does not move.** The master key is still derived and held in this
+process on your machine; `unlock` still opens its form in your local browser.
+Virlow's servers still see only ciphertext.
+
+**What does change:** decrypted note and memory text now travels over that
+connection to whatever client you point at it. So:
+
+- The listener binds `127.0.0.1` by default. `--host` will bind elsewhere and
+  warns loudly, because anyone who can reach the port and holds the token can
+  read your decrypted notes.
+- To reach it from outside, put your own tunnel in front of it
+  (`cloudflared`, `ssh -R`, Tailscale) rather than binding to `0.0.0.0`.
+- Treat the token like a password. Delete the file to rotate it; the next start
+  mints a new one.
+
+## Which folders AI tools can see
+
+Every folder in the Virlow app has an **"Expose to MCP"** switch — *"Let the
+local AI assistant read & edit this folder and its subfolders. Off by
+default."* This server now honours it. Until this version it did not, so the
+app was telling you something untrue: the switch saved a value that nothing
+ever read.
+
+- A folder is visible when **it or any ancestor** is switched on, matching what
+  the label promises. Turning a parent on opens everything beneath it.
+- `read_note` respects it too. Knowing a note's id is not consent.
+- The **Memories** folder is exempt — this server creates it and it exists only
+  for AI tools.
+- A note in **no folder** is not visible: exposure is granted per folder, and
+  nothing has granted it. File it into an exposed folder to include it.
+
+**Filtering is never silent.** Any result that withheld something says so, with
+the count and what to do about it:
+
+```
+(4 notes hidden in folders that are not exposed to MCP. Turn on "Expose to MCP"
+in a folder's settings in the Virlow app to include it.)
+```
+
+A shortened list is otherwise indistinguishable from an empty vault, and you
+would have no reason to suspect a setting. Since the switch is off by default,
+expect to see this until you turn some folders on — that is the setting
+working, not a fault.
+
+## Turning memories off
+
+Memories are **opt-in**. The switch lives in the Virlow app under
+**Settings → Security → AI memories**, and it is off until you turn it on. With
+it off, every memory tool refuses:
+
+```
+AI memories are switched off for this account. Turn on "AI memories" in
+Settings → Security in the Virlow app to use this tool.
+```
+
+The setting is re-read from your account on **every** memory tool call, never
+cached for the session. Turning it *on* being slow would be an inconvenience;
+turning it *off* being slow would be a privacy control that does not work — you
+would switch it off, keep being recorded, and have no way to tell. If the
+account cannot be reached, the tools refuse rather than assume consent.
+
+`--no-memories` additionally starts the server with the five memory tools
+unregistered, so they do not appear in `tools/list` at all:
+
+```bash
+npx -y virlow-mcp --no-memories
+```
+
+Use it when you want a connector that structurally cannot touch memories,
+regardless of the account setting. Notes tools, `unlock`, `lock`, and `status`
+are unaffected either way (14 tools instead of 19).
+
+## Suggested agent rules
+
+Drop this into your client's persistent instructions (`.cursorrules`, `CLAUDE.md`,
+Codex's `AGENTS.md`, etc.) so the AI uses memory proactively instead of only when asked:
+
+```
+You have Virlow memory tools. At the start of a task, call search_memory
+with the task topic to recall relevant facts. When you learn a durable
+fact about the user, their preferences, or this project (a decision, a
+convention, a gotcha), store it with add_memory — one concise fact per
+call, a short label describing it, and namespace set to the project name
+for project-specific facts. Do not store secrets, credentials, or
+transient details.
+```
+
+## Security notes
+
+- **What's stored where.** The Virlow API stores only ciphertext: encrypted note titles
+  and content, memories included. The plaintext-looking `title`/`content` columns for
+  encrypted notes hold a literal `[ENCRYPTED]` placeholder, not your data. No decrypted
+  text ever touches disk — decryption happens in this process's memory only, per tool
+  call, and is discarded when the vault locks. Folder names are the one exception, and
+  always have been: they are stored in the clear, so a namespace name is visible to the
+  server even though everything in it is not.
+- **Embedding cache.** Search vectors are cached in `~/.virlow-mcp/cache` so a session
+  starts without re-embedding every memory. The file is a single AES-GCM blob under your
+  master key — note ids and timestamps included — and its name is a hash of your user id.
+  Without your master password it is unreadable, and if it cannot be decrypted (say after
+  a password change) it is silently discarded and rebuilt. It holds vectors only, never
+  the text they came from.
+- **Credentials never reach the AI.** Login, master password, and any 2FA code are typed
+  into the local browser form (served on `127.0.0.1` with a random one-time nonce) and
+  go straight from your browser to this process and the Virlow API. No tool call ever
+  carries a password, and the AI model never sees one.
+- **Auto-lock.** The vault locks automatically after 4 hours of inactivity, and
+  immediately on explicit `lock`. Locking discards the in-memory decryption key and all
+  cached memories/notes; any further tool call fails until you `unlock` again. An
+  operation still in flight when the vault locks cannot write its results back in
+  afterwards.
+- **Model download.** Semantic search over memories runs a small, public embedding
+  model (`Xenova/all-MiniLM-L6-v2`, ~30MB of open ONNX weights, pinned to a fixed
+  revision) entirely locally via `@huggingface/transformers`. It downloads once, on the
+  first memory-tool call, into `~/.virlow-mcp/models`, and is reused after that. This
+  model only ever processes your already-decrypted plaintext locally to produce a
+  vector — it sends nothing anywhere.
+- **Dedupe.** `add_memory` compares the new fact's embedding against existing memories
+  in the same scope (same namespace, or global). At cosine similarity ≥ 0.9 it updates
+  the closest match in place instead of creating a duplicate, carrying that memory's
+  existing metadata and creation date forward. Between 0.7 and 0.9 it stores the new
+  memory and tells the agent which existing ones it resembles. Only the label and the
+  fact are embedded — never the frontmatter, which is near-identical across every memory
+  and would otherwise distort these thresholds.
+- **Hidden notes.** Hidden notes never appear in `list_notes`/`search_notes` results; they
+  can still be read by exact id with `read_note`.