owlmem 0.4.0 → 0.6.0

package/README.md

@@ -2,6 +2,30 @@
 
 Command line for [OwlMem](https://owlmem.com) — shared memory and an end-to-end encrypted vault for your AI agents.
 
+## Connect your AI apps
+
+```sh
+npx -y owlmem install
+```
+
+Finds Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and Claude Desktop on this computer and adds
+OwlMem (`https://mcp.owlmem.com/mcp`) to each one. Config files are merged, not overwritten, and every file it
+changes is backed up first (`<file>.bak-owlmem-<time>`). It also adds a short "Team memory" rules block to
+`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` and `~/.gemini/GEMINI.md` (between `<!-- owlmem:start -->` markers).
+
+| Option | |
+|---|---|
+| `--dry-run` | show the plan, change nothing |
+| `--yes` | don't ask (when stdin isn't a terminal — an AI running it — it never asks) |
+| `--only claude-code,cursor` | only these apps (`claude-code`, `codex`, `cursor`, `vscode`, `vscode-insiders`, `windsurf`, `gemini`, `claude-desktop`) |
+| `--no-rules` | leave the instruction files alone |
+| `--uninstall` | remove the OwlMem entries and rules block again |
+
+Signing in is done by each app (standard MCP OAuth): the first time it uses OwlMem it opens the owlmem.com
+page, where you sign in and click **Allow**. AI agents can read the setup guide at https://mcp.owlmem.com.
+
+## Vault
+
 ```sh
 npx owlmem login            # paste the agent's token from the OwlMem console
 npx owlmem vault unlock     # paste your recovery code, once per machine
@@ -13,6 +37,13 @@ npx owlmem vault import bitwarden_export.json   # also 1Password / KeePass CSV,
 Vault items are encrypted on your machine with a key only you hold; OwlMem stores ciphertext it cannot read.
 Every read or write needs the space owner's approval in the console (passkey, authenticator app or GitHub).
 
+For unattended jobs (scheduled tasks, overnight deploys) the owner can set a **standing grant**: one agent, on one machine,
+may read chosen items or a folder without asking each time, until a set date (90 days at most), optionally only during set hours.
+Run `npx owlmem device` on that machine to register it and print its fingerprint. The program signs every vault request with a
+device key kept next to its config, so the same token on another machine gets nothing. By default a standing grant covers
+`owlmem run` / `vault_run` only (the secret goes into a command); viewing in plain text must be allowed separately.
+Saving, deleting and exporting always need approval.
+
 Let your AI use the vault directly through a local MCP server:
 
 ```sh
@@ -22,3 +53,6 @@ claude mcp add owlmem-vault -- npx -y owlmem mcp
 Tools: `vault_list`, `vault_run` (secrets are injected into the command and masked in its output), `vault_get`, `vault_put`.
 
 Requires Node 18+. No dependencies.
+
+`owlmem vault unlock` opens your browser only when talking to owlmem.com; set `OWLMEM_NO_BROWSER=1` (or `BROWSER=none`)
+to just print the link instead.

package/owlmem.mjs

@@ -5,6 +5,9 @@
 // server only ever sees ciphertext. Your space key comes from the recovery code shown once when the vault
 // was set up in the console; `owlmem vault unlock` stores it on this machine (0600).
 //
+//   owlmem install [--dry-run] [--yes] [--only a,b] [--no-rules] [--uninstall]
+//                                        connect Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and
+//                                        Claude Desktop on this computer to OwlMem (npx -y owlmem install)
 //   owlmem login                         save this agent's token (from the console)
 //   owlmem vault unlock                  paste the recovery code once per machine
 //   owlmem vault ls
@@ -15,20 +18,27 @@
 //   owlmem vault export [--format bitwarden-json|keepass-csv|env] > file
 //   owlmem run --env VAR=<name>[:field] [...] -- <command> [args]   run a command with secrets in its environment
 //   owlmem vault keygen                  (setup without a browser) print a new recovery code and its key check
+//   owlmem device                        register this machine and show its fingerprint (for standing grants)
 //   owlmem mcp                           local MCP server for your AI (vault_list, vault_run, vault_get, vault_put)
 //                                        e.g. claude mcp add owlmem-vault -- node ~/owlmem.mjs mcp
 //
 // Reading, writing, deleting and exporting need the space owner's approval in the console; this program waits
 // for it (up to 5 minutes). Secrets go to stdout only; messages go to stderr.
+//
+// Standing grants (for unattended jobs): the owner can let one agent, on one machine, read chosen items without
+// asking each time — until a set date, optionally only during set hours. This program signs every vault request
+// with a device key kept on this machine (device.json next to config.json), and says whether the secret goes into a
+// command (`owlmem run`, vault_run) or is shown (`vault get`, vault_get). A token copied to another machine has no
+// device key there, so standing grants don't apply. Writing, deleting and exporting always need approval.
 
 import { webcrypto as crypto } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
-import { homedir } from "node:os";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, copyFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
 import { join, dirname } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 
-export const VERSION = "0.4.0";
-const BASE = (process.env.OWLMEM_URL || "https://app.owlmem.com").replace(/\/$/, "");
+export const VERSION = "0.6.0";
+const BASE = (process.env.OWLMEM_URL || "https://owlmem.com").replace(/\/$/, "");
 const DIR = process.env.OWLMEM_HOME || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "owlmem");
 const enc = new TextEncoder(), dec = new TextDecoder();
 const say = (...a) => process.stderr.write(a.join(" ") + "\n");
