memhouse 0.12.6 → 0.13.0

package/README.md

@@ -76,12 +76,22 @@ memhouse update [--check]                  upgrade, restart daemons, check the s
 memhouse start | stop                      dashboard + shipper as daemons
 memhouse service install | uninstall       survive a reboot
 memhouse deploy --local | --down           stand up (or remove) a local house
-memhouse plugins install claude            /mem:search, :sessions, :sql —
-                                           into every Claude Code config dir found
+memhouse invite <name>                     mint a member + house, hand them one env file
+memhouse passwd                            rotate this member's password
+memhouse migrate | migrate-rooms [--dry-run] [--yes]
+                                           run whatever this house still needs
+memhouse relocate --to <url>               copy this house to a new ClickHouse, then repoint
+memhouse nightly [--out DIR]               build an installable tarball from this checkout
+memhouse plugins install claude            9 skills — ask, hello, invite, search,
+                                           sessions, share, sql, status, users — into
+                                           every Claude Code config dir found
 memhouse prompt                            memory snippet for an agent's system prompt
 memhouse prompt --install                  an install prompt, rendered for this machine
 ```
 
+Any command's own usage: `memhouse <command> --help` (or `-h`) — always prints usage,
+never runs the command.
+
 Every command works both ways: interactive for you, `--yes` / flags / `--json` for
 an agent — so an agent can install its own memory unattended.
 

package/bin/memhouse.js

@@ -326,7 +326,8 @@ Setup        onboard              interactive wizard: discover → configure →
              invite <name>        mint a member + house on the server and write the env
                                   file their install needs (--url --admin-user
                                   --admin-password [--db NAME] [--out FILE]); local
-                                  machine untouched
+                                  machine untouched. Refuses a house that already holds
+                                  someone's messages — --adopt if sharing it is intended
              passwd               rotate this member's password + rewrite the env file
                                   (admin-assisted: --admin-user --admin-password)
                                   --print-sql            print the SQL, run it yourself
@@ -667,15 +668,13 @@ CREATE USER IF NOT EXISTS ${member} IDENTIFIED BY '${password.replace(/'/g, "\\'
 
 ${rooms.trim()}
 
--- The whole database. ALL on your own house reaches nothing outside it — the database is
--- the boundary — and it is what lets the shipper create and evolve its own tables.
-GRANT ALL ON ${db}.* TO ${member};
-
--- SELECT again, WITH GRANT OPTION — sharing, made self-serve and read-only by
--- construction. This is what lets the member run \`GRANT SELECT ON ${db}.* TO <friend>\`
--- themselves (/mem:share) without an operator, while the grant-option stops at SELECT:
--- they can open a read-only window into their own memory and can hand on nothing more.
-GRANT SELECT ON ${db}.* TO ${member} WITH GRANT OPTION;
+-- The whole database, WITH GRANT OPTION. ALL on your own house reaches nothing outside it
+-- — the database is the boundary — and it lets the shipper create and evolve its own
+-- tables. The grant option makes the member the real owner: they can hand on any of their
+-- own data (\`/mem:share\` still opens only a read-only SELECT window, but the owner is not
+-- boxed into read-only sharing of their own house). Scoped to this db, and no CREATE USER
+-- rides with it — a member still cannot mint accounts or reach another house.
+GRANT ALL ON ${db}.* TO ${member} WITH GRANT OPTION;
 
 -- Self-scoped ALTER USER: the member may change THEIR OWN password and no one else's.
 -- \`ON ${member}\` names exactly this user, so \`memhouse passwd\` needs no admin, and an
@@ -692,6 +691,12 @@ GRANT ALTER USER ON ${member} TO ${member};
 -- It grants no read of anyone's rows; reading a housemate's memory still needs /mem:share.
 GRANT SHOW USERS ON *.* TO ${member};
 
+-- \`memhouse relocate\` runs FROM the destination, pulling the source over remoteSecure() —
+-- a table function ClickHouse gates behind its own access type, separate from GRANT ALL on
+-- a database. Without this, relocate fails at the native-reachability probe with
+-- ACCESS_DENIED (source untouched, nothing lost — just unusable until granted).
+GRANT REMOTE ON *.* TO ${member};
+
 -- Pin async_insert on the user (ADD SETTING merges; a bare SETTINGS clause would replace
 -- the user's whole list). The pin keeps the user_id stamp honest: a MATERIALIZED
 -- currentUser() is computed during the INSERT, and an async flush stores it as the empty
@@ -788,11 +793,12 @@ async function adminBootstrap(cfg, admin) {
   // reaches nothing outside the database, and it is what lets the member's own shipper
   // create and evolve the rooms (--ensure-schema below).
   try {
-    await q(`GRANT ALL ON ${cfg.db}.* TO ${admin.member}`, { database: '' });
-    // SELECT again, WITH GRANT OPTION: what /mem:share rides on. The member can open a
-    // read-only window into their OWN house for a housemate-to-be — and can hand on
-    // nothing more, because the grant option stops at SELECT.
-    await q(`GRANT SELECT ON ${cfg.db}.* TO ${admin.member} WITH GRANT OPTION`, { database: '' });
+    // ALL, WITH GRANT OPTION: the database is theirs, so they may do anything with their
+    // own data AND hand any of it on. /mem:share still opens only a read-only window (it
+    // grants SELECT), but the owner is not boxed into read-only sharing of their own house.
+    // Scoped to their db: the grant option reaches nothing outside it, and no CREATE USER
+    // comes with it, so a member still cannot mint accounts or touch another house.
+    await q(`GRANT ALL ON ${cfg.db}.* TO ${admin.member} WITH GRANT OPTION`, { database: '' });
     // Self-scoped ALTER USER — the member owns their own password (memhouse passwd needs
     // no admin; an invitee can rotate the password the inviter set). Non-escalating: the
     // grant names this one user, so it reaches no other account. Best-effort: a house on
@@ -806,8 +812,16 @@ async function adminBootstrap(cfg, admin) {
     // Best-effort like ALTER USER above — an admin without access-management just skips it.
     try { await q(`GRANT SHOW USERS ON *.* TO ${admin.member}`, { database: '' }); }
     catch { /* no access-management: /mem:users section 4 stays admin-only for this member */ }
+    // REMOTE: `memhouse relocate` runs FROM the destination, pulling the source over
+    // remoteSecure() — a table function ClickHouse gates behind its own access type,
+    // separate from any GRANT ALL on a database. Without it every relocate a member runs
+    // fails at the native-reachability probe with ACCESS_DENIED, source untouched, no
+    // data lost — just relocate unusable until an admin grants this by hand. Best-effort
+    // like the two grants above.
+    try { await q(`GRANT REMOTE ON *.* TO ${admin.member}`, { database: '' }); }
+    catch { /* no access-management: relocate stays admin-assisted for this member */ }
     await q(`ALTER USER ${admin.member} ADD SETTING ${MEMBER_PIN}`, { database: '' });
-    console.log(ok(`granted the house: ALL ON ${cfg.db}.* to '${admin.member}', SHOW USERS, async_insert pinned`));
+    console.log(ok(`granted the house: ALL ON ${cfg.db}.* to '${admin.member}', SHOW USERS, REMOTE, async_insert pinned`));
   } catch (e) {
     console.log(bad(`could not grant the house to '${admin.member}': ${e.message}`));
     if (createdUser) {
@@ -2899,7 +2913,7 @@ async function cmdNightly() {
  */
 async function cmdInvite() {
   const name = positional[0];
-  if (!name) { console.log('usage: memhouse invite <name> --url <house-url> --admin-user … --admin-password … [--db <house>] [--out <file>]'); return 2; }
+  if (!name) { console.log('usage: memhouse invite <name> --url <house-url> --admin-user … --admin-password … [--db <house>] [--out <file>] [--adopt]'); return 2; }
   try { require(path.join(REPO_ROOT, 'memhouse', 'house', 'house')).assertUsableName(name, 'member'); }
   catch (e) { console.log(bad(e.message)); return 1; }
   const cfg = resolveConfig();
@@ -2952,6 +2966,42 @@ async function cmdInvite() {
   // EXPLICIT --admin-* (where the admin typed the target themselves) provisions at --url.
   // Either way the invite FILE carries --url, the invitee's path.
   const provisionUrl = flags['admin-user'] ? url : cfg.url;
+
+  // Is there already a house here, with somebody's memory in it? The house is created
+  // with CREATE DATABASE IF NOT EXISTS, so inviting a name whose database already exists
+  // ADOPTS it — same output as a fresh one, and the invitee lands on top of rows that are
+  // not theirs. (The user half is safe: adminBootstrap refuses an existing ClickHouse
+  // user, so no sitting member's password is ever rotated out from under them.)
+  //
+  // Found the hard way: an invite meant for one person was sent to another, who shipped
+  // 3,733 messages under it. Re-inviting the intended person reported success and handed
+  // them the first person's memory, with nothing on any surface saying so.
+  //
+  // Read-only, best-effort: an admin that cannot count rows should not lose the ability
+  // to invite, and a house that does not exist yet is the ordinary case.
+  const adminCfg = { ...cfg, url: provisionUrl, user: adminUser, password: adminPass || '', db, stated: true };
+  let occupied = null;
+  try {
+    const exists = await chRows(adminCfg, `SELECT count() AS n FROM system.tables WHERE database = '${db.replace(/'/g, "\\'")}' AND name = 'messages'`, { database: '' });
+    if (Number(exists[0] && exists[0].n) > 0) {
+      const r = await chRows(adminCfg, 'SELECT count() AS msgs, uniqExact(user_id) AS writers FROM messages', { database: db });
+      const msgs = Number(r[0] && r[0].msgs) || 0;
+      if (msgs > 0) occupied = { msgs, writers: Number(r[0].writers) || 0 };
+    }
+  } catch { /* cannot tell — provisioning below will surface any real access problem */ }
+  if (occupied && flags.adopt !== true) {
+    console.log(bad(`house '${db}' already exists and holds ${occupied.msgs} messages from ${occupied.writers} writer(s) — NOT inviting.`));
+    console.log(`  Inviting '${name}' here would hand them somebody else's memory, and their`);
+    console.log('  first ship would land on top of it. Nothing has been changed.');
+    console.log('  Pick a different handle:   memhouse invite <other-name> --url …');
+    console.log(`  Or a different house:      memhouse invite ${name} --url … --db <house>`);
+    console.log(`  If sharing this house IS the intent, say so:  --adopt`);
+    return 1;
+  }
+  if (occupied) {
+    console.log(warn(`adopting existing house '${db}' — ${occupied.msgs} messages already here (--adopt)`));
+  }
+
   const built = await adminBootstrap({ ...cfg, url: provisionUrl, db, stated: true }, {
     user: adminUser, password: adminPass || '', member: name, quiet: true,
   });
