@iamem/amem 0.1.0 → 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/api/routes.js

@@ -9,6 +9,7 @@ import { installClaude, claudeInstallHealth } from "../install/claude.js";
 import { installCursor, cursorInstallHealth } from "../install/cursor.js";
 import { hostInstallHealth, installHost } from "../install/hosts.js";
 import { decorateDraft, decorateDrafts } from "../draft-quality.js";
+import { isUsefulRememberText } from "../capture.js";
 import { buildSavingsExport, formatSavingsMarkdown, savingsPdf, } from "../savings-export.js";
 import { assertPlatformAllowed, assertRemoteAllowed, loadPolicy, } from "../policy.js";
 import { applyProposal, applySupersedes, parseProposalJson, validateProposal } from "../proposal.js";
@@ -412,6 +413,9 @@ function runRemember(repo, body) {
     const text = bodyField(body, "text");
     if (!text)
         return err(400, "text required");
+    if (!isUsefulRememberText(text)) {
+        return err(400, "text too trivial or secret-like — remember a durable fact with context");
+    }
     const kind = bodyField(body, "kind") ?? "session";
     const id = bodyField(body, "id") ??
         `claim.remember_${createHash("sha256").update(text).digest("hex").slice(0, 12)}`;

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/capture.d.ts

@@ -1,6 +1,9 @@
 import { type ProposalDraftRow, type RepoRow, type UsageEventRow } from "./db.js";
 import { type Proposal } from "./proposal.js";
+/** Reject empty / chat-noise / secret-like text before it becomes a claim. */
 export declare function isUsefulCaptureText(text: string): boolean;
+/** Same guard for explicit amem_remember / API writes (including short “test”). */
+export declare function isUsefulRememberText(text: string): boolean;
 export declare function extractCaptureAnchors(text: string, repoRoot: string): string[];
 /** High-quality durable facts apply without waiting for amem_remember. */
 export declare function shouldAutoApplyProposal(proposal: Proposal): boolean;

package/dist/capture.js

@@ -8,9 +8,10 @@ import { applyProposal } from "./proposal.js";
 import { scoreProposal } from "./draft-quality.js";
 import { tokenJaccard } from "./search.js";
 import { isAutoApplyAll } from "./prefs.js";
-const TRIVIAL = /^(ok|okay|yes|yep|no|nah|thanks|thank you|continue|go ahead|sure|please)\.?$/i;
+const TRIVIAL = /^(ok|okay|yes|yep|no|nah|thanks|thank you|continue|go ahead|sure|please|test|testing|hello|hi|hey|ping|asdf|foo|bar)\.?$/i;
 const SECRET = /password|api[_-]?key|secret|token\s*[:=]|begin (rsa |openssh )?private/i;
 const PATH_RE = /\b(?:[\w.-]+\/)*[\w.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|md|json|yml|yaml|sql)\b/g;
+/** Reject empty / chat-noise / secret-like text before it becomes a claim. */
 export function isUsefulCaptureText(text) {
     const t = text.trim();
     if (t.length < 16)
@@ -21,6 +22,19 @@ export function isUsefulCaptureText(text) {
         return false;
     return true;
 }
+/** Same guard for explicit amem_remember / API writes (including short “test”). */
+export function isUsefulRememberText(text) {
+    const t = text.trim();
+    if (!t)
+        return false;
+    if (TRIVIAL.test(t))
+        return false;
+    if (t.length < 8)
+        return false;
+    if (SECRET.test(t))
+        return false;
+    return true;
+}
 export function extractCaptureAnchors(text, repoRoot) {
     const found = [...text.matchAll(PATH_RE)].map((m) => m[0]);
     const unique = [...new Set(found)].slice(0, 6);

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/hygiene.d.ts

@@ -23,9 +23,18 @@ export type HygienePreview = {
     /** Estimated active count after decay + merge */
     afterCleanup: number;
     softPaywall: boolean;
+    /** Active claims with kind=session (chat noise indicator). */
+    sessionCount: number;
+    /** sessionCount / active, 0 when empty. */
+    sessionRatio: number;
 };
 export declare const SOFT_PAYWALL_FACTS = 200;
 export declare const SOFT_PAYWALL_NOISE = 15;
+/** Soft-paywall when session chat takeaways dominate the graph. */
+export declare const SOFT_PAYWALL_SESSION_RATIO = 0.55;
+export declare const SOFT_PAYWALL_SESSION_MIN = 25;
+/** Unused unpinned session claims become decay candidates sooner than durable kinds. */
+export declare const SESSION_UNUSED_DAYS = 14;
 /** Free: counts only for soft paywall / banners. Never applies changes. */
 export declare function hygienePreview(repoId: string, unusedDays?: number): HygienePreview;
 /** Aggregate preview across all tracked repos (for All memory scope). */

package/dist/hygiene.js

@@ -10,6 +10,11 @@ import { tokenJaccard } from "./search.js";
 import { parseAnchors } from "./freshness.js";
 export const SOFT_PAYWALL_FACTS = 200;
 export const SOFT_PAYWALL_NOISE = 15;
+/** Soft-paywall when session chat takeaways dominate the graph. */
+export const SOFT_PAYWALL_SESSION_RATIO = 0.55;
+export const SOFT_PAYWALL_SESSION_MIN = 25;
+/** Unused unpinned session claims become decay candidates sooner than durable kinds. */
+export const SESSION_UNUSED_DAYS = 14;
 function usedClaimIds(repoId, days) {
     const ids = new Set();
     for (const event of listUsageEvents({ repoId, days })) {
@@ -29,14 +34,24 @@ function usedClaimIds(repoId, days) {
 function computeHygiene(repoId, unusedDays = 90) {
     const claims = listClaims(repoId);
     const used = usedClaimIds(repoId, unusedDays);
+    const usedSessions = usedClaimIds(repoId, SESSION_UNUSED_DAYS);
     const cutoff = Date.now() - unusedDays * 86_400_000;
+    const sessionCutoff = Date.now() - SESSION_UNUSED_DAYS * 86_400_000;
     const stale = claims.filter((c) => {
         if (Number(c.pinned || 0) > 0)
             return false;
+        const updated = Date.parse(c.updated_at);
+        if (!Number.isFinite(updated))
+            return false;
+        const isSession = (c.kind || "").toLowerCase() === "session";
+        if (isSession) {
+            if (usedSessions.has(c.id))
+                return false;
+            return updated < sessionCutoff;
+        }
         if (used.has(c.id))
             return false;
-        const updated = Date.parse(c.updated_at);
-        return Number.isFinite(updated) && updated < cutoff;
+        return updated < cutoff;
     });
     const duplicates = [];
     for (let i = 0; i < claims.length; i++) {
@@ -63,16 +78,40 @@ function computeHygiene(repoId, unusedDays = 90) {
         active: claims.length,
     };
 }
+function sessionStats(repoId) {
+    const claims = listClaims(repoId);
+    const active = claims.length;
+    const sessionCount = claims.filter((c) => (c.kind || "").toLowerCase() === "session").length;
+    const sessionRatio = active > 0 ? sessionCount / active : 0;
+    return { sessionCount, sessionRatio, active };
+}
+function softPaywallFrom(preview) {
+    if (hasFeature(FEATURE_HYGIENE))
+        return false;
+    const noise = preview.staleCount + preview.duplicateCount;
+    if (preview.active >= SOFT_PAYWALL_FACTS || noise >= SOFT_PAYWALL_NOISE)
+        return true;
+    if (preview.sessionCount >= SOFT_PAYWALL_SESSION_MIN &&
+        preview.sessionRatio >= SOFT_PAYWALL_SESSION_RATIO) {
+        return true;
+    }
+    return false;
+}
 /** Free: counts only for soft paywall / banners. Never applies changes. */
 export function hygienePreview(repoId, unusedDays = 90) {
     const report = computeHygiene(repoId, unusedDays);
+    const { sessionCount, sessionRatio } = sessionStats(repoId);
     const staleCount = report.stale.length;
     const duplicateCount = report.duplicates.length;
     const removable = Math.min(report.active, staleCount + duplicateCount);
     const afterCleanup = Math.max(0, report.active - removable);
-    const thresholdHit = report.active >= SOFT_PAYWALL_FACTS || staleCount + duplicateCount >= SOFT_PAYWALL_NOISE;
-    // Paid (hygiene unlocked) — never surface an unpaid soft-paywall signal.
-    const softPaywall = thresholdHit && !hasFeature(FEATURE_HYGIENE);
+    const softPaywall = softPaywallFrom({
+        active: report.active,
+        staleCount,
+        duplicateCount,
+        sessionCount,
+        sessionRatio,
+    });
     return {
         active: report.active,
         staleCount,
@@ -80,6 +119,8 @@ export function hygienePreview(repoId, unusedDays = 90) {
         pendingDrafts: report.pendingDrafts,
         afterCleanup,
         softPaywall,
+        sessionCount,
+        sessionRatio,
     };
 }
 /** Aggregate preview across all tracked repos (for All memory scope). */
@@ -88,18 +129,35 @@ export function hygienePreviewAll(unusedDays = 90) {
     let staleCount = 0;
     let duplicateCount = 0;
     let pendingDrafts = 0;
+    let sessionCount = 0;
     for (const repo of listRepos()) {
         const p = hygienePreview(repo.id, unusedDays);
         active += p.active;
         staleCount += p.staleCount;
         duplicateCount += p.duplicateCount;
         pendingDrafts += p.pendingDrafts;
+        sessionCount += p.sessionCount;
     }
     const removable = Math.min(active, staleCount + duplicateCount);
     const afterCleanup = Math.max(0, active - removable);
-    const thresholdHit = active >= SOFT_PAYWALL_FACTS || staleCount + duplicateCount >= SOFT_PAYWALL_NOISE;
-    const softPaywall = thresholdHit && !hasFeature(FEATURE_HYGIENE);
-    return { active, staleCount, duplicateCount, pendingDrafts, afterCleanup, softPaywall };
+    const sessionRatio = active > 0 ? sessionCount / active : 0;
+    const softPaywall = softPaywallFrom({
+        active,
+        staleCount,
+        duplicateCount,
+        sessionCount,
+        sessionRatio,
+    });
+    return {
+        active,
+        staleCount,
+        duplicateCount,
+        pendingDrafts,
+        afterCleanup,
+        softPaywall,
+        sessionCount,
+        sessionRatio,
+    };
 }
 export function hygieneReport(repoId, unusedDays = 90) {
     requireFeature(FEATURE_HYGIENE, "Memory hygiene");

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/backlog.md

@@ -37,16 +37,16 @@ Updated after completing the Feature Map **Later** phase (local embedding model
 
 ## Open
 
-- First npm publish of `@iamem/amem` (org `@iamem` already exists; need valid `NPM_TOKEN` / `npm login`, then tag `v0.1.0` or `npm publish --access public`).
 - Prompt-pack before/after Stats benchmark; restore wizard polish; IT seat pack.
 - Decide one-time vs subscription (offline files cannot revoke on cancel unless you add `expires_at` and re-issue).
 - Optional vendored ONNX/MiniLM weights in a paid pack (external command is the local hook today).
+- Move CI publish to npm Trusted Publishing (OIDC) before Jan 2027 GAT bypass-2FA publish sunset.
 
 ## Shipped (go-to-market / upsell)
 
 - Public Checkout at **getamem.com** (tryamem redirects); Stripe live webhook.
 - Mailtrap **live send** (`MAILTRAP_USE_TESTING=false`); thank-you download still works if mail fails.
-- Package renamed to `@iamem/amem` (CLI binary still `amem`); shop install copy updated.
+- **`@iamem/amem@0.1.0` on npm** — `npx @iamem/amem setup` / `npm i -g @iamem/amem` (CLI binary `amem`).
 - UI **Apply license** (paste/drop) + **Turn on Pro retrieval** checklist.
 - Memory **retrieval showdown** (free hash vs Pro n-gram) + top-bar **Try retrieval**.
 - Remember-contract guidance: prefer durable kinds; avoid `session` spam.

package/docs/enterprise-endpoint.md

@@ -30,7 +30,7 @@ The pack includes deny-by-default `policy.toml`, an MDM plist stub, `mdm-offboar
 
 ## Install (DevEx / IT)
 
-1. Ship a pinned amem build (internal npm, pkg, or `npm link` from a mirrored clone). Node 20+ required (`better-sqlite3`).
+1. Ship a pinned amem build: `npm i -g @iamem/amem` (or internal mirror / pkg). Node 20+ required (`better-sqlite3` prebuilds on common macOS/Linux).
 2. Deploy policy:
 
 ```bash
@@ -78,6 +78,7 @@ That is not a remote public API:
 - Nothing in `~/.amem` is uploaded or synced.
 - Binding is loopback-only — LAN/WAN clients cannot reach the UI by default.
 - Treat any process on the same machine as potentially able to call `127.0.0.1:7843` while the UI is running (same as any local MCP server).
+- Do not expose the UI on a non-loopback bind; policy forces loopback. Tightening `Access-Control-Allow-Origin` to specific Origins is optional and can break some MCP hosts — leave `*` unless you control every client Origin.
 
 ## Offboarding
 

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.0",
+  "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();
+}

package/ui-static/app.js

@@ -320,6 +320,8 @@ function writeUrlState() {
 
 function setTab(tab) {
   if (tab === "stats") tab = "analytics";
+  // Paid licenses: Plans is a sell page — don't open it; Setup still has Apply license.
+  if (tab === "welcome" && isPaidLicense()) tab = "dashboard";
   if (tab === "brain") {
     state.brainAll = true;
     persistBrainAll(true);
@@ -405,6 +407,7 @@ async function refreshVault() {
   } catch {
     state.license = state.status?.license || null;
   }
+  paintPlansNavVisibility(isPaidLicense());
   try {
     state.embed = await apiUnscoped("/api/embed");
   } catch {
@@ -1051,9 +1054,17 @@ function isPaidLicense() {
   const tier = String(state.license?.tier || state.status?.license?.tier || "free").toLowerCase();
   const paid = state.license?.valid !== false && (tier === "pro" || tier === "it");
   if (paid) persistLicenseTier(tier);
+  paintPlansNavVisibility(paid);
   return paid;
 }
 
+/** Paid users don't need the Plans sell tab in the sidebar (Setup still has Apply license). */
+function paintPlansNavVisibility(paid) {
+  const btn = document.querySelector('#tabs button[data-tab="welcome"]');
+  if (!btn) return;
+  btn.classList.toggle("hidden", Boolean(paid));
+}
+
 function licenseApplyHtml(idPrefix = "lic") {
   return `
     <div class="license-apply" id="${idPrefix}ApplyBox">
@@ -2098,14 +2109,20 @@ async function loadSoftPaywall() {
       return;
     }
     const noise = (preview.staleCount || 0) + (preview.duplicateCount || 0);
+    const sessions = Number(preview.sessionCount || 0);
+    const ratio = Number(preview.sessionRatio || 0);
+    const sessionHeavy = sessions >= 25 && ratio >= 0.55;
     const shop = state.shop || {};
     const proUrl = shop.proUrl || "https://getamem.com/buy/pro";
     el.classList.remove("hidden");
+    const why = sessionHeavy
+      ? `${preview.active} facts · <b>${Math.round(ratio * 100)}%</b> are short-lived <code>session</code> kinds (~${sessions}). Free preview → Pro applies Cleanup to archive unused sessions.`
+      : `${preview.active} facts · ~${noise} unused/duplicates → about <b>${preview.afterCleanup}</b> after cleanup. Free still works — this is optional.`;
     el.innerHTML = `
       <div class="soft-paywall-inner">
         <div>
-          <strong>Pro can clean this</strong>
-          <p class="note" style="margin:0.25rem 0 0">${preview.active} facts · ~${noise} unused/duplicates → about <b>${preview.afterCleanup}</b> after cleanup. Free still works — this is optional.</p>
+          <strong>${sessionHeavy ? "Session noise is crowding retrieval" : "Pro can clean this"}</strong>
+          <p class="note" style="margin:0.25rem 0 0">${why}</p>
         </div>
         <div class="soft-paywall-actions">
           <a class="btn small" href="${esc(proUrl)}" target="_blank" rel="noopener">Buy Pro · Apply cleanup</a>
@@ -3810,7 +3827,7 @@ async function render() {
 document.querySelectorAll("#tabs button[data-tab]").forEach((b) => {
   b.addEventListener("click", () => setTab(b.dataset.tab));
 });
-$("#brandBtn")?.addEventListener("click", () => setTab("welcome"));
+$("#brandBtn")?.addEventListener("click", () => setTab(isPaidLicense() ? "dashboard" : "welcome"));
 
 $("#brainSearch")?.addEventListener("input", (e) => {
   if (state.tab !== "brain") return;

package/ui-static/styles.css

@@ -1306,6 +1306,10 @@ a.btn {
   display: none;
 }
 
+.side-tabs button.hidden {
+  display: none !important;
+}
+
 .hidden {
   display: none !important;
 }