@@ -111,6 +121,43 @@ export async function sealForMachine(pubkey, rawKey, space) {
   const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: enc.encode(space) }, await unlockAesKey(eph.privateKey, pub, space, "encrypt"), rawKey);
   return { epk: b64(new Uint8Array(await crypto.subtle.exportKey("raw", eph.publicKey))), nonce: b64(iv), ct: b64(new Uint8Array(ct)) };
 }
+// ── passkey unlock (browser only: navigator.credentials) ──
+// A passkey's PRF extension returns 32 bytes only that passkey can compute (the server never sees them). They're stretched (HKDF) into a
+// wrapping key that seals the vault key; OwlMem stores only the sealed box (vault_key_wraps). The page that calls these runs on owlmem.com.
+const b64url = (u8) => b64(u8).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const unb64url = (s) => { s = String(s).replace(/-/g, "+").replace(/_/g, "/"); while (s.length % 4) s += "="; return unb64(s); };
+async function prfWrapKey(prf) {
+  const k = await crypto.subtle.importKey("raw", prf, "HKDF", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(32), info: enc.encode("owlmem-vault-wrap-v1") }, k, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+const wrapAad = (space, user, credId) => enc.encode(space + "\n" + user + "\n" + credId);
+// challenge（可选）：服务器发的先验挑战。给了的话这一次刷 Passkey 同时就是「验明正身」——返回的 credential 交给服务器验签（10-24：导出要一步到位）
+export async function passkeyPrf(creds, challenge) {    // creds: [{cred_id, salt}] → {cred_id, prf, credential}
+  if (!globalThis.PublicKeyCredential) throw new Fail("This browser doesn't support passkeys.");
+  const map = Object.fromEntries(creds.map((c) => [c.cred_id, { first: unb64(c.salt) }]));
+  const prf = creds.length === 1 ? { eval: { first: unb64(creds[0].salt) } } : { evalByCredential: map };
+  const cred = await navigator.credentials.get({ publicKey: { challenge: challenge ? unb64url(challenge) : crypto.getRandomValues(new Uint8Array(32)), rpId: location.hostname, userVerification: "required",
+    timeout: 60000, allowCredentials: creds.map((c) => ({ type: "public-key", id: unb64url(c.cred_id) })), extensions: { prf } } });
+  const out = cred.getClientExtensionResults()?.prf?.results?.first;
+  if (!out) throw new Fail("This passkey can't unlock the vault (its device doesn't support the PRF feature). Use another passkey or the recovery code.");
+  const u = (b) => b64url(new Uint8Array(b));
+  return { cred_id: u(cred.rawId), prf: out, credential: { id: cred.id, type: cred.type, response: { clientDataJSON: u(cred.response.clientDataJSON),
+           authenticatorData: u(cred.response.authenticatorData), signature: u(cred.response.signature) } } };
+}
+export async function wrapVaultKey(prf, rawKey, space, user, credId) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: wrapAad(space, user, credId) }, await prfWrapKey(prf), rawKey);
+  return { nonce: b64(iv), wrapped: b64(new Uint8Array(ct)) };
+}
+export async function unlockWithPasskey(wraps, space, user, keyCheck, challenge) {   // → {raw, cred_id, credential}
+  const r = await passkeyPrf(wraps, challenge);
+  const w = wraps.find((x) => x.cred_id === r.cred_id);
+  const raw = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: unb64(w.nonce), additionalData: wrapAad(space, user, w.cred_id) }, await prfWrapKey(r.prf), unb64(w.wrapped)));
+  if (!(await verifyKeyCheck(raw, space, keyCheck))) throw new Fail("Passkey unlock is out of date (the vault was reset). Use the recovery code and set the passkey up again.");
+  return { raw, cred_id: w.cred_id, credential: r.credential };
+}
+export function newSalt() { return b64(crypto.getRandomValues(new Uint8Array(32))); }
+
 export async function openFromBrowser(privateKey, space, box) {
   const epk = await crypto.subtle.importKey("raw", unb64(box.epk), ECDH, false, []);
   const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: unb64(box.nonce), additionalData: enc.encode(space) }, await unlockAesKey(privateKey, epk, space, "decrypt"), unb64(box.ct));
@@ -132,11 +179,42 @@ function spaceKey(space) {
   return unb64(readFileSync(p, "utf8").trim());
 }
 