@@ -3203,6 +3253,13 @@ async function cmdUninstall() {
   if (flags.version === true || process.argv.slice(2).some((a) => a === '-v' || a === '-V')) {
     console.log(PKG.version); return;
   }
+  // `memhouse <cmd> --help` (or `-h`) must never reach a command's own logic — passwd,
+  // invite, uninstall and friends act on first call with no separate confirm step, so a
+  // --help that fell through to the default branch would DO the thing instead of
+  // describing it. One check ahead of the switch, for every command, is the whole fix.
+  if (cmd && (flags.help === true || process.argv.slice(2).some((a) => a === '-h' || a === '--help'))) {
+    console.log(HELP); return;
+  }
   const cfg = resolveConfig();
 
   switch (cmd) {

package/memhouse/delivery/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mem",
-  "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: ask, search, browse, analyze, check, share, and invite across all 17 supported editors and machines. Skills install as /mem:hello, /mem:ask, /mem:search, /mem:sessions, /mem:share, /mem:invite, /mem:sql, /mem:status, and /mem:users.",
-  "version": "0.12.6",
+  "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: ask, search, browse, analyze, check, share, and invite across all 17 supported editors and machines, plus administration of the ClickHouse behind it. Skills install as /mem:hello, /mem:ask, /mem:search, /mem:sessions, /mem:share, /mem:invite, /mem:sql, /mem:status, /mem:users, and /mem:admin.",
+  "version": "0.13.0",
   "author": {
     "name": "Ramazan Polat"
   },

package/memhouse/delivery/plugin/skills/admin/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: admin
+description: Operate the memhouse ClickHouse as its administrator — list and inspect every user and house, provision or remove members, grant and revoke access, and read server-wide health (disk, parts, mutations, running queries). Use when the user asks to "do X as admin", "manage users", "drop a house", "see disk usage", "who is on this server", or when a member-scoped skill refused for want of privileges. Requires an admin credential; says so plainly when there is not one.
+user-invocable: true
+argument-hint: "<what you want done>"
+allowed-tools: Bash
+---
+
+# /mem:admin — operate the house as its administrator
+
+A member owns one database. An **administrator** owns the ClickHouse: every house, every
+account, every grant. This skill is the second one, and it is the only skill allowed to
+act outside the caller's own house.
+
+Everything here runs through the same rule as `/mem:invite`: **an admin password must
+never enter this conversation.** memhouse ships this transcript into the house you are
+administering, so a password pasted in chat is a password published to the archive.
+Resolve it from the environment or a file, never from a prompt, and never echo it.
+
+## 1. Find an admin credential — never ask for one in chat
+
+Try these in order and stop at the first that works. **Never print any of these files or
+the variables in them** — no `cat`, no `env | grep`, no `set -x`.
+
+```bash
+MH_HOME="${MEMHOUSE_HOME:-$HOME/.memhouse}"
+# a) an explicit admin credential in the environment
+ADM_U=${MEMHOUSE_ADMIN_USER-}; ADM_P=${MEMHOUSE_ADMIN_PASSWORD-}
+# b) an admin env file kept beside the member config
+if [ -z "$ADM_U" ] && [ -f "$MH_HOME/admin.env" ]; then
+  set -a; . "$MH_HOME/admin.env"; set +a
+  ADM_U=${MEMHOUSE_ADMIN_USER:-${MEMHOUSE_USER-}}; ADM_P=${MEMHOUSE_ADMIN_PASSWORD:-${MEMHOUSE_PASSWORD-}}
+fi
+# c) the ordinary member credential — on a house the pilot stood up themselves
+#    (memhouse deploy --local) the member IS the superuser
+set -a; [ -f "$MH_HOME/env" ] && . "$MH_HOME/env"; set +a
+: "${ADM_U:=${MEMHOUSE_USER-}}"; : "${ADM_P:=${MEMHOUSE_PASSWORD-}}"
+```
+
+Then **prove** it is actually an admin rather than assuming — a member can often read
+`system.users` while holding nothing else:
+
+```bash
+curl -sS --fail-with-body --user "$ADM_U:$ADM_P" \
+  --data-binary "SHOW GRANTS FOR $ADM_U FORMAT TSV" "$MEMHOUSE_URL/"
+```
+
+Admin means the grants carry `ACCESS MANAGEMENT`, or `CREATE USER`/`CREATE DATABASE` at
+`*.*` — not merely `SHOW USERS`, which every member has. If none of a/b/c qualifies,
+**stop and say so**:
+
+> This needs administrator access to the ClickHouse at `<url>`, and the credential
+> configured here is the member account `<user>` — it owns its own house and nothing
+> else. To use `/mem:admin`, put an admin credential in `~/.memhouse/admin.env`
+> (`MEMHOUSE_ADMIN_USER=` / `MEMHOUSE_ADMIN_PASSWORD=`, mode 600) or export
+> `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD`, then ask again. Whoever operates
+> the server has it; on a house from `memhouse deploy --local` it is the account already
+> in `~/.memhouse/env`.
+
+Do not offer to carry on with reduced powers, do not suggest the user paste a password
+into the chat, and do not improvise around the refusal. Say which of a/b/c you tried.
+
+## 2. Run the request
+
+Use the resolved credential for every query. `--fail-with-body` so ClickHouse's own error
+is visible; add `&readonly=1` on anything that only reads.
+
+```bash
+adm() { curl -sS --fail-with-body --user "$ADM_U:$ADM_P" --data-binary "$1" "$MEMHOUSE_URL/${2-}"; }
+adm "SELECT …  FORMAT PrettyCompact" "?readonly=1"
+```
+
+Reads worth knowing — reach for these before inventing SQL:
+
+| Question | Query |
+|---|---|
+| who exists | `SELECT name FROM system.users ORDER BY name` |
+| what can someone do | `SHOW GRANTS FOR <user>` |
+| every house and its size | `SELECT database, formatReadableSize(sum(bytes_on_disk)) AS disk, sum(rows) AS rows FROM system.parts WHERE active GROUP BY database ORDER BY sum(bytes_on_disk) DESC` |
+| a house's rooms | `SELECT table, formatReadableSize(sum(bytes_on_disk)) AS disk, sum(rows) AS rows FROM system.parts WHERE active AND database = '<db>' GROUP BY table` |
+| who writes where | `SELECT user_id, host, count() FROM <db>.messages GROUP BY user_id, host` |
+| running queries | `SELECT query_id, user, elapsed, formatReadableSize(memory_usage) AS mem, substring(query,1,120) AS q FROM system.processes` |
+| unfinished mutations | `SELECT database, table, mutation_id, command, parts_to_do, latest_fail_reason FROM system.mutations WHERE NOT is_done` |
+| merge backlog | `SELECT database, table, elapsed, progress FROM system.merges` |
+
+Writes follow the shapes memhouse itself uses, so an admin-made member is identical to an
+invited one — a member gets `GRANT ALL ON <db>.* … WITH GRANT OPTION`, plus `SHOW USERS`,
+self-scoped `ALTER USER`, `REMOTE`, and the async-insert pin. **Prefer the CLI over raw
+SQL when one exists**: `memhouse invite <name> --url …` provisions a member correctly
+(and refuses a house that already holds someone's messages); this skill is for the things
+it does not cover.
+
+## 3. Destructive work — look first, then confirm
+
+`DROP DATABASE`, `DROP USER`, `REVOKE`, `ALTER … DELETE`, `TRUNCATE`, `KILL QUERY` and
+password rotation all change something a person depends on. There are no backups and no
+undo: a dropped house is gone, and the transcripts behind it may have aged out of the
+editors that produced them.
+
+Before any of them:
+
+1. **Look at the target and report what is actually there** — row counts per room, who
+   wrote them, the date span, which machines. A house you expected to be empty may not
+   be.
+2. **Name the collateral.** Dropping a user stops that account's shipper on every machine
+   it runs on. Revoking a grant closes a share the other person may be mid-query on.
+   Rotating a password breaks every machine shipping under it.
+3. **Get an explicit yes for that specific object**, quoting the counts you just read.
+   A general "yes do admin things" is not consent to drop a populated house.
+4. **Verify afterwards** and say what is now true.
+
+If the user has already told you exactly what to destroy and why, and the counts match
+their description, proceed — do not re-litigate a decision they have made. Report the
+outcome plainly, including the row counts destroyed.
+
+## Never
+
+Never accept an admin password typed into the conversation, and never print one — not in
+a command, not in an echo, not in an error. If a command needs it, expand a shell
+variable (`--admin-password "$ADM_P"`), so the value never appears in the transcript.
+
+Never widen a member's grants beyond what `memhouse invite` issues without the user
+asking for that specific privilege and being told what it allows. Never grant
+`ACCESS MANAGEMENT`, `CREATE USER`, or anything at `*.*` casually — those make a second
+administrator.
+
+Never touch a house that is not the subject of the request. Never run a destructive
+statement whose predicate you have not first run as a `SELECT`.

package/memhouse/delivery/plugin/skills/invite/SKILL.md

@@ -30,9 +30,10 @@ substituted into a command — that burns the credential into the transcript on
    Only ask about a **shared house** if the user brings one up; default is the invitee's
    own house (omit --db; never pass `--db default` for "the default house").
 
-3. TRY IT BARE FIRST — run this via the Bash tool. `memhouse invite` uses the caller's
-   OWN configured credential when it can manage users, which is the common case for
-   whoever set the house up, so no admin is needed:
+3. TRY IT BARE FIRST — run this via the Bash tool, from the directory the file should
+   land in (step 4). `memhouse invite` uses the caller's OWN configured credential when
+   it can manage users, which is the common case for whoever set the house up, so no
+   admin is needed:
 
    ```
    memhouse invite <name> --url <url> [--db <shared-house>]
@@ -50,16 +51,52 @@ substituted into a command — that burns the credential into the transcript on
    memhouse invite <name> --url <url> [--db <shared-house>] --admin-user <admin> --admin-password 'PASTE_IT_HERE'
    ```
 
-4. When it succeeds it prints `invite written: invite-<name>.env`. Relay to the user:
-   - hand `invite-<name>.env` to the invitee over a trusted channel (croc, a password
-     manager — not chat); the file IS a password
-   - the invitee runs `memhouse install --env invite-<name>.env` — it OFFERS to change
-     the password to one only they know (they were granted rotation on their own account),
-     then deletes the file; so the password you set stops working once they install
-   - once installed, sharing works: `/mem:share <name>` on either side
+   **If it refuses with "house `<db>` already exists and holds N messages", STOP.** That
+   house is somebody's memory, and inviting into it would hand the invitee someone else's
+   sessions. Do not pass `--adopt` on your own initiative — report the row count and the
+   writer count to the user and let them choose: a different handle, a different `--db`,
+   or `--adopt` if sharing that house is genuinely what they want.
+
+4. **Put the file where the user can attach it.** The CLI writes `invite-<name>.env`
+   into the CURRENT directory, and the user has to send it by hand — so run the command
+   from their downloads directory (on macOS and most Linux desktops `~/Downloads`), or
+   move it there afterwards. Never leave it in a git repo: it is a password, and
+   `invite-*.env` is only gitignored in this repo, not in whatever checkout the user
+   happened to be standing in.
+
+   Confirm it is there and still mode `600`, and say the full path. **Never print the
+   file's contents** — the password inside would land in a transcript memhouse ships.
+
+5. **Say whether the house was fresh.** Run
+   `memhouse stats` or query `SELECT count() FROM <db>.messages` and tell the user
+   plainly: a brand-new house reads 0. This is a second line of defence behind step 3's
+   refusal, and it is how the user learns the invitee is starting clean.
+
+6. **Write the message the user will send.** They are about to hand over a file plus an
+   explanation, so compose it for them rather than making them write it. Put it in a
+   fenced block they can copy whole, and cover:
+   - what memhouse is, in a sentence or two — the invitee may never have heard of it
+   - that the attached `invite-<name>.env` IS a password: don't forward it, don't paste
+     it into chat
+   - `npm install -g memhouse` (Node 24+, no flags, nothing compiles), then
+     `memhouse install --env invite-<name>.env`
+   - that install OFFERS to change the password to one only they know, then deletes the
+     file — so they should say yes, because the inviter knows the current one
+   - `memhouse onboard` to start shipping, `memhouse status` to check it worked
+   - that their house is theirs alone; the inviter cannot read it unless they run
+     `/mem:share <inviter>`
+
+   If the invitee is REPLACING an existing setup (they were shipping under another
+   credential), add `memhouse ship --full` after the install — a plain incremental pass
+   skips sessions the new house has no record of, so their history would not follow them.
+
+   Then: once installed, sharing works both ways — `/mem:share <name>`.
 
 ## Never
 
 Never create a ClickHouse user by running raw SQL with an admin password you were given
 in chat. Never invent an admin credential. Never suggest granting beyond what `memhouse
 invite` does. If the binary is absent, stop and say so — do not improvise the SQL.
+
+Never print the invite file's contents, and never pass `--adopt` unless the user asked
+for it after being told what is already in that house.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memhouse",
-  "version": "0.12.6",
-  "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",
+  "version": "0.13.0",
+  "description": "memhouse \u2014 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": {
     "memhouse": "./bin/memhouse.js"