@iamem/amem 0.1.1 → 0.1.2

package/README.md

@@ -52,7 +52,8 @@ Guarantees:
 
 - `~/.amem` is created with mode `0700`
 - Local UI binds to `127.0.0.1` only
-- No telemetry, no managed sync, no “share with org” mode
+- Memory never leaves the machine — no managed sync, no “share with org” mode
+- Optional anonymous install ping only (see [Telemetry](#telemetry)); opt out anytime
 - Agents are instructed to store **repo facts**, not proprietary prompting strategy
 - Optional AES-256-GCM lock and encrypted local backups — still no cloud
 
@@ -87,6 +88,22 @@ See [docs/npm-release.md](docs/npm-release.md). CI runs `npm test` and `npm run
 
 If `npm install` fails compiling native code, install Xcode CLT (macOS) or `build-essential` (Linux) and retry, or use a Node 20/22 official binary that matches the prebuild matrix.
 
+### Telemetry
+
+On `npm install` / `npx` (outside CI and tests), amem may send a single anonymous POST to `https://getamem.com/api/beacon/npm-install` with:
+
+- package name and version
+- Node.js version
+- OS platform and CPU architecture
+
+No code, paths, usernames, emails, IPs, or memory contents are included. Opt out:
+
+```bash
+AMEM_TELEMETRY_DISABLED=1 npm i -g @iamem/amem
+```
+
+Memory under `~/.amem` still never leaves your machine.
+
 ### Quick paths
 
 ```bash
@@ -142,6 +159,17 @@ amem ui
 
 That opens `http://127.0.0.1:7843` on the **Setup** tab. It scans your home folder for git repos (skips `Library`, `node_modules`, `Downloads`, and similar noise). Check the ones you want, pick clients (Cursor, Claude Code, Windsurf, Continue, Aider, Zed, …), then **Start tracking selected**. Each pick is bound in `~/.amem` and gets the matching installer when available.
 
+Prefer a desktop window instead of a browser tab (same localhost server, same privacy):
+
+```bash
+# once per machine/checkout (downloads Electron — not included in npm i -g)
+npm run app:setup
+
+amem app
+```
+
+`amem ui` keeps opening the browser; `amem app` opens Electron. Both talk to `127.0.0.1` only. If the UI server is already running, `amem app` attaches to it. Global installs: run `npm run app:setup` from the package directory (or clone), then `amem app`.
+
 The header has a **Personal** switcher (cross-repo prefs) and **Lock / backup** chrome — lock status, last backup, and a daily local schedule. Memory shows the same lock/backup chips. The Setup tab includes a copyable **remember contract** for any MCP host (`amem recipe`).
 
 Optional: check **Start amem ui when this computer logs in** so the localhost server comes back after a reboot:
@@ -388,6 +416,7 @@ amem usage export [--format json|md|pdf] [--days 30] [--scope current|all] [--ou
 amem license status|apply|activate|clear|issue|keys
 amem embed status|use hash|use ngram|reindex
 amem ui [--port 7843] [--no-open]
+amem app [--port 7843]
 amem service install|uninstall|status
 ```
 
@@ -403,7 +432,8 @@ amem service install|uninstall|status
 | `propose apply` | Upsert structured memory locally |
 | `lock` / `unlock` | Optional AES-256-GCM encrypt-at-rest for `graph.db` |
 | `backup` | Local snapshot (optionally encrypted); `schedule` for daily timer |
-| `ui` | Setup wizard + Memory + Stats on localhost |
+| `ui` | Setup wizard + Memory + Stats in the browser (localhost) |
+| `app` | Same UI in an Electron window (`npm run app:setup` once) |
 | `service` | Login item so `amem ui` starts after reboot |
 | `doctor --attest` | Privacy/policy attestation for IT tickets |
 | `export` / `wipe` | Personal backup or delete (still local) |
@@ -490,7 +520,8 @@ IT / DevEx can govern the **fleet**: approved install, policy, attestation, offb
 
 Hard guarantees (not configurable away):
 
-- No telemetry  
+- No memory telemetry or claim upload — `~/.amem` stays local  
+- Optional anonymous npm install ping only (opt out: `AMEM_TELEMETRY_DISABLED=1`)  
 - UI binds to loopback only (`127.0.0.1`)  
 - Memory stays under `~/.amem` (mode `0700`)  
 

package/desktop/main.js

@@ -0,0 +1,100 @@
+/**
+ * Thin Electron shell: loads the existing amem localhost UI.
+ * No Node integration in the renderer — API stays on 127.0.0.1.
+ *
+ * macOS note: BrowserWindow `icon` does not change the Dock for an unpackaged
+ * Electron.app. We must call app.dock.setIcon() with a PNG (icns often loads empty).
+ */
+const { app, BrowserWindow, nativeImage } = require("electron");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function uiUrl() {
+  const fromEnv = String(process.env.AMEM_UI_URL || "").trim();
+  if (fromEnv) return fromEnv;
+  const arg = process.argv.find((a) => /^https?:\/\//.test(a));
+  return arg || "http://127.0.0.1:7843/";
+}
+
+function iconsDir() {
+  return path.join(__dirname, "icons");
+}
+
+/** Prefer PNG for Dock — nativeImage + .icns is unreliable for unpackaged Electron. */
+function loadAppIcon() {
+  const dir = iconsDir();
+  const candidates =
+    process.platform === "darwin"
+      ? ["icon-1024.png", "icon.png", "icon.icns"]
+      : process.platform === "win32"
+        ? ["icon.ico", "icon.png", "icon-1024.png"]
+        : ["icon.png", "icon-1024.png"];
+
+  for (const name of candidates) {
+    const iconPath = path.join(dir, name);
+    if (!fs.existsSync(iconPath)) continue;
+    let image = nativeImage.createFromPath(iconPath);
+    if (image.isEmpty()) continue;
+    // Dock looks sharper with a mid-size bitmap.
+    const { width } = image.getSize();
+    if (width > 512) {
+      image = image.resize({ width: 512, height: 512, quality: "best" });
+    }
+    return image;
+  }
+  console.warn("[amem-desktop] no usable icon in", dir);
+  return null;
+}
+
+function applyDockIcon(icon) {
+  if (!icon || process.platform !== "darwin" || !app.dock) return;
+  try {
+    app.dock.setIcon(icon);
+    app.dock.show();
+  } catch (err) {
+    console.warn("[amem-desktop] dock.setIcon failed:", err instanceof Error ? err.message : err);
+  }
+}
+
+function createWindow(icon) {
+  const win = new BrowserWindow({
+    width: 1280,
+    height: 860,
+    minWidth: 880,
+    minHeight: 560,
+    title: "amem",
+    show: false,
+    backgroundColor: "#0b0f12",
+    ...(icon ? { icon } : {}),
+    webPreferences: {
+      preload: path.join(__dirname, "preload.js"),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+    },
+  });
+
+  win.once("ready-to-show", () => {
+    applyDockIcon(icon);
+    win.show();
+  });
+  win.loadURL(uiUrl()).catch((err) => {
+    console.error("[amem-desktop] failed to load UI:", err instanceof Error ? err.message : err);
+  });
+}
+
+app.setName("amem");
+
+app.whenReady().then(() => {
+  const icon = loadAppIcon();
+  applyDockIcon(icon);
+  createWindow(icon);
+  app.on("activate", () => {
+    applyDockIcon(icon);
+    if (BrowserWindow.getAllWindows().length === 0) createWindow(icon);
+  });
+});
+
+app.on("window-all-closed", () => {
+  app.quit();
+});

package/desktop/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "amem-desktop",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Electron shell for local amem Brain UI (localhost only).",
+  "main": "main.js",
+  "scripts": {
+    "start": "electron ."
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "electron": "^33.2.1"
+  }
+}

package/desktop/preload.js

@@ -0,0 +1,4 @@
+/**
+ * Preload is intentionally empty for v1 — the UI talks to localhost over fetch.
+ * Kept for secure defaults (contextIsolation + sandbox).
+ */

package/desktop/scripts/ensure-electron.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Ensure the Electron binary finished downloading after npm install
+ * (some environments skip lifecycle scripts / botch macOS framework unzip).
+ */
+import { existsSync, rmSync, writeFileSync, statSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const desktopRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const electronPkg = join(desktopRoot, "node_modules", "electron");
+const pathTxt = join(electronPkg, "path.txt");
+const distDir = join(electronPkg, "dist");
+
+if (!existsSync(join(electronPkg, "package.json"))) {
+  console.error("electron is not installed under desktop/. Run: npm install --prefix desktop");
+  process.exit(1);
+}
+
+function platformRelative() {
+  if (process.platform === "darwin") return "Electron.app/Contents/MacOS/Electron";
+  if (process.platform === "win32") return "electron.exe";
+  return "electron";
+}
+
+function binaryPath() {
+  return join(distDir, platformRelative());
+}
+
+function frameworkOk() {
+  if (process.platform !== "darwin") return true;
+  return existsSync(
+    join(distDir, "Electron.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Electron Framework"),
+  );
+}
+
+function looksComplete() {
+  const bin = binaryPath();
+  if (!existsSync(bin)) return false;
+  if (!frameworkOk()) return false;
+  return true;
+}
+
+function requireBin() {
+  try {
+    const require = createRequire(pathToFileURL(join(desktopRoot, "package.json")).href);
+    const bin = require("electron");
+    return typeof bin === "string" && existsSync(bin) ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+function downloadZip() {
+  const require = createRequire(join(electronPkg, "package.json"));
+  const { downloadArtifact } = require("@electron/get");
+  const { version } = require(join(electronPkg, "package.json"));
+  const checksums = require(join(electronPkg, "checksums.json"));
+  return downloadArtifact({
+    version,
+    artifactName: "electron",
+    force: true,
+    platform: process.platform,
+    arch: process.arch,
+    checksums,
+  });
+}
+
+async function ensure() {
+  if (looksComplete()) {
+    if (!existsSync(pathTxt)) writeFileSync(pathTxt, platformRelative());
+    console.log(`Electron ready: ${requireBin() || binaryPath()}`);
+    return;
+  }
+
+  console.log("Downloading Electron binary…");
+  rmSync(distDir, { recursive: true, force: true });
+  try {
+    rmSync(pathTxt, { force: true });
+  } catch {
+    /* ignore */
+  }
+
+  const zipPath = await downloadZip();
+  mkdirSync(distDir, { recursive: true });
+
+  // System unzip preserves macOS framework symlinks; extract-zip often does not.
+  const unzip = spawnSync("unzip", ["-o", "-q", zipPath, "-d", distDir], { stdio: "inherit" });
+  if (unzip.status !== 0) {
+    // Fallback for Windows / machines without unzip
+    const extract = requireFromElectron("extract-zip");
+    await extract(zipPath, { dir: distDir });
+  }
+
+  writeFileSync(pathTxt, platformRelative());
+  // Match electron/install.js version marker when present
+  try {
+    const { version } = createRequire(join(electronPkg, "package.json"))("./package.json");
+    writeFileSync(join(distDir, "version"), version);
+  } catch {
+    /* ignore */
+  }
+
+  if (!looksComplete()) {
+    console.error("Electron binary still incomplete after install.");
+    console.error("Try: rm -rf desktop/node_modules && npm run app:setup");
+    process.exit(1);
+  }
+
+  console.log(`Electron ready: ${requireBin() || binaryPath()}`);
+}
+
+function requireFromElectron(id) {
+  return createRequire(join(electronPkg, "package.json"))(id);
+}
+
+ensure().catch((err) => {
+  console.error(err instanceof Error ? err.stack : err);
+  process.exit(1);
+});

package/dist/app-shell.d.ts

@@ -0,0 +1,13 @@
+export declare function desktopDir(pkgRoot?: string): string;
+export declare function electronInstallHint(dir?: string): string;
+/** Absolute path to the Electron binary, or null if desktop deps are missing. */
+export declare function resolveElectronBinary(dir?: string): string | null;
+/**
+ * Start or attach to amem ui, then open the Electron window.
+ * Owns server shutdown only when this process started it.
+ */
+export declare function runDesktopApp(options?: {
+    port?: number;
+    cwd?: string;
+    pkgRoot?: string;
+}): Promise<void>;

package/dist/app-shell.js

@@ -0,0 +1,126 @@
+/**
+ * Desktop (Electron) shell launcher for the localhost Brain UI.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadPolicy } from "./policy.js";
+import { buildUiLandingUrl, isAddrInUse, probeUiHealth, startUiServer, } from "./ui/server.js";
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export function desktopDir(pkgRoot = PKG_ROOT) {
+    return join(pkgRoot, "desktop");
+}
+export function electronInstallHint(dir = desktopDir()) {
+    return `npm run app:setup   # or: npm install --prefix "${dir}" && node desktop/scripts/ensure-electron.mjs`;
+}
+/** Absolute path to the Electron binary, or null if desktop deps are missing. */
+export function resolveElectronBinary(dir = desktopDir()) {
+    const pkgJson = join(dir, "package.json");
+    if (!existsSync(pkgJson))
+        return null;
+    const candidates = [
+        join(dir, "node_modules/electron/dist/Electron.app/Contents/MacOS/Electron"),
+        join(dir, "node_modules/electron/dist/electron"),
+        join(dir, "node_modules/electron/dist/electron.exe"),
+    ];
+    try {
+        const require = createRequire(pkgJson);
+        const bin = require("electron");
+        if (typeof bin === "string" && bin && existsSync(bin))
+            return bin;
+    }
+    catch {
+        /* path.txt missing or postinstall incomplete — try dist paths */
+    }
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function spawnElectron(electronBin, dir, url) {
+    return new Promise((resolve, reject) => {
+        const env = { ...process.env, AMEM_UI_URL: url };
+        // Parent IDEs sometimes set this; it makes Electron run as plain Node.
+        delete env.ELECTRON_RUN_AS_NODE;
+        const child = spawn(electronBin, [".", url], {
+            cwd: dir,
+            env,
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                resolve(1);
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}
+/**
+ * Start or attach to amem ui, then open the Electron window.
+ * Owns server shutdown only when this process started it.
+ */
+export async function runDesktopApp(options = {}) {
+    const port = options.port ?? 7843;
+    const cwd = options.cwd ?? process.cwd();
+    const dir = desktopDir(options.pkgRoot ?? PKG_ROOT);
+    const electronBin = resolveElectronBinary(dir);
+    if (!electronBin) {
+        const err = new Error([
+            "Electron desktop shell is not installed.",
+            `Run once:  ${electronInstallHint(dir)}`,
+            "Then:       amem app",
+            "(Browser UI still works with: amem ui)",
+        ].join("\n"));
+        err.code = "AMEM_ELECTRON_MISSING";
+        throw err;
+    }
+    const policy = loadPolicy().policy;
+    const landing = buildUiLandingUrl(port, cwd);
+    let owned = null;
+    try {
+        owned = await startUiServer({
+            port,
+            cwd,
+            openBrowser: false,
+            host: policy.ui_bind,
+            landingUrl: landing,
+        });
+    }
+    catch (error) {
+        if (!isAddrInUse(error))
+            throw error;
+        const probe = await probeUiHealth(port);
+        if (!probe.hasVault) {
+            throw new Error([
+                `Port ${port} is already serving an older amem without lock/backup APIs.`,
+                "Stop that process, then run amem app again:",
+                `  lsof -nP -iTCP:${port} -sTCP:LISTEN`,
+            ].join("\n"));
+        }
+    }
+    console.log(`amem app → ${landing}`);
+    if (owned)
+        console.log("UI server started for this window (localhost only).");
+    else
+        console.log("Attached to UI server already running on this port.");
+    try {
+        const code = await spawnElectron(electronBin, dir, landing);
+        if (code !== 0)
+            process.exitCode = code;
+    }
+    finally {
+        if (owned) {
+            try {
+                await owned.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}

package/dist/cli.js

@@ -12,6 +12,7 @@ import { amemHome, dbPath, tryEnsureDir } from "./paths.js";
 import { assertExportAllowed, assertPlatformAllowed, assertRemoteAllowed, assertUiAllowed, loadPolicy, } from "./policy.js";
 import { applyProposal, diffProposal, exportRepoMemory, formatProposalDiff, loadProposalFile, validateProposal, } from "./proposal.js";
 import { detectRepoIdentity, parseWorkspaceSlug, workspaceIdentity } from "./repo-identity.js";
+import { runDesktopApp } from "./app-shell.js";
 import { startUiServer, buildUiLandingUrl, openUiInBrowser, isAddrInUse, probeUiHealth, } from "./ui/server.js";
 import { installLoginService, isServiceInstalled, isServiceSupported, uninstallLoginService } from "./service.js";
 import { mcpClientConfig, runMcpServer } from "./mcp.js";
@@ -66,6 +67,7 @@ Usage:
   amem usage report --saved <n> [--platform cursor|claude] [--event-id <id>]
   amem usage export [--format json|md|pdf] [--days 30] [--scope current|all] [--out <file>]
   amem ui [--port 7843] [--no-open]
+  amem app [--port 7843]
   amem service install|uninstall|status
   amem mcp [--print-config] [--workspace <name>]
   amem license status|apply|clear|issue|keys
@@ -846,6 +848,21 @@ async function main() {
                 }
                 break;
             }
+            case "app": {
+                assertUiAllowed();
+                const port = Number(flagString(flags, "port") ?? "7843");
+                try {
+                    await runDesktopApp({ port, cwd: process.cwd() });
+                }
+                catch (error) {
+                    console.error(error instanceof Error ? error.message : String(error));
+                    closeDb();
+                    process.exitCode = 1;
+                    break;
+                }
+                closeDb();
+                break;
+            }
             case "service": {
                 const sub = positional[1];
                 if (sub === "status") {

package/dist/publish.d.ts

@@ -1,5 +1,5 @@
 /** Paths that must be inside the published tarball for `npx @iamem/amem setup`. */
-export declare const REQUIRED_PACK_PATHS: readonly ["dist/cli.js", "dist/mcp.js", "dist/remember-contract.js", "ui-static/index.html", "ui-static/app.js", "ui-static/styles.css", "docs/remember-contract.md", "docs/agent-install-prompt.md", "docs/npm-release.md", "skills/amem-update-working-memory/SKILL.md", "scripts/mdm-offboard.sh"];
+export declare const REQUIRED_PACK_PATHS: readonly ["dist/cli.js", "dist/mcp.js", "dist/remember-contract.js", "ui-static/index.html", "ui-static/app.js", "ui-static/styles.css", "docs/remember-contract.md", "docs/agent-install-prompt.md", "docs/npm-release.md", "skills/amem-update-working-memory/SKILL.md", "scripts/mdm-offboard.sh", "scripts/postinstall.js"];
 export declare const PUBLISH_PACKAGE_NAME = "@iamem/amem";
 export type PublishReady = {
     root: string;

package/dist/publish.js

@@ -14,6 +14,7 @@ export const REQUIRED_PACK_PATHS = [
     "docs/npm-release.md",
     "skills/amem-update-working-memory/SKILL.md",
     "scripts/mdm-offboard.sh",
+    "scripts/postinstall.js",
 ];
 export const PUBLISH_PACKAGE_NAME = "@iamem/amem";
 export function packageRoot() {

package/docs/npm-release.md

@@ -35,4 +35,4 @@ This repo does **not** auto-publish on every push.
 
 ## Pack contents
 
-`package.json#files` includes `dist`, `ui-static`, `docs`, `skills`, and `scripts/mdm-offboard.sh`. Native code is pulled in as the `better-sqlite3` dependency — do not vendor it.
+`package.json#files` includes `dist`, `ui-static`, `docs`, `skills`, `scripts/mdm-offboard.sh`, and `scripts/postinstall.js` (anonymous install ping; opt out with `AMEM_TELEMETRY_DISABLED=1`). Native code is pulled in as the `better-sqlite3` dependency — do not vendor it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamem/amem",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local personal agent memory for Cursor and Claude Code. Private to your machine — never shared.",
   "type": "module",
   "bin": {
@@ -16,17 +16,22 @@
   },
   "files": [
     "dist",
+    "desktop",
     "skills",
     "templates",
     "docs",
     "ui-static",
-    "scripts/mdm-offboard.sh"
+    "scripts/mdm-offboard.sh",
+    "scripts/postinstall.js"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "prepare": "npm run build",
+    "postinstall": "node ./scripts/postinstall.js",
     "amem": "node dist/cli.js",
+    "app": "node dist/cli.js app",
+    "app:setup": "npm install --prefix desktop && node desktop/scripts/ensure-electron.mjs",
     "smoke": "node scripts/smoke.mjs",
     "pack:check": "npm run build && node scripts/check-pack.mjs",
     "prepublishOnly": "npm test && node scripts/check-pack.mjs",

package/scripts/postinstall.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Anonymous install ping for @iamem/amem (package version, Node, OS/arch only).
+ * Opt out: AMEM_TELEMETRY_DISABLED=1  — skipped automatically in CI / NODE_ENV=test.
+ * Never throws; always exits 0 so install is never blocked.
+ */
+import https from "node:https";
+import os from "node:os";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function done() {
+  process.exit(0);
+}
+
+try {
+  if (
+    process.env.AMEM_TELEMETRY_DISABLED ||
+    process.env.CI ||
+    process.env.NODE_ENV === "test"
+  ) {
+    done();
+  }
+
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const body = JSON.stringify({
+    event: "npm_install",
+    package: pkg.name || "@iamem/amem",
+    version: pkg.version || "",
+    node: process.version,
+    platform: os.platform(),
+    arch: os.arch(),
+    ts: Date.now(),
+  });
+
+  const req = https.request(
+    {
+      hostname: "getamem.com",
+      path: "/api/beacon/npm-install",
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+        "User-Agent": `amem-postinstall/${pkg.name || "amem"}@${pkg.version || "0"}`,
+      },
+      timeout: 2000,
+    },
+    () => done(),
+  );
+  req.on("error", () => done());
+  req.on("timeout", () => {
+    req.destroy();
+    done();
+  });
+  setTimeout(done, 2000);
+  req.write(body);
+  req.end();
+} catch {
+  done();
+}