+// ── this machine's device key (standing grants are bound to it) ──
+// ECDSA P-256, made on first use, kept next to config.json (0600). The server only ever sees the public key and signatures.
+let DEVICE = null;
+async function device() {
+  if (DEVICE) return DEVICE;
+  const p = join(DIR, "device.json");
+  let d = null;
+  try { d = JSON.parse(readFileSync(p, "utf8")); } catch {}
+  if (!d || !d.pkcs8 || !d.spki) {
+    const kp = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+    d = { v: 1, spki: b64url(new Uint8Array(await crypto.subtle.exportKey("spki", kp.publicKey))), pkcs8: b64(new Uint8Array(await crypto.subtle.exportKey("pkcs8", kp.privateKey))), created: new Date().toISOString() };
+    saveFile(p, JSON.stringify(d, null, 2));
+  }
+  const key = await crypto.subtle.importKey("pkcs8", unb64(d.pkcs8), { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+  return (DEVICE = { spki: d.spki, key });
+}
+export async function deviceFingerprint(spki) {
+  const h = [...new Uint8Array(await crypto.subtle.digest("SHA-256", unb64(spki.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - spki.length % 4) % 4))))].map((x) => x.toString(16).padStart(2, "0")).join("").slice(0, 16).toUpperCase();
+  return h.match(/.{4}/g).join("-");
+}
+// mode: "run" = the secret goes into a command; "view" = it is shown (stdout / the AI's conversation); "other" = anything else
+async function signHeaders(method, path, mode) {
+  const d = await device();
+  const ts = String(Math.floor(Date.now() / 1000)), nonce = b64url(crypto.getRandomValues(new Uint8Array(18)));
+  const msg = ["owlmem-device-v1", method.toUpperCase(), new URL(BASE + "/v1/vault/" + path).pathname, mode, ts, nonce].join("\n");
+  const sig = new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, d.key, enc.encode(msg)));
+  return { "X-OwlMem-Device": d.spki, "X-OwlMem-Device-Name": (process.env.OWLMEM_DEVICE_NAME || hostname()).replace(/[^\w .@()-]/g, "").slice(0, 60),
+           "X-OwlMem-Mode": mode, "X-OwlMem-Time": ts, "X-OwlMem-Nonce": nonce, "X-OwlMem-Sig": b64url(sig) };
+}
+
 // ── http ──
