memhouse 0.4.2 → 0.4.3

package/bin/memhouse.js

@@ -320,6 +320,8 @@ Data         ship                 one incremental pass (--full | --loop [sec])
 
 Agents       plugins              list | install claude [--target DIR] | remove claude
              prompt               print the memory system-prompt snippet
+             prompt --install     print an install prompt for an agent, with this
+                                  machine's state and the one route that applies
 
 House        deploy --local       run ClickHouse in docker/podman, then install
              deploy --down        remove the local house (container + volume)
@@ -394,6 +396,129 @@ async function cmdDiscover() {
   return out;
 }
 
+/**
+ * Render the agent install prompt with this machine's facts.
+ *
+ * The value is in what it removes: the CLI has already probed for a house, an engine and
+ * an existing config, so the prompt can state the ONE route that applies. A static
+ * runbook makes the agent derive that from a decision tree, which is where it picks the
+ * wrong branch — most expensively by asking a user with no ClickHouse for a ClickHouse
+ * URL, which is exactly what onboard itself used to do.
+ */
+async function renderInstallPrompt() {
+  const tplPath = path.join(DELIVERY, 'AGENT-INSTALL-PROMPT.md');
+  const tpl = fs.readFileSync(tplPath, 'utf-8');
+  const body = tpl.split('<!-- PROMPT BODY BELOW -->')[1] || tpl;
+
+  const cfg = resolveConfig();
+  const configured = fs.existsSync(ENV_FILE);
+  const engines = deployableEngines();
+
+  // Probe rather than assume. JSON_OUT is forced off so cmdDiscover returns its object
+  // instead of printing JSON and returning undefined.
+  const saved = JSON_OUT;
+  let found = null;
+  try {
+    found = await withSuppressedOutput(() => cmdDiscover());
+  } catch { /* fall through to the unknown-state wording */ } finally { void saved; }
+
+  const editors = (found && found.editors || []).filter((e) => e.sessions > 0);
+  const reachable = (found && found.clickhouse || []).filter((p) => p.reachable);
+  const houseUp = reachable.length > 0;
+
+  // Is an existing install actually working, or configured-but-broken? A broken one is
+  // the case a plain "install it" prompt handles worst.
+  let state = 'not installed';
+  if (configured) {
+    let ok0 = false;
+    try { ok0 = !!(await ch(cfg, 'SELECT 1')); } catch { ok0 = false; }
+    state = ok0 ? 'installed and connected' : 'configured, but the house does not answer';
+  }
+
+  let plan;
+  if (state === 'installed and connected') {
+    plan = `memhouse is already installed and connected to \`${cfg.url}\` (database \`${cfg.db}\`).
+**Do not reinstall.** Verify and hand back:
+
+1. \`memhouse doctor\` — every line should be a check mark.
+2. \`memhouse status\` — note the session and message counts.
+3. If the shipper is not running: \`memhouse start\`.
+4. If \`doctor\` reports rooms missing, the house may predate 0.4.0; it will say so by
+   name and print the recovery. Follow what it prints rather than reinstalling.`;
+  } else if (state.startsWith('configured')) {
+    plan = `memhouse is configured to use \`${cfg.url}\` (database \`${cfg.db}\`) but that
+endpoint does not answer. Do NOT reconfigure before finding out why.
+
+1. Is the house simply stopped? If it was a local container, \`memhouse deploy --local\`
+   brings the same volume back — it does not lose data.
+2. Is it a remote house the user's network cannot reach right now? Ask them; do not
+   repoint their config at something else on your own initiative.
+3. Only once the user says the old house is gone for good should you set up a new one,
+   and then say plainly that past sessions re-ship from local transcripts but anything
+   whose transcript was deleted lives only in the old house.`;
+  } else if (houseUp) {
+    plan = `A ClickHouse is already reachable at \`${reachable[0].url}\`. Use it.
+
+1. \`npm install -g memhouse --allow-scripts=better-sqlite3\`
+   The flag is not optional — six adapters (cursor, zed, opencode, goose, windsurf,
+   antigravity) read SQLite stores and silently drop out without the native build.
+2. Ask the user for the ClickHouse username and password for that endpoint.
+3. \`memhouse install --url ${reachable[0].url} --user <user> --password <pw>\`
+   If they hold admin on it and want memhouse to create the user, database, rooms and
+   grants for them, use \`--admin-user\`/\`--admin-password\` instead; memhouse then
+   reconnects as the new member and never stores the admin credential.
+   If they would rather run the SQL themselves, \`memhouse install --print-sql\` prints
+   it and touches nothing.
+4. \`memhouse start\`.`;
+  } else if (engines.length) {
+    plan = `There is no ClickHouse to point at, but **${engines.join(' and ')}** is available,
+so memhouse can run one:
+
+1. \`npm install -g memhouse --allow-scripts=better-sqlite3\`
+   The flag is not optional — six adapters read SQLite stores and silently drop out
+   without the native build.
+2. \`memhouse deploy --local\`
+   This starts a loopback-only ClickHouse, generates a credential, installs, creates the
+   user's rooms and runs the first ship. One command, no questions.
+3. \`memhouse start\`.
+
+${process.platform === 'linux' && engines.includes('podman')
+    ? 'On Linux with rootless podman the container stops at logout unless lingering is on.\nIf memhouse warns about this, run what it prints (`loginctl enable-linger <user>`)\nand tell the user why it matters.' : ''}`;
+  } else {
+    plan = `There is no ClickHouse reachable and no container engine to run one with. You
+cannot finish this install alone — say so rather than improvising.
+
+Tell the user they need one of:
+- a ClickHouse they already run (Cloud, a server, a kernel house) plus its credentials;
+- docker or podman installed, after which \`memhouse deploy --local\` does everything.
+
+You can still do the harmless half now: \`npm install -g memhouse --allow-scripts=better-sqlite3\`,
+then \`memhouse discover\` to show them what would be shipped once a house exists.`;
+  }
+
+  const out = body
+    .replaceAll('{{VERSION}}', PKG.version)
+    .replaceAll('{{PLATFORM}}', `${process.platform}/${process.arch}`)
+    .replaceAll('{{NODE}}', process.versions.node)
+    .replaceAll('{{STATE}}', state)
+    .replaceAll('{{EDITORS}}', editors.length
+      ? editors.map((e) => `${e.source} (${e.sessions})`).join(', ')
+      : 'none found — memhouse would ship nothing until an editor is used')
+    .replaceAll('{{HOUSE}}', houseUp ? reachable.map((p) => p.url).join(', ') : 'none reachable')
+    .replaceAll('{{ENGINES}}', engines.length ? engines.join(', ') : 'none (no docker, no podman)')
+    .replaceAll('{{PLAN}}', plan.trim())
+    .replaceAll('{{PORT}}', String(cfg.port));
+  process.stdout.write(out.trimStart());
+  return 0;
+}
+
+/** Run a printing function with stdout swallowed, and give back its return value. */
+async function withSuppressedOutput(fn) {
+  const write = process.stdout.write.bind(process.stdout);
+  process.stdout.write = () => true;
+  try { return await fn(); } finally { process.stdout.write = write; }
+}
+
 /**
  * Can this machine stand up a house of its own?
  *
@@ -1123,7 +1248,13 @@ function cmdUninstall() {
       break;
     }
     case 'plugins': process.exitCode = cmdPlugins(); break;
-    case 'prompt': process.stdout.write(fs.readFileSync(path.join(DELIVERY, 'PROMPT.md'), 'utf-8')); break;
+    case 'prompt':
+      // Two audiences, two prompts. Bare `prompt` is the memory-USAGE snippet that goes
+      // into a running agent's system prompt; `--install` is the one you hand an agent
+      // that has not installed memhouse yet.
+      if (flags.install === true) process.exitCode = await renderInstallPrompt();
+      else process.stdout.write(fs.readFileSync(path.join(DELIVERY, 'PROMPT.md'), 'utf-8'));
+      break;
     case 'reset': process.exitCode = await cmdReset(); break;
     case 'deploy': {
       const dep = require(path.join(REPO_ROOT, 'mem-house', 'deploy.js'));

package/editors/antigravity.js

@@ -2,7 +2,16 @@ const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const Database = require('better-sqlite3');
+// Required lazily. A top-level require makes this native module a load-time dependency
+// of the whole adapter set: editors/index.js imports every adapter, so one missing
+// binding threw before any adapter ran and `discover` reported ZERO editors — losing the
+// eleven that need no native code at all. The adapterErrors path exists to degrade one
+// adapter at a time, and a top-level throw walks straight past it.
+let Database = null;
+function openDb(...a) {
+  if (!Database) Database = require('better-sqlite3');
+  return new Database(...a);
+}
 const { getAppDataPath } = require('./base');
 const adapterErrors = require('./adapter-errors');
 
@@ -235,7 +244,7 @@ function readGlobalStateValue(key) {
 
   let db = null;
   try {
-    db = new Database(ANTIGRAVITY_GLOBAL_STORAGE_DB, { readonly: true, fileMustExist: true });
+    db = openDb(ANTIGRAVITY_GLOBAL_STORAGE_DB, { readonly: true, fileMustExist: true });
     const row = db.prepare('SELECT value FROM ItemTable WHERE key = ?').get(key);
     if (!row) return null;
     const v = row.value;

package/editors/cursor.js

@@ -1,4 +1,13 @@
-const Database = require('better-sqlite3');
+// Required lazily. A top-level require makes this native module a load-time dependency
+// of the whole adapter set: editors/index.js imports every adapter, so one missing
+// binding threw before any adapter ran and `discover` reported ZERO editors — losing the
+// eleven that need no native code at all. The adapterErrors path exists to degrade one
+// adapter at a time, and a top-level throw walks straight past it.
+let Database = null;
+function openDb(...a) {
+  if (!Database) Database = require('better-sqlite3');
+  return new Database(...a);
+}
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
@@ -147,7 +156,7 @@ function getWorkspaceMap() {
 
 function getComposerHeaders(stateDbPath) {
   try {
-    const db = new Database(stateDbPath, { readonly: true });
+    const db = openDb(stateDbPath, { readonly: true });
     const row = db.prepare("SELECT value FROM ItemTable WHERE key = 'composer.composerData'").get();
     db.close();
     if (!row) return [];
@@ -277,7 +286,7 @@ function getChats() {
   // Source 1: ~/.cursor/chats store.db
   for (const { workspace, chatId, dbPath } of getAgentStoreChats()) {
     try {
-      const db = new Database(dbPath, { readonly: true });
+      const db = openDb(dbPath, { readonly: true });
       const meta = readStoreMeta(db);
       db.close();
       if (meta) {
@@ -316,7 +325,7 @@ function getChats() {
 
   // Source 2: workspaceStorage composers
   let globalDb = null;
-  try { globalDb = new Database(GLOBAL_STORAGE_DB, { readonly: true }); }
+  try { globalDb = openDb(GLOBAL_STORAGE_DB, { readonly: true }); }
   catch (e) {
     // Absent is normal — Cursor may simply not be installed. Unreadable is not.
     if (fs.existsSync(GLOBAL_STORAGE_DB)) adapterErrors.record('cursor', e, GLOBAL_STORAGE_DB);
@@ -369,7 +378,7 @@ function getChats() {
 
 function getMessages(chat) {
   if (chat._type === 'agent-store') {
-    const db = new Database(chat._dbPath, { readonly: true });
+    const db = openDb(chat._dbPath, { readonly: true });
     const msgs = collectStoreMessages(db, chat._rootBlobId);
     db.close();
     // Use lastUsedModel as fallback for assistant messages without model info
@@ -382,7 +391,7 @@ function getMessages(chat) {
   }
 
   let globalDb;
-  try { globalDb = new Database(GLOBAL_STORAGE_DB, { readonly: true }); }
+  try { globalDb = openDb(GLOBAL_STORAGE_DB, { readonly: true }); }
   catch (e) {
     // Returning [] unreported would let a re-ship overwrite this session's stored
     // transcript with nothing.
@@ -407,7 +416,7 @@ function getMessages(chat) {
 
 function getCursorAccessToken() {
   try {
-    const db = new Database(GLOBAL_STORAGE_DB, { readonly: true });
+    const db = openDb(GLOBAL_STORAGE_DB, { readonly: true });
     const row = db.prepare("SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken'").get();
     db.close();
     return row ? row.value : null;

package/editors/opencode.js

@@ -1,7 +1,16 @@
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const Database = require('better-sqlite3');
+// Required lazily. A top-level require makes this native module a load-time dependency
+// of the whole adapter set: editors/index.js imports every adapter, so one missing
+// binding threw before any adapter ran and `discover` reported ZERO editors — losing the
+// eleven that need no native code at all. The adapterErrors path exists to degrade one
+// adapter at a time, and a top-level throw walks straight past it.
+let Database = null;
+function openDb(...a) {
+  if (!Database) Database = require('better-sqlite3');
+  return new Database(...a);
+}
 const adapterErrors = require('./adapter-errors');
 
 // OpenCode stores data in XDG-style paths across all platforms
@@ -28,7 +37,7 @@ const DB_PATH = getOpenCodeDbPath();
 function queryDb(sql) {
   if (!fs.existsSync(DB_PATH)) return [];
   try {
-    const db = new Database(DB_PATH, { readonly: true });
+    const db = openDb(DB_PATH, { readonly: true });
     const rows = db.prepare(sql).all();
     db.close();
     return rows;
@@ -85,7 +94,7 @@ function getSqliteSessions() {
 function getSqliteMessages(sessionId) {
   if (!fs.existsSync(DB_PATH)) return [];
   try {
-    const db = new Database(DB_PATH, { readonly: true });
+    const db = openDb(DB_PATH, { readonly: true });
     const messages = db.prepare(
       `SELECT m.id as msg_id, m.data as msg_data, m.time_created
        FROM message m WHERE m.session_id = ? ORDER BY m.time_created ASC`

package/editors/zed.js

@@ -2,7 +2,16 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
-const Database = require('better-sqlite3');
+// Required lazily. A top-level require makes this native module a load-time dependency
+// of the whole adapter set: editors/index.js imports every adapter, so one missing
+// binding threw before any adapter ran and `discover` reported ZERO editors — losing the
+// eleven that need no native code at all. The adapterErrors path exists to degrade one
+// adapter at a time, and a top-level throw walks straight past it.
+let Database = null;
+function openDb(...a) {
+  if (!Database) Database = require('better-sqlite3');
+  return new Database(...a);
+}
 const adapterErrors = require('./adapter-errors');
 
 // Zed stores data in different locations depending on the platform
@@ -69,7 +78,7 @@ function decompressZstd(buf) {
 function queryDb(sql) {
   if (!fs.existsSync(THREADS_DB)) return [];
   try {
-    const db = new Database(THREADS_DB, { readonly: true });
+    const db = openDb(THREADS_DB, { readonly: true });
     const rows = db.prepare(sql).all();
     db.close();
     return rows;
@@ -91,7 +100,7 @@ function getThreadColumns() {
   if (threadColumns) return threadColumns;
   if (!fs.existsSync(THREADS_DB)) return new Set();
   try {
-    const db = new Database(THREADS_DB, { readonly: true });
+    const db = openDb(THREADS_DB, { readonly: true });
     const cols = db.prepare('PRAGMA table_info(threads)').all().map((r) => r.name);
     db.close();
     // PRAGMA on a missing or renamed table SUCCEEDS with zero rows rather than
@@ -122,7 +131,7 @@ function resetCache() {
 function queryBlob(id) {
   if (!fs.existsSync(THREADS_DB)) return null;
   try {
-    const db = new Database(THREADS_DB, { readonly: true });
+    const db = openDb(THREADS_DB, { readonly: true });
     const row = db.prepare('SELECT data FROM threads WHERE id = ?').get(id);
     db.close();
     return row ? row.data : null;

package/mem-house/delivery/AGENT-INSTALL-PROMPT.md

@@ -0,0 +1,58 @@
+# memhouse — agent install prompt (template)
+
+`memhouse prompt --install` renders this with THIS machine's facts substituted and
+prints it. Feed the output to a coding agent; it has everything needed to install and
+onboard without asking the user to look anything up.
+
+The point of rendering rather than shipping a static runbook: the CLI has already
+probed the machine, so the prompt states the route that applies instead of making the
+agent reason through a decision tree and possibly pick wrong. `AGENT-INSTALL.md` is the
+static long-form version, and it predates `deploy --local`.
+
+Placeholders are `{{NAME}}`. Everything below the marker is the prompt body.
+
+<!-- PROMPT BODY BELOW -->
+You are installing **memhouse** for the user on this machine.
+
+memhouse gives a coding agent long-term memory of past sessions. It reads the session
+transcripts your editors already write to disk — 17 of them — parses them locally, and
+ships typed rows into ClickHouse. Nothing is intercepted or proxied; it reads files that
+already exist.
+
+## What this machine looks like right now
+
+- memhouse version: **{{VERSION}}**
+- platform: {{PLATFORM}}, node {{NODE}}
+- current state: **{{STATE}}**
+- editors with sessions found: {{EDITORS}}
+- reachable ClickHouse: {{HOUSE}}
+- container engines available: {{ENGINES}}
+
+## Your task
+
+{{PLAN}}
+
+## Rules that matter
+
+- **Never invent a credential.** If a step needs a password for a house the user already
+  runs, ask them for it. Do not guess, do not read it out of a file they did not name.
+- **Do not run `deploy --down`.** It destroys the container *and its volume*. It is never
+  part of an install.
+- The install writes `~/.memhouse/env` at mode 0600. Do not print its contents; do not
+  echo a password into the transcript you are writing, which memhouse will then ship.
+- If a command fails, read what it printed before retrying. memhouse's failures name the
+  cause and usually name the fix — it is not a generic tool that fails generically.
+- Rooms are named for the ClickHouse user: `sessions_<them>`, `messages_<them>`,
+  `tool_calls_<them>`. There are no unsuffixed tables. If you write a query, suffix it.
+
+## When you are done
+
+Run `memhouse doctor` and report its output to the user. Every line should be a check
+mark. Then tell them:
+
+- where the dashboard is (`http://localhost:{{PORT}}`) and that `memhouse start` runs it
+- that `memhouse search <terms>` searches every past session from every editor
+- that you can now search their history yourself, and offer to try one query
+
+If `doctor` reports a failure, say which line failed and what memhouse suggested. Do not
+declare success on a partial install.

package/mem-house/delivery/AGENT-INSTALL.md

@@ -1,7 +1,13 @@
 # mem-house — agent install
 
 Imperative steps for an AI coding agent installing mem-house on a machine. Execute
-in order; every command is copy-pasteable. Prereqs: Node >= 20.19 and a reachable
+in order; every command is copy-pasteable.
+
+**Prefer `memhouse prompt --install`.** It renders `AGENT-INSTALL-PROMPT.md` against the
+machine it runs on — which editors have sessions, whether a ClickHouse answers, whether
+docker or podman exists — and states the one route that applies. This file is the static
+long-form version and assumes a reachable ClickHouse already exists, which is the case
+`deploy --local` was added to remove. Prereqs: Node >= 20.19 and a reachable
 ClickHouse >= 26.2 (local server, Cloud, or a kernel house — see
 `kernel-install.md` for the kernel path). No checkout required — memhouse is on npm.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memhouse",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "memhouse — agent conversation memory across 17 editors: parse-on-client shippers, a typed ClickHouse store with one set of rooms per member, kernel-agency install, and the agentlytics dashboard",
   "main": "bin/memhouse.js",
   "bin": {