@iamem/amem 0.1.1 → 0.1.3

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:
@@ -156,7 +184,8 @@ Tabs after setup:
 
 1. **Setup** — scan/select repos, platforms, login auto-start, bootstrap proposal  
 2. **Memory** — facts by file, scored drafts (approve / replace older / dismiss / reject noisy), edit/pin/delete, search, recent hits/misses  
-3. **Stats** — estimated tokens saved per LLM, plus JSON / markdown / PDF export (proxies, not a bill)
+3. **Tasks** — per-project Kanban for deferred agent work (Backlog → Next → Doing → Blocked → Done). MCP: `amem_task_add` / `amem_task_update` / `amem_task_complete`. Open tasks appear in `amem_context`. Use Memory for durable facts; Tasks for “do later.”  
+4. **Stats** — estimated tokens saved per LLM, plus JSON / markdown / PDF export (proxies, not a bill)
 
 Server-only (no browser open):
 
@@ -225,6 +254,8 @@ Memory is a small local graph in SQLite:
 | **Claim** | A durable fact with file anchors (may be `active` or `superseded`; optional pin) |
 | **Edge** | Links (claim → flow → component); `kind: "supersedes"` archives the target claim |
 | **Draft** | Pending session / miss→learn proposals waiting for Memory approve |
+| **Task** | Deferred work on the project Kanban (Backlog / Next / Doing / Blocked / Done) — not a durable fact |
+| **Skill** | A reusable multi-step procedure, stored as a `SKILL.md` file (see below) |
 | **Usage event** | Each `amem context` hit + token estimate |
 
 Claims are the retrieval unit. Ranking combines:
@@ -252,6 +283,60 @@ Example claim:
 
 ---
 
+## Skills (procedural memory)
+
+Claims answer *what is true*. Skills answer *how we do this here* — a deploy sequence, a
+migration dance, a debugging path someone already walked. They are too long to sit in every
+prompt, so they load on demand.
+
+Skills live as `SKILL.md` files under `~/.amem/skills/`, indexed in SQLite for ranking:
+
+```
+~/.amem/skills/deploy-staging/SKILL.md
+~/.amem/skills/deploy-staging/references/runbook.md
+```
+
+**Progressive disclosure.** A context packet carries only names and descriptions. The agent
+calls `amem_skill_view` to pull a body once it decides the procedure applies, so an unused
+library of skills costs almost no tokens.
+
+**The learning loop.** amem ships no model, so it never writes a skill itself. At session end
+it looks for the shape of a hard-won procedure — enumerated steps or real commands, plus an
+error it recovered from or a correction you gave. When several signals line up it queues one
+suggestion, which reaches your agent as a nudge in the next context packet. The agent writes
+the skill; you approve it. If a skill was loaded during a session that still went sideways,
+amem queues a revision instead of a duplicate.
+
+The bar is deliberately high, and a session can queue at most one suggestion.
+
+```bash
+amem skills list                # index of what is stored
+amem skills show deploy-staging # full body
+amem skills new deploy-staging --desc "Deploy staging and verify health"
+amem skills import ./some-skill # bring in an agentskills.io skill
+amem skills drafts              # pending suggestions and staged writes
+amem skills approve <draft-id>
+```
+
+Skills are also a Skills tab in `amem ui`.
+
+**Safety.** Skills are instructions an agent will follow, so content is scanned for
+credentials and prompt-injection patterns before any write. Three policy keys control them:
+
+| Key | Default | Effect |
+| --- | --- | --- |
+| `skills_enabled` | `true` | Master switch for storage, ranking, and injection |
+| `skill_write_approval` | `false` | Stage agent writes for review instead of writing to disk |
+| `skill_capture` | `true` | Allow session-end skill suggestions |
+
+An unreadable `policy.toml` forces `skill_write_approval` on. `amem doctor --attest` reports
+every installed skill with a content hash, so you can diff what agents are being told to do.
+
+> Backups currently copy the database only — `~/.amem/skills/` is not included yet. Keep
+> skills you care about in version control until that lands.
+
+---
+
 ## Token savings (estimates)
 
 Every `amem context` logs a usage event. The UI **Stats** tab breaks this down by platform (`cursor`, `claude`, …).
@@ -352,6 +437,9 @@ MCP tools (stdio or HTTP):
 | `amem_context` | Ranked memory packet for the current question |
 | `amem_remember` | Store a durable fact after an outcome |
 | `amem_recipe` | Generic read-then-write contract (any MCP host) |
+| `amem_skill_list` | Cheap index of stored procedures (names + descriptions only) |
+| `amem_skill_view` | Load one skill body, after the index says it applies |
+| `amem_skill_save` | Store a multi-step procedure you just worked out |
 | `amem_repos` | What is monitored (git repos + named workspaces) |
 | `amem_stats` | Lookup time, estimated tokens/ms saved, hit rate |
 | `amem_graph` | Claims / components / flows stored for a workspace or repo |
@@ -372,6 +460,8 @@ amem doctor [--attest] [--json]
 amem context "<query>" [--workspace <name>] [--platform …]
 amem remember "<text>" [--workspace <name>] [--kind …] [--anchor <path>]
 amem recipe [--json]
+amem skills list|show <name>|new <name> [--desc <text>]|rm <name>|sync|import <path>
+amem skills drafts|approve <draft-id>|dismiss <draft-id>
 amem mcp [--print-config] [--workspace <name>]
 amem propose validate|diff|apply <file.json>
 amem export [--out <file.json>]
@@ -388,6 +478,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
 ```
 
@@ -399,11 +490,13 @@ amem service install|uninstall|status
 | `context` | Retrieve a Markdown packet; log usage |
 | `remember` | Store one local fact |
 | `mcp` | Stdio MCP tools; HTTP MCP at `http://127.0.0.1:7843/mcp` while UI runs |
+| `skills` | Manage procedural memory (`list`, `show`, `new`, `import`, `drafts`, `approve`) |
 | `propose diff` | Preview claim/component/flow changes before apply |
 | `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 +583,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);
+});