-async function call(method, path, body) {
+async function call(method, path, body, mode = "other") {
   let r;
   try {
-    r = await fetch(BASE + "/v1/vault/" + path, { method, headers: { Authorization: "Bearer " + token(), "Content-Type": "application/json", "User-Agent": "owlmem-cli/" + VERSION },
+    const sh = await signHeaders(method, path, mode).catch(() => ({}));      // can't write the device key: no standing grants, everything else still works
+    r = await fetch(BASE + "/v1/vault/" + path, { method, headers: { Authorization: "Bearer " + token(), "Content-Type": "application/json", "User-Agent": "owlmem-cli/" + VERSION, ...sh },
                                                   body: body === undefined ? undefined : JSON.stringify(body) });
   } catch (e) { throw new Fail("Can't reach OwlMem (" + BASE + "): " + e.message); }
   const data = await r.json().catch(() => ({}));
@@ -144,10 +222,10 @@ async function call(method, path, body) {
 }
 // Ask, and if the owner has to approve, wait for it (polling every 3 s, up to 5 minutes), then ask again.
 let WAIT_MS = 5 * 60 * 1000;     // 命令行等 5 分钟；MCP 里只等 30 秒，免得 AI 客户端的工具调用超时
-async function approved(method, path, body, kind = "access") {
+async function approved(method, path, body, kind = "access", mode = "other") {
   let extra = "";
   for (let round = 0; round < 3; round++) {
-    const r = await call(method, path + extra, body);
+    const r = await call(method, path + extra, body, mode);
     if (r.status < 400) return r.data;
     if (r.data.error !== "approval_required") throw new Fail(r.data.detail || r.data.error || "HTTP " + r.status);
     const id = r.data.request;
@@ -159,7 +237,7 @@ async function approved(method, path, body, kind = "access") {
       st = (await call("GET", "requests/" + id)).data.status;
       if (st !== "pending") break;
     }
-    if (st === "pending") throw new Fail(`Waiting for approval (request ${id}). Ask the space owner to approve it in the OwlMem console (Vault), then try again.`);
+    if (st === "pending") throw new Fail(`Waiting for approval (request ${id}). Ask the space owner to approve it in the OwlMem console (Vault), then try again. For unattended jobs, ask them for a standing grant for this agent and this machine (run: owlmem device).`);
     if (st !== "approved") throw new Fail(st === "denied" ? "The request was denied." : "The request expired before it was approved.");
     say("Approved.");
     if (kind !== "access") extra = (path.includes("?") ? "&" : "?") + "request=" + encodeURIComponent(id);
@@ -274,6 +352,21 @@ export function guessCSV(text) {
 }
 // <<< vault core
 
+// ── opening a browser ──
+// Only for the real service: OWLMEM_NO_BROWSER=1 or BROWSER=none turns it off, and so does any OWLMEM_URL that isn't owlmem.com
+// (tests and local previews run on 127.0.0.1 — 10-24 a test run kept opening tabs in the owner's browser). The link is always printed.
+export function browserAllowed(env = process.env) {
+  if (env.OWLMEM_NO_BROWSER && env.OWLMEM_NO_BROWSER !== "0") return false;
+  if (String(env.BROWSER || "").toLowerCase() === "none") return false;
+  let host = "";
+  try { const u = new URL(env.OWLMEM_URL || "https://owlmem.com"); if (u.protocol !== "https:") return false; host = u.hostname; } catch { return false; }
+  return host === "owlmem.com" || host.endsWith(".owlmem.com");
+}
+function openBrowser(url) {
+  if (!browserAllowed()) return false;
+  try { spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open", [url], { stdio: "ignore", detached: true }).on("error", () => {}).unref(); return true; } catch { return false; }
+}
+
 // ── unlock via the console ──
 async function unlockInBrowser(space) {
   const kp = await unlockKeypair();
@@ -281,7 +374,7 @@ async function unlockInBrowser(space) {
   if (r.status >= 400) throw new Fail(r.data.detail || r.data.error);
   const fp = await unlockFingerprint(kp.pubkey);
   say("Open this link, sign in, and approve with your passkey:\n\n  " + r.data.url + "\n\nThe console will show a code — check it matches: " + fp + "\nWaiting (up to 10 minutes)…");
-  try { spawn(process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open", [r.data.url], { stdio: "ignore", detached: true }).on("error", () => {}).unref(); } catch {}
+  openBrowser(r.data.url);
   const wait = Number(process.env.OWLMEM_POLL_MS || 2000), until = Date.now() + 10 * 60 * 1000;
   while (Date.now() < until) {
     await new Promise((res) => setTimeout(res, wait));
@@ -313,9 +406,9 @@ function ask(question, hidden = true) {
 
 // ── commands ──
 function flag(args, name, dflt) { const i = args.indexOf(name); if (i < 0) return dflt; const v = args[i + 1]; args.splice(i, 2); return v; }
-async function fetchItem(name) {
+async function fetchItem(name, mode = "view") {
   const sp = await space(); const raw = spaceKey(sp.space);
-  const it = await approved("GET", itemPath(name));
+  const it = await approved("GET", itemPath(name), undefined, "access", mode);
   return open(raw, sp.space, name, it.nonce, it.ciphertext);
 }
 function pick(body, field) {
@@ -329,7 +422,7 @@ function pick(body, field) {
 const MCP_TOOLS = [
   { name: "vault_list", description: "List the credentials in the team vault (names and descriptions only; no secrets).", inputSchema: { type: "object", properties: {} } },
   { name: "vault_run",
-    description: "PREFERRED way to use a secret: run a shell command with vault items injected as environment variables. The secret values are masked as **** in the output returned to you, so they never enter the conversation. Needs the space owner's approval in the OwlMem console the first time (then 15 min – 2 h).",
+    description: "PREFERRED way to use a secret: run a shell command with vault items injected as environment variables. The secret values are masked as **** in the output returned to you, so they never enter the conversation. Needs the space owner's approval in the OwlMem console the first time (then 15 min – 2 h), unless they set a standing grant for you on this machine — standing grants cover vault_run only (not vault_get) unless the owner also allowed viewing.",
     inputSchema: { type: "object", properties: {
       command: { type: "string", description: "Shell command to run (sh -c)" },
       env: { type: "object", description: 'Map of ENV_VAR to "item" or "item:field", e.g. {"DB_PASSWORD": "prod/db:password"}', additionalProperties: { type: "string" } },
@@ -359,7 +452,7 @@ async function mcpCall(name, a) {
     for (const [k, ref] of Object.entries(a.env || {})) {
       if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) throw new Fail("Bad variable name " + k);
       const [item, field] = String(ref).split(":");
-      const v = pick(await fetchItem(item), field); env[k] = v; if (v && v.length >= 4) secrets.push(v);
+      const v = pick(await fetchItem(item, "run"), field); env[k] = v; if (v && v.length >= 4) secrets.push(v);
     }
     const mask = (t) => secrets.sort((x, y) => y.length - x.length).reduce((acc, v) => acc.split(v).join("****"), t);
     const out = await new Promise((res) => {
@@ -397,10 +490,309 @@ async function mcpServe() {
   await new Promise((res) => process.stdin.on("end", res));
 }
 
+// ── install: connect the AI apps on this machine to OwlMem's MCP server ──
+// The snippets here must say the same as the website (design/owlmem/site.py CODE); tests/test_owlmem_install.py compares them.
+export const MCP_URL = "https://mcp.owlmem.com/mcp";
+export const RULES = `## Team memory (OwlMem)
+- Before starting a task, use kb_search (documents) and kb_recall (facts) for the topic.
+- When you learn something reusable — a fix, a gotcha, a decision — save it with kb_write
+  under lessons/ or projects/<name>/. Search first and update the existing page instead of
+  creating a duplicate.
+- Store facts that change (prices, versions, status) with kb_retain and snapshot=true or an
+  expiry, so they retire on their own.
+- Never put passwords or API keys in documents or memory. Use the OwlMem vault.`;
+const MARK_START = "<!-- owlmem:start -->", MARK_END = "<!-- owlmem:end -->";
+const DOCS = "https://owlmem.com/docs#";
+// What each app's config file gets under its servers key (same shapes as on owlmem.com/docs)
+export const ENTRIES = {
+  cursor: { url: MCP_URL },
+  vscode: { type: "http", url: MCP_URL },
+  windsurf: { serverUrl: MCP_URL },
+  gemini: { httpUrl: MCP_URL },
+  "claude-desktop": { command: "npx", args: ["-y", "mcp-remote", MCP_URL] },
+};
+export const CLAUDE_ADD = ["mcp", "add", "--transport", "http", "--scope", "user", "owlmem", MCP_URL];
+export const CODEX_TOML = `[mcp_servers.owlmem]\nurl = "${MCP_URL}"`;
+
+function onPath(name) {
+  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  for (const d of (process.env.PATH || "").split(process.platform === "win32" ? ";" : ":")) {
+    if (!d) continue;
+    for (const e of exts) { const p = join(d, name + e); if (existsSync(p)) return p; }
+  }
+  return null;
+}
+function home() { return process.env.HOME || process.env.USERPROFILE || homedir(); }
+function platform() { return process.env.OWLMEM_PLATFORM || process.platform; }     // OWLMEM_PLATFORM: tests only
+function appData() {     // per-user application data folder (VS Code, Claude Desktop)
+  const p = platform(), h = home();
+  if (p === "darwin") return join(h, "Library", "Application Support");
+  if (p === "win32") return process.env.APPDATA || join(h, "AppData", "Roaming");
+  return process.env.XDG_CONFIG_HOME || join(h, ".config");
+}
+const readText = (f) => { try { return readFileSync(f, "utf8"); } catch { return null; } };
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// Client table. detect(): is this app on this machine? Each plan returns {state, ops, note}.
+//   state: "ok" (already set up) | "add" | "update" | "remove" | "absent" (nothing to remove) | "fail"
+//   ops: [{type:"write", file, text} | {type:"run", argv}]
+function jsonClient(id, name, file, key, entry) {
+  return { id, name, file, key, entry, docs: DOCS + ({ windsurf: "others", gemini: "others", "claude-desktop": "claude" }[id] || id) };
+}
+export function clients() {
+  const h = home(), ad = appData();
+  const codexHome = process.env.CODEX_HOME || join(h, ".codex");
+  const list = [
+    { id: "claude-code", name: "Claude Code", docs: DOCS + "claude-code", rules: join(process.env.CLAUDE_CONFIG_DIR || join(h, ".claude"), "CLAUDE.md"),
+      detect: () => !!onPath("claude") },
+    { id: "codex", name: "Codex", docs: DOCS + "codex", file: join(codexHome, "config.toml"), rules: join(codexHome, "AGENTS.md"),
+      detect: () => !!onPath("codex") || existsSync(codexHome) },
+    Object.assign(jsonClient("cursor", "Cursor", join(h, ".cursor", "mcp.json"), "mcpServers", ENTRIES.cursor),
+      { detect: () => existsSync(join(h, ".cursor")) || !!onPath("cursor") }),
+    Object.assign(jsonClient("vscode", "VS Code", join(ad, "Code", "User", "mcp.json"), "servers", ENTRIES.vscode),
+      { detect: () => existsSync(join(ad, "Code", "User")) }),
+    Object.assign(jsonClient("vscode-insiders", "VS Code Insiders", join(ad, "Code - Insiders", "User", "mcp.json"), "servers", ENTRIES.vscode),
+      { detect: () => existsSync(join(ad, "Code - Insiders", "User")), docs: DOCS + "vscode", optional: true }),
+    Object.assign(jsonClient("windsurf", "Windsurf", join(h, ".codeium", "windsurf", "mcp_config.json"), "mcpServers", ENTRIES.windsurf),
+      { detect: () => existsSync(join(h, ".codeium", "windsurf")) }),
+    Object.assign(jsonClient("gemini", "Gemini CLI", join(h, ".gemini", "settings.json"), "mcpServers", ENTRIES.gemini),
+      { detect: () => existsSync(join(h, ".gemini")) || !!onPath("gemini"), rules: join(h, ".gemini", "GEMINI.md") }),
+    Object.assign(jsonClient("claude-desktop", "Claude Desktop", join(ad, "Claude", "claude_desktop_config.json"), "mcpServers", ENTRIES["claude-desktop"]),
+      { detect: () => existsSync(join(ad, "Claude")) }),
+  ];
+  return list;
+}
+export const CLIENT_IDS = ["claude-code", "codex", "cursor", "vscode", "vscode-insiders", "windsurf", "gemini", "claude-desktop"];
+
+function planJSON(c, uninstall) {
+  const text = readText(c.file);
+  let obj = {};
+  if (text !== null && text.trim()) {
+    try { obj = JSON.parse(text); } catch {
+      const hint = /\/\/|\/\*/.test(text) ? "it has comments or isn't plain JSON" : "it isn't valid JSON";
+      return { state: "fail", ops: [], note: `${c.file}: ${hint}, so it was left alone. Add OwlMem by hand: ${c.docs}` };
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) return { state: "fail", ops: [], note: `${c.file}: unexpected content, left alone. Add OwlMem by hand: ${c.docs}` };
+  }
+  const servers = obj[c.key] && typeof obj[c.key] === "object" && !Array.isArray(obj[c.key]) ? obj[c.key] : null;
+  const cur = servers ? servers.owlmem : undefined;
+  if (uninstall) {
+    if (cur === undefined) return { state: "absent", ops: [] };
+    const next = { ...obj, [c.key]: { ...servers } }; delete next[c.key].owlmem;
+    return { state: "remove", ops: [{ type: "write", file: c.file, text: JSON.stringify(next, null, 2) + "\n" }] };
+  }
+  if (same(cur, c.entry)) return { state: "ok", ops: [] };
+  const next = { ...obj, [c.key]: { ...(servers || {}), owlmem: c.entry } };
+  return { state: cur === undefined ? "add" : "update", ops: [{ type: "write", file: c.file, text: JSON.stringify(next, null, 2) + "\n" }],
+           note: cur === undefined ? "" : "replaced the existing owlmem entry " + JSON.stringify(cur) };
+}
+
+// Codex: ~/.codex/config.toml. Only the [mcp_servers.owlmem] table (and its sub-tables) is touched; everything else is kept as is.
+export function tomlSplit(text) {
+  const rest = [], section = []; let mine = false;
+  for (const l of text.split("\n")) {
+    if (/^\s*\[\[/.test(l)) mine = false;
+    else { const m = /^\s*\[\s*([^\]]+?)\s*\]\s*(#.*)?$/.exec(l); if (m) { const n = m[1].replace(/["'\s]/g, ""); mine = n === "mcp_servers.owlmem" || n.startsWith("mcp_servers.owlmem."); } }
+    (mine ? section : rest).push(l);
+  }
+  return { rest: rest.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\s+$/, ""), section: section.join("\n").trim(), found: section.length > 0 };
+}
+function planCodex(c, uninstall) {
+  const text = readText(c.file) ?? "";
+  if (/^\s*mcp_servers\s*[.=]|^\s*owlmem\s*=\s*\{/m.test(text))
+    return { state: "fail", ops: [], note: `${c.file} defines MCP servers in a form this installer doesn't edit; left alone. Add OwlMem by hand: ${c.docs}` };
+  const { rest, section, found } = tomlSplit(text);
+  if (uninstall) return found ? { state: "remove", ops: [{ type: "write", file: c.file, text: rest ? rest + "\n" : "" }] } : { state: "absent", ops: [] };
+  const norm = (s) => s.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#")).join("\n");
+  if (found && norm(section) === norm(CODEX_TOML)) return { state: "ok", ops: [] };
+  return { state: found ? "update" : "add", ops: [{ type: "write", file: c.file, text: (rest ? rest + "\n\n" : "") + CODEX_TOML + "\n" }],
+           note: found ? "replaced the existing [mcp_servers.owlmem] table" : "" };
+}
+
+// Claude Code: through its own command (`claude mcp add … --scope user`); ~/.claude.json tells us what is there already.
+function planClaude(c, uninstall) {
+  let cur;
+  try { cur = (JSON.parse(readText(join(home(), ".claude.json")) || "{}").mcpServers || {}).owlmem; } catch { cur = undefined; }
+  const rm = { type: "run", argv: ["claude", "mcp", "remove", "owlmem", "--scope", "user"], ignoreFail: !uninstall };
+  if (uninstall) return cur === undefined ? { state: "absent", ops: [] } : { state: "remove", ops: [rm] };
+  if (cur && cur.url === MCP_URL && (cur.type === "http" || cur.type === "streamable-http") && !cur.headers) return { state: "ok", ops: [] };
+  return { state: cur === undefined ? "add" : "update", ops: [...(cur === undefined ? [] : [rm]), { type: "run", argv: ["claude", ...CLAUDE_ADD], retryWith: rm }],
+           note: cur === undefined ? "" : "replaced the existing owlmem server " + JSON.stringify(cur) };
+}
+
+export function withRules(text, uninstall) {
+  const t = text ?? "";
+  const re = new RegExp("\\n*" + MARK_START + "[\\s\\S]*?" + MARK_END + "\\n?");
+  if (uninstall) return re.test(t) ? t.replace(re, "\n").replace(/^\n+/, "").replace(/\n{3,}/g, "\n\n") : t;
+  const block = MARK_START + "\n" + RULES + "\n" + MARK_END + "\n";
+  if (re.test(t)) return t.replace(re, (m) => (m.startsWith("\n") ? "\n\n" : "") + block);
+  return t.trim() ? t.replace(/\s*$/, "\n\n") + block : block;
+}
+
+export function plan(opts = {}) {
+  const only = opts.only ? new Set(opts.only) : null;
+  const out = [];
+  for (const c of clients()) {
+    if (only && !only.has(c.id) && !(c.id === "vscode-insiders" && only.has("vscode"))) continue;
+    const r = { id: c.id, name: c.name, docs: c.docs, file: c.file, ops: [], note: "" };
+    if (!c.detect()) { if (!c.optional || only) Object.assign(r, { state: "missing" }); else continue; out.push(r); continue; }
+    Object.assign(r, c.id === "claude-code" ? planClaude(c, opts.uninstall) : c.id === "codex" ? planCodex(c, opts.uninstall) : planJSON(c, opts.uninstall));
+    if (c.rules && !opts.noRules && r.state !== "fail") {
+      const before = readText(c.rules), after = withRules(before, opts.uninstall);
+      if (after !== (before ?? "") && !(opts.uninstall && before === null)) { r.ops.push({ type: "write", file: c.rules, text: after, rules: true }); r.rulesChanged = true; }
+      r.rulesFile = c.rules;
+    }
+    out.push(r);
+  }
+  return out;
+}
+
+function stamp() { const d = new Date(), p = (n) => String(n).padStart(2, "0"); return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`; }
+function runCmd(argv) {
+  const r = spawnSync(argv[0], argv.slice(1), { encoding: "utf8", shell: process.platform === "win32", timeout: 60000 });
+  return { ok: r.status === 0, out: ((r.stderr || "") + (r.stdout || "")).trim() || (r.error ? r.error.message : "") };
+}
+export function apply(items) {
+  const ts = stamp();
+  for (const r of items) {
+    r.backups = [];
+    try {
+      for (const op of r.ops) {
+        if (op.type === "write") {
+          mkdirSync(dirname(op.file), { recursive: true });
+          if (existsSync(op.file)) { const b = op.file + ".bak-owlmem-" + ts; copyFileSync(op.file, b); r.backups.push(b); }
+          writeFileSync(op.file, op.text);
+        } else {
+          let res = runCmd(op.argv);
+          if (!res.ok && op.retryWith && /already exists/i.test(res.out)) { runCmd(op.retryWith.argv); res = runCmd(op.argv); }
+          if (!res.ok && !op.ignoreFail) throw new Error("`" + op.argv.join(" ") + "` failed: " + (res.out.split("\n").slice(-3).join(" ") || "no output"));
+        }
+      }
+    } catch (e) { r.state = "fail"; r.note = (e.message || String(e)) + " — set it up by hand: " + r.docs; }
+  }
+  return items;
+}
+
+const tilde = (f) => { const h = home(); return f && h && f.startsWith(h + (platform() === "win32" ? "\\" : "/")) ? "~" + f.slice(h.length) : f; };
+const SYM = { ok: "✓", add: "✓", update: "↺", remove: "✓", absent: "–", missing: "–", fail: "✗" };
+function describe(r, done, uninstall) {
+  const verb = {
+    ok: "already set up", add: done ? "added" : "will add OwlMem", update: done ? "updated" : "will update the owlmem entry",
+    remove: done ? "removed" : "will remove OwlMem", absent: "not configured", missing: "not installed", fail: "failed",
+  }[r.state];
+  const sym = !done && r.state === "add" ? "+" : !done && r.state === "remove" ? "-" : SYM[r.state];
+  const lines = [`${sym} ${r.name.padEnd(17)} ${verb}${r.state !== "missing" && r.file && r.state !== "fail" ? "  (" + tilde(r.file) + ")" : ""}`];
+  if (r.note) lines.push("    " + r.note);
+  for (const op of r.ops) {
+    if (op.type === "run" && !done) lines.push("    run: " + op.argv.join(" "));
+    if (op.rules) lines.push(`    ${done ? "" : "will "}${uninstall ? (done ? "removed" : "remove") : (done ? "wrote" : "write")} the OwlMem rules block in ${tilde(op.file)}`);
+  }
+  if (done && r.backups?.length) lines.push("    backup: " + r.backups.join(", "));
+  return lines.join("\n");
+}
+
+const LOGIN = {
+  "claude-code": "Claude Code: run /mcp, pick owlmem, choose Authenticate.",
+  codex: "Codex: run `codex mcp login owlmem`.",
+  cursor: "Cursor: Settings → MCP, click \"Needs login\" next to owlmem.",
+  vscode: "VS Code: it asks you to sign in the first time Copilot uses owlmem (or run \"MCP: List Servers\" → owlmem → Start).",
+  "vscode-insiders": "VS Code Insiders: same as VS Code.",
+  windsurf: "Windsurf: open Settings → MCP servers and refresh; sign in when it asks.",
+  gemini: "Gemini CLI: run `/mcp auth owlmem`.",
+  "claude-desktop": "Claude Desktop: restart it; the sign-in page opens on the first start (via mcp-remote).",
+};
+
+async function install(args) {
+  const opts = { dryRun: false, yes: false, noRules: false, uninstall: false, only: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--no-rules") opts.noRules = true;
+    else if (a === "--uninstall") opts.uninstall = true;
+    else if (a === "--only" || a.startsWith("--only=")) {
+      const v = a.includes("=") ? a.slice(7) : args[++i];
+      opts.only = String(v || "").split(",").map((s) => s.trim()).filter(Boolean);
+      const bad = opts.only.filter((x) => !CLIENT_IDS.includes(x));
+      if (bad.length || !opts.only.length) throw new Fail(`--only takes a comma-separated list of: ${CLIENT_IDS.join(", ")}`);
+    } else if (a === "--help" || a === "-h") { console.log(INSTALL_HELP); return; }
+    else throw new Fail("Unknown option " + a + "\n\n" + INSTALL_HELP);
+  }
+  const items = plan(opts);
+  const changes = items.filter((r) => r.ops.length);
+  const out = (s = "") => console.log(s);
+  out(opts.uninstall ? "OwlMem uninstall — " + (opts.dryRun ? "dry run, nothing is changed" : "plan") : "OwlMem install — connects the AI apps on this computer to " + MCP_URL + (opts.dryRun ? " (dry run, nothing is changed)" : ""));
+  out();
+  for (const r of items) out(describe(r, false, opts.uninstall));
+  out();
+  if (!changes.length) {
+    out(items.some((r) => r.state === "ok") || opts.uninstall ? "Nothing to change." : "No supported AI apps found. Manual setup for every app: https://owlmem.com/docs");
+    if (!opts.uninstall && items.some((r) => r.state === "ok")) nextSteps(items, out);
+    process.exitCode = items.some((r) => r.state === "fail") ? 1 : 0;
+    return;
+  }
+  if (opts.dryRun) { out(`Dry run: ${changes.length} app(s) would change. Run again without --dry-run to apply.`); return; }
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty && !opts.yes) {
+    const ans = (await ask("Apply these changes? [Y/n] ", false)).toLowerCase();
+    if (ans && !ans.startsWith("y")) { out("Nothing changed."); return; }
+  }
+  apply(changes);
+  out();
+  for (const r of changes) out(describe(r, true, opts.uninstall));
+  out();
+  if (opts.uninstall) out("OwlMem was removed from those apps. Backups of every changed file sit next to it (*.bak-owlmem-*).");
+  else {
+    nextSteps(items, out);
+    const codex = items.find((r) => r.id === "codex" && r.state !== "fail" && r.state !== "missing");
+    if (codex && tty && !opts.yes && onPath("codex") && browserAllowed()) {      // codex mcp login opens a browser: same rule as openBrowser
+      const ans = (await ask("Sign Codex in now? This runs `codex mcp login owlmem` and opens your browser. [y/N] ", false)).toLowerCase();
+      if (ans.startsWith("y")) await new Promise((res) => spawn("codex", ["mcp", "login", "owlmem"], { stdio: "inherit", shell: process.platform === "win32" }).on("exit", res).on("error", res));
+    }
+  }
+  if (items.some((r) => r.state === "fail")) process.exitCode = 1;
+}
+
+function nextSteps(items, out) {
+  const live = items.filter((r) => ["ok", "add", "update"].includes(r.state));
+  if (!live.length) return;
+  out("Next: sign in once in each app. The first time an app uses OwlMem it opens the owlmem.com sign-in page —");
+  out("sign in with your email (new accounts get a free space) and click \"Allow\". An AI can't click it for you.");
+  for (const r of live) out("  • " + LOGIN[r.id]);
+  if (live.some((r) => ["cursor", "vscode", "vscode-insiders", "windsurf"].includes(r.id)))
+    out("Cursor, VS Code and Windsurf have no global rules file: add the rules from https://owlmem.com/docs#instructions to your project rules.");
+  if (live.some((r) => r.id === "claude-desktop")) out("Claude Desktop: restart it to load OwlMem. (Or add https://mcp.owlmem.com/mcp under Settings → Connectors instead.)");
+  out("Already-running sessions don't see new MCP servers: start a new session, then ask your AI to run kb_search.");
+}
+
+const INSTALL_HELP = `Usage: npx -y owlmem install [options]
+
+Connects Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and Claude Desktop on this computer to
+OwlMem (${MCP_URL}). Config files are merged, never overwritten; each changed file is backed up first
+as <file>.bak-owlmem-<time>. Also adds the OwlMem usage rules to CLAUDE.md / AGENTS.md / GEMINI.md.
+
+  --dry-run          show what would change, change nothing
+  --yes, -y          don't ask (non-interactive runs, e.g. an AI running this, never ask)
+  --only a,b         only these apps: ${CLIENT_IDS.join(", ")}
+  --no-rules         don't touch CLAUDE.md / AGENTS.md / GEMINI.md
+  --uninstall        remove OwlMem entries and the rules block (with backups)
+
+Signing in happens in each app the first time it uses OwlMem (standard MCP OAuth): you click "Allow" once.`;
+
 export async function main(argv) {
   const [cmd, sub, ...rest] = argv;
   if (cmd === "--version" || cmd === "version") { console.log(VERSION); return; }
+  if (cmd === "install") { await install(argv.slice(1)); return; }
+  if (cmd === "uninstall") { await install(["--uninstall", ...argv.slice(1)]); return; }
   if (cmd === "mcp") { await mcpServe(); return; }
+  if (cmd === "device") {          // register this machine for standing grants and show its fingerprint
+    const r = await call("POST", "device", {});
+    if (r.status >= 400) throw new Fail(r.data.detail || r.data.error || "HTTP " + r.status);
+    say("This machine: " + (process.env.OWLMEM_DEVICE_NAME || hostname()));
+    console.log(r.data.device);
+    say("Registered for " + r.data.agent + ". In the OwlMem console (Vault → Standing grants) pick the machine with this fingerprint.");
+    return;
+  }
   if (cmd === "login") {
     const t = (process.env.OWLMEM_TOKEN || await ask("Paste this agent's token (om_…, shown as dots), then Enter: ")).replace(/\x1b\[[0-9;]*[~A-Za-z]/g, "").replace(/[^A-Za-z0-9_-]/g, "");
     if (!/^om_[A-Za-z0-9_-]{20,80}$/.test(t)) throw new Fail("That doesn't look like an OwlMem agent token (om_…).");
@@ -418,13 +810,13 @@ export async function main(argv) {
       if (opts[i] !== "--env") throw new Fail("Unknown option " + opts[i]);
       const m = /^([A-Za-z_][A-Za-z0-9_]*)=([^:]+)(?::(.+))?$/.exec(opts[++i] || "");
       if (!m) throw new Fail("Use --env VAR=item or --env VAR=item:field");
-      env[m[1]] = pick(await fetchItem(m[2]), m[3] || (undefined));
+      env[m[1]] = pick(await fetchItem(m[2], "run"), m[3] || (undefined));
     }
     const child = spawn(command[0], command.slice(1), { stdio: "inherit", env });
     await new Promise((res) => child.on("exit", (code, sig) => { process.exitCode = sig ? 1 : code; res(); }));
     return;
   }
-  if (cmd !== "vault") { say(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//")).slice(0, 26).map((l) => l.slice(3)).join("\n")); process.exitCode = cmd ? 2 : 0; return; }
+  if (cmd !== "vault") { { const ls = readFileSync(new URL(import.meta.url), "utf8").split("\n").slice(1); say(ls.slice(0, ls.findIndex((l) => !l.startsWith("//"))).map((l) => l.slice(3)).join("\n")); } process.exitCode = cmd ? 2 : 0; return; }
   const args = [...rest];
   if (sub === "keygen") {
     const sp = process.env.OWLMEM_SPACE || (await space().catch(() => ({}))).space;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "owlmem",
-  "version": "0.4.0",
-  "description": "OwlMem command line: end-to-end encrypted vault for your AI agents, and a local MCP server.",
+  "version": "0.6.0",
+  "description": "OwlMem command line: connect your AI apps to OwlMem in one command (npx -y owlmem install), an end-to-end encrypted vault for your AI agents, and a local MCP server.",
   "type": "module",
   "bin": { "owlmem": "owlmem.mjs" },
   "files": ["owlmem.mjs", "README.md", "LICENSE"],