memhouse 0.18.9 → 0.18.11

package/examples/04-self-hosted-team/smoke.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Smoke test for the self-hosted team house: everything goes through the TLS proxy.
+#
+#   ./smoke.sh                  docker compose up -d with ./.env, then test it
+#   SKIP_UP=1 ./smoke.sh        test a stack that is already running (see below)
+#   KEEP=1 ./smoke.sh           keep the `smoke` member and its rooms afterwards
+#
+# With SKIP_UP=1 nothing is read from .env; give the target instead:
+#   MEMHOUSE_URL              https://<domain>[:port]
+#   MEMHOUSE_ADMIN_USER / MEMHOUSE_ADMIN_PASSWORD   (lend the password with with-secret)
+#   CA_FILE                   the CA that signed the proxy's certificate, if not a public one
+#
+# What it proves: the proxy answers over TLS; the passwordless `default` user is gone; an
+# admin can invite a member; the member installs, ships, and reads its rooms back; a
+# BACKUP to the backups disk restores with the same row count.
+set -euo pipefail
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+MH=${MEMHOUSE_BIN:-memhouse}
+mh() { $MH "$@"; }
+WORK=$(mktemp -d)
+unset MEMHOUSE_USER MEMHOUSE_PASSWORD MEMHOUSE_DB
+
+pass=0; fail=0
+ok()  { printf '  ok    %s\n' "$1"; pass=$((pass+1)); }
+bad() { printf '  FAIL  %s\n        %s\n' "$1" "${2:-}"; fail=$((fail+1)); }
+
+if [ "${SKIP_UP:-0}" != "1" ]; then
+  [ -f "$HERE/.env" ] || { echo "no .env — cp .env.example .env, fill it in, chmod 600"; exit 1; }
+  (cd "$HERE" && docker compose up -d --wait)
+  set -a; . "$HERE/.env"; set +a
+  port=${MEMHOUSE_HTTPS_PORT:-443}
+  MEMHOUSE_URL="https://$MEMHOUSE_DOMAIN$([ "$port" = 443 ] || echo ":$port")"
+  MEMHOUSE_ADMIN_USER=${MEMHOUSE_ADMIN_USER:-admin}
+  if [ "${MEMHOUSE_TLS:-internal}" = "internal" ]; then
+    (cd "$HERE" && docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt "$WORK/caddy-root.crt")
+    CA_FILE="$WORK/caddy-root.crt"
+  fi
+fi
+: "${MEMHOUSE_URL:?}" "${MEMHOUSE_ADMIN_USER:?}" "${MEMHOUSE_ADMIN_PASSWORD:?}"
+export MEMHOUSE_URL MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
+CURL=(curl -sS)
+if [ -n "${CA_FILE:-}" ]; then
+  CURL+=(--cacert "$CA_FILE")
+  export NODE_EXTRA_CA_CERTS="$CA_FILE"   # memhouse is Node: it trusts this CA too
+fi
+
+# Passwords go to curl on stdin (-K -), never on its command line.
+q_as() { printf 'user = "%s:%s"\n' "$1" "$2" | "${CURL[@]}" -K - --data-binary "$3" "$MEMHOUSE_URL/" 2>&1; }
+admin_q() { q_as "$MEMHOUSE_ADMIN_USER" "$MEMHOUSE_ADMIN_PASSWORD" "$1"; }
+member_q() { ( set -a; . "$WORK/home/env"; set +a; q_as "$MEMHOUSE_USER" "$MEMHOUSE_PASSWORD" "$1" ); }
+
+cleanup() {
+  if [ "${KEEP:-0}" != "1" ] && [ "${CREATED:-0}" = "1" ]; then
+    admin_q "DROP USER IF EXISTS smoke" >/dev/null || true
+    for t in $(admin_q "SELECT name FROM system.tables WHERE database = 'mem' AND startsWith(name, 'smoke_') FORMAT TSV"); do
+      admin_q "DROP TABLE IF EXISTS mem.$t SYNC" >/dev/null || true
+    done
+  fi
+  rm -rf "$WORK"
+}
+trap cleanup EXIT
+
+echo "smoke test against $MEMHOUSE_URL"
+
+r=$("${CURL[@]}" "$MEMHOUSE_URL/ping" 2>&1 || true)
+[ "$r" = "Ok." ] && ok "the proxy answers over TLS (certificate verified)" || bad "no TLS answer from the proxy" "$r"
+
+r=$(q_as default "" "SELECT 1" || true)
+case "$r" in *AUTHENTICATION_FAILED*|*"Authentication failed"*|*REQUIRED_PASSWORD*) ok "the passwordless default user is gone";; *) bad "the default user still answers" "$r";; esac
+
+r=$(admin_q "SELECT version()")
+case "$r" in [0-9]*) ok "admin reaches ClickHouse $r";; *) bad "admin login failed" "$r"; exit 1;; esac
+
+n=$(admin_q "SELECT count() FROM system.users WHERE name = 'smoke' FORMAT TSV")
+[ "$n" = "0" ] || { bad "a user named smoke already exists — refusing to touch it"; exit 1; }
+CREATED=1
+
+# A loopback URL is right only through a tunnel; invite refuses one unless told so.
+case "$MEMHOUSE_URL" in https://localhost*|https://127.0.0.1*) LOCAL=--allow-local;; *) LOCAL=;; esac
+export MEMHOUSE_HOME="$WORK/admin"; mkdir -p "$MEMHOUSE_HOME"
+out=$(cd "$WORK" && mh invite smoke --url "$MEMHOUSE_URL" --admin-user "$MEMHOUSE_ADMIN_USER" --out "$WORK/smoke.env" $LOCAL 2>&1 || true)
+case "$out" in *"invite written"*) ok "admin invited member 'smoke'";; *) bad "invite failed" "$(printf '%s' "$out" | tail -3)"; exit 1;; esac
+
+export MEMHOUSE_HOME="$WORK/home"; mkdir -p "$MEMHOUSE_HOME"
+node "$HERE/../fixtures/make-sessions.js" "$WORK/sessions" smoke alpha beta >/dev/null
+out=$(unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
+      mh install --env "$WORK/smoke.env" --editors claude --claude-roots "$WORK/sessions" --yes --no-ship 2>&1 || true)
+case "$out" in *"installed"*) ok "the member installed from the invite file, over https";; *) bad "install failed" "$(printf '%s' "$out" | grep '✗' | head -3)"; exit 1;; esac
+out=$(unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD; mh ship 2>&1 || true)
+case "$out" in *"shipped 2 sessions"*) ok "shipped: $(printf '%s' "$out" | tail -1 | sed 's/^\[memhouse\] //')";; *) bad "ship failed" "$out";; esac
+
+r=$(member_q "SELECT count() FROM mem.smoke_messages FINAL FORMAT TSV")
+[ "$r" = "6" ] && ok "the member reads its 6 messages back through the proxy" || bad "read-back count" "$r"
+r=$(member_q "CREATE TABLE mem.not_mine (x UInt8) ENGINE = MergeTree ORDER BY x" || true)
+case "$r" in *ACCESS_DENIED*|*"Not enough privileges"*) ok "the member cannot create tables outside mem.smoke_*";; *) bad "the member created a table outside its rooms" "$r";; esac
+
+ts=$(date -u +%Y-%m-%d-%H_%M_%S)
+r=$(admin_q "BACKUP TABLE mem.smoke_messages TO Disk('backups', 'mem-smoke-$ts.zip')")
+case "$r" in *BACKUP_CREATED*) ok "BACKUP to the backups disk";; *) bad "backup failed" "$r";; esac
+r=$(admin_q "RESTORE TABLE mem.smoke_messages AS mem.smoke_restore_check FROM Disk('backups', 'mem-smoke-$ts.zip')")
+case "$r" in *RESTORED*) ok "RESTORE from it";; *) bad "restore failed" "$r";; esac
+r=$(admin_q "SELECT count() FROM mem.smoke_restore_check FORMAT TSV")
+[ "$r" = "6" ] && ok "the restored copy holds the same 6 rows" || bad "restored count" "$r"
+
+r=$(admin_q "SELECT status FROM system.backups WHERE name LIKE '%''mem-2%' AND startsWith(toString(status), 'BACKUP') ORDER BY start_time DESC LIMIT 1 FORMAT TSV")
+case "$r" in BACKUP_CREATED) ok "the backup service has written a nightly backup since the server started";;
+  '') printf '  info  no nightly backup yet this server lifetime (BACKUP_ON_START=1 runs one at start)\n';;
+  *) bad "the last nightly backup did not complete" "$r";; esac
+
+echo
+echo "$pass passed, $fail failed"
+[ "$fail" = 0 ]

package/examples/README.md

@@ -0,0 +1,42 @@
+# memhouse examples
+
+Four working setups, smallest first. Each folder has a README and a script you can run as
+it is. They all ship **made-up sessions** (from [`fixtures/`](fixtures/)) rather than
+yours, and each installs into a memhouse home of its own, so an install you already have
+is never touched.
+
+| # | Example | Who it is for | Needs |
+|---|---|---|---|
+| 01 | [One machine](01-local-one-machine/) | one person, a house in a local container | Node 24, Docker or Podman |
+| 02 | [An existing ClickHouse](02-existing-clickhouse/) | you already run ClickHouse, or use ClickHouse Cloud | Node 24, an admin account on it |
+| 03 | [A team house](03-team-house/) | an admin, three members, a full share and a scoped one | Node 24, a throwaway ClickHouse and its admin |
+| 04 | [Self-hosted for a team](04-self-hosted-team/) | ClickHouse behind TLS, nightly backups, members on other machines | a Linux server with Docker, a DNS name |
+
+To do any of this for real, with your own sessions, skip the script and follow the
+README's "For real" section: it is the same commands without the fixture flags.
+
+## Running them
+
+```bash
+npm install -g memhouse          # or set MEMHOUSE_BIN to a checkout: "node /path/to/bin/memhouse.js"
+cd examples/01-local-one-machine
+./run.sh
+```
+
+Admin passwords are never typed on a command line. The scripts read them from
+`MEMHOUSE_ADMIN_PASSWORD`, which you lend to one command from wherever you keep secrets:
+
+```bash
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:clickhouse-admin -- ./run.sh
+```
+
+Any tool that sets an environment variable for one command does the same job: 1Password's
+`op run`, or a `read -rs MEMHOUSE_ADMIN_PASSWORD && export MEMHOUSE_ADMIN_PASSWORD` in the
+same shell, which keeps it off the screen and out of shell history.
+
+## How they were tested
+
+Last run on 2026-10-08, memhouse 0.18.9 (main `ccdcfb8`), against ClickHouse 26.7.1.1315,
+the version memhouse's own production house runs: 01 on a disposable Linux VM with Docker,
+02 and 03 against a disposable ClickHouse, 04 as the full compose stack. The output each
+README quotes is from that run.

package/examples/fixtures/README.md

@@ -0,0 +1,24 @@
+# fixtures — made-up sessions
+
+`make-sessions.js` writes a few Claude Code transcripts for one made-up person, laid out
+the way Claude Code lays out `~/.claude`, so an example can ship real rows without
+shipping your conversations.
+
+```bash
+node make-sessions.js <claude-root> <person> [project ...]   # default projects: alpha beta
+```
+
+Each project gets one session: a question, a tool call (`memhouse whoami`) and its result,
+and an answer. The `alpha` session is about an `ACCESS_DENIED` error and the `beta` one
+about rotating a password, so a search can tell them apart. memhouse records the project
+as the last segment of the session's folder (`/home/<person>/work/alpha`), which is what a
+scoped share like `--only project=alpha` matches.
+
+Point memhouse at the directory, and at nothing else, with:
+
+```bash
+MEMHOUSE_EDITORS=claude MEMHOUSE_CLAUDE_ROOTS=<claude-root> memhouse ship
+```
+
+or persist the same scope at install time with `--editors claude --claude-roots <claude-root>`.
+The script prints one line per session: `<project> <session-id>`.

package/examples/fixtures/make-sessions.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Write a few made-up Claude Code sessions for one person, so an example can ship real
+// transcripts without shipping YOURS.
+//
+//   node make-sessions.js <claude-root> <person> [project ...]
+//
+// <claude-root> is laid out the way Claude Code lays out ~/.claude: projects/<encoded
+// folder>/<session-id>.jsonl. Point memhouse at it with
+//
+//   MEMHOUSE_EDITORS=claude MEMHOUSE_CLAUDE_ROOTS=<claude-root> memhouse ship
+//
+// and nothing else on the machine is read. Each project gets one session: a question, a
+// tool call, an answer. The project memhouse records is the folder's last segment, so
+// `--only project=alpha` in a scoped share matches the session written for `alpha`.
+//
+// Prints one line per session: <project> <session-id>.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const [root, person, ...rest] = process.argv.slice(2);
+if (!root || !person || !/^[A-Za-z][A-Za-z0-9_]*$/.test(person)) {
+  console.error('usage: make-sessions.js <claude-root> <person> [project ...]');
+  process.exit(2);
+}
+const projects = rest.length ? rest : ['alpha', 'beta'];
+
+// What each made-up session is about — distinct words, so a search can tell them apart.
+const TOPICS = {
+  alpha: { ask: 'The deploy fails with ClickHouse error ACCESS_DENIED on INSERT. Why?',
+    answer: 'The member holds INSERT on its own rooms only. The deploy wrote to a table outside the mem.<member>_* pattern; write to the member rooms instead.' },
+  beta: { ask: 'How do I rotate the shipper password without losing data?',
+    answer: 'Run memhouse passwd. It rotates the credential and rewrites the env file; the rows in the house are not touched.' },
+};
+const topic = (p) => TOPICS[p] || { ask: `What is the state of project ${p}?`, answer: `Project ${p} is a made-up example.` };
+
+const now = Date.now();
+for (const [i, project] of projects.entries()) {
+  const folder = `/home/${person}/work/${project}`;
+  const dir = path.join(root, 'projects', folder.replace(/\//g, '-'));
+  fs.mkdirSync(dir, { recursive: true });
+  const sid = crypto.randomUUID();
+  // An hour apart per project, a few seconds apart per turn, all in the recent past.
+  const t = (s) => new Date(now - (projects.length - i) * 3600e3 + s * 1000).toISOString();
+  const { ask, answer } = topic(project);
+  const base = { sessionId: sid, cwd: folder, gitBranch: 'main', version: '2.1.0' };
+  const lines = [
+    { ...base, type: 'user', uuid: 'u1', timestamp: t(0), message: { role: 'user', content: ask } },
+    { ...base, type: 'assistant', uuid: 'a1', parentUuid: 'u1', timestamp: t(4),
+      message: { role: 'assistant', model: 'claude-example', content: [
+        { type: 'text', text: 'Let me look at the grants first.' },
+        { type: 'tool_use', id: `toolu_${i}`, name: 'Bash', input: { command: 'memhouse whoami' } },
+      ], usage: { input_tokens: 120, output_tokens: 30 } } },
+    { ...base, type: 'user', uuid: 'u2', parentUuid: 'a1', timestamp: t(6),
+      message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: `toolu_${i}`, content: `member ${person}` }] } },
+    { ...base, type: 'assistant', uuid: 'a2', parentUuid: 'u2', timestamp: t(10),
+      message: { role: 'assistant', model: 'claude-example', content: [{ type: 'text', text: answer }],
+        usage: { input_tokens: 180, output_tokens: 60 } } },
+  ];
+  fs.writeFileSync(path.join(dir, `${sid}.jsonl`), lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  console.log(`${project} ${sid}`);
+}

package/memhouse/DESIGN.md

@@ -134,8 +134,15 @@ Config file: `~/.memhouse/config.json` (`hiddenProjects`, future prefs).
 - Per-message `ts`: interpolated across the session's `[createdAt, lastUpdatedAt]`
   (adapters don't expose per-message timestamps; monotonic by `seq`; documented
   approximation, refine per-adapter later).
-- `seq` is the message index within the session (0-based). `tool_calls.idx` is the
-  call index within the session. `is_subagent` = message content begins with
+- `seq` is the message's place in the session. The session's own turns are dense from 0;
+  a folded subagent's turns are numbered from their own block,
+  `1,000,000,000 + slot × 100,000 + turn`, where `slot` is the subagent's rank by start
+  time. `tool_calls.idx` is laid out the same way (the session's own calls dense from 0,
+  a subagent's counted within its block). A row's key therefore never depends on how long
+  the parent or any other subagent is, which is what lets a session with subagents ship
+  tail-only; positional numbering moved every subagent row whenever the parent grew. A
+  parse that does not fit the blocks falls back to positional numbering. Readers order by
+  `seq` and count with `count()`; nothing may treat `seq` as dense. `is_subagent` = message content begins with
   `[subagent]` (the fold marker from the Claude adapter).
 - Incremental shipping: read existing `(session_id, last_updated_at, message_count)`
   (FINAL) and skip chats that haven't grown/changed; a full re-ship must remain

package/memhouse/admin-secret.js

@@ -0,0 +1,81 @@
+// Where an ADMIN password comes from — and why the command line is the last place.
+//
+// A password passed as `--admin-password <p>` is in the process list (`ps`) for as long
+// as the command runs and in shell history unless the caller remembered a leading space.
+// The only scriptable admin path used to demand exactly that: `--admin-user` as a flag
+// turned off every other source, so an agent or CI job that held the password in an
+// environment variable (or in a secret store, via `with-secret`) still had to put it on
+// argv. Found by O's sandbox rehearsal (finding 6).
+//
+// Order, first answer wins:
+//   1. --admin-password-file <path>  a file holding the password (trailing newline dropped)
+//      --admin-password-file -       read it from stdin   (printf '%s' "$P" | memhouse …)
+//   2. --admin-password <p>          still accepted, with a warning — never required
+//   3. MEMHOUSE_ADMIN_PASSWORD       the environment; `with-secret` lends it to one command
+//   4. the stored credential         only when it belongs to the SAME admin user
+// Nothing here prompts: the caller decides whether a TTY prompt is the next step.
+//
+// Pure apart from the one file/stdin read, which is injectable, so it is unit tested.
+
+const fs = require('fs');
+
+// Strip exactly one trailing newline: `echo secret > f` writes one, and a password that
+// legitimately ends in whitespace must survive.
+function stripOneNewline(s) {
+  return String(s).replace(/\r?\n$/, '');
+}
+
+function readSecretFile(spec, { readFile = fs.readFileSync, stdinIsTTY = process.stdin.isTTY } = {}) {
+  if (spec === '-') {
+    if (stdinIsTTY) throw new Error('--admin-password-file - reads the password from stdin, but stdin is a terminal — pipe it in, or leave the flag off to be prompted');
+    return stripOneNewline(readFile(0, 'utf-8'));
+  }
+  let text;
+  try { text = readFile(spec, 'utf-8'); } catch (e) { throw new Error(`--admin-password-file ${spec}: ${e.code === 'ENOENT' ? 'no such file' : e.message.split('\n')[0]}`); }
+  return stripOneNewline(text);
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.adminUser      the admin user this password is for
+ * @param {object} o.flags          parsed CLI flags
+ * @param {object} [o.env]          process.env (injectable)
+ * @param {object} [o.stored]       { user, password } this install keeps, if any
+ * @param {object} [o.io]           { readFile, stdinIsTTY } for tests
+ * @returns {{ password: string|undefined, source: 'file'|'stdin'|'flag'|'env'|'stored'|null }}
+ */
+function resolveAdminPassword({ adminUser, flags = {}, env = process.env, stored = null, io = {} }) {
+  const fileFlag = flags['admin-password-file'];
+  const argvFlag = flags['admin-password'];
+  if (fileFlag !== undefined && argvFlag !== undefined) {
+    throw new Error('give the admin password one way: --admin-password-file or --admin-password, not both');
+  }
+  if (fileFlag !== undefined) {
+    if (fileFlag === true || fileFlag === '') throw new Error('--admin-password-file needs a path, or - for stdin');
+    const password = readSecretFile(String(fileFlag), io);
+    return { password, source: fileFlag === '-' ? 'stdin' : 'file' };
+  }
+  if (argvFlag !== undefined && argvFlag !== true) return { password: String(argvFlag), source: 'flag' };
+  if (env && typeof env.MEMHOUSE_ADMIN_PASSWORD === 'string' && env.MEMHOUSE_ADMIN_PASSWORD !== '') {
+    return { password: env.MEMHOUSE_ADMIN_PASSWORD, source: 'env' };
+  }
+  if (stored && stored.user && stored.password && stored.user === adminUser) {
+    return { password: stored.password, source: 'stored' };
+  }
+  return { password: undefined, source: null };
+}
+
+// One line for a caller that took the password off argv anyway.
+const ARGV_WARNING = '--admin-password on the command line is visible in `ps` and shell history, and is deprecated: it is removed in 0.19.0. Use MEMHOUSE_ADMIN_PASSWORD (with-secret) or --admin-password-file -';
+
+// What to tell a caller with no TTY and no password from any source.
+function missingAdminPasswordHelp(adminUser) {
+  return [
+    `no password for admin '${adminUser}', and no TTY to prompt on. Give it without putting it on the command line:`,
+    `     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse …`,
+    `     printf '%s' "$PASSWORD" | memhouse … --admin-password-file -`,
+    `     memhouse … --admin-password-file <file, mode 600>`,
+  ];
+}
+
+module.exports = { resolveAdminPassword, readSecretFile, stripOneNewline, ARGV_WARNING, missingAdminPasswordHelp };

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: recall past sessions and answer from them, run analytics, check the house, bring people in, and administer the server. Skills install as /mem:recall, /mem:sql, /mem:house, /mem:access, and /mem:admin.",
-  "version": "0.18.9",
+  "version": "0.18.11",
   "author": {
     "name": "Ramazan Polat"
   },

package/memhouse/delivery/plugin/reference/HOUSE.md

@@ -101,23 +101,35 @@ session finds nothing — look inside the parent:
 ```sql
 -- the subagents a session spawned
 SELECT toString(extra.agent.id) AS agent, any(toString(extra.agent.description)) AS asked_to, count() AS turns
-FROM messages WHERE session_id = '<sid>' AND is_subagent GROUP BY agent   -- toString: a JSON path cannot be a GROUP BY key
+FROM messages FINAL
+WHERE session_id = '<sid>' AND user_id = '<uid>' AND is_subagent
+  AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+       WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+GROUP BY agent   -- toString: a JSON path cannot be a GROUP BY key
 -- one subagent's transcript, in order
-SELECT seq, role, substring(text, 1, 2000) FROM messages
-WHERE session_id = '<sid>' AND extra.agent.id = '<agent>' ORDER BY seq
+SELECT seq, role, substring(text, 1, 2000) AS text FROM messages FINAL
+WHERE session_id = '<sid>' AND user_id = '<uid>' AND toString(extra.agent.id) = '<agent>'
+  AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+       WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+ORDER BY seq
 ```
 
+Both carry the current-epoch filter (trap 1 below). A session whose subagents were
+re-parsed holds every parse, so an unfiltered count doubles each subagent's turns, and an
+unfiltered transcript repeats them. `<uid>` is the session's `user_id`, from whatever
+query found it (trap 2).
+
 **`messages`** — one row per turn.
 
 | column | meaning |
 |---|---|
 | `session_id` | `<source>:<adapter-local id>`, e.g. `claude-code:6b1f…` |
-| `seq` | position in the session, from 0 |
+| `seq` | order within the session. The session's own turns are `0, 1, 2, …`; a subagent's turns sit in their own block, `1,000,000,000 + slot × 100,000 + turn` (slot = the subagent's rank by start time), so `seq` is **sparse** — count rows with `count()`, never `max(seq) + 1` |
 | `source` | editor: `claude-code`, `codex`, `cursor`, … |
-| `host` | the machine, `<hostname>-<8 hex>` — random per install, not derived |
+| `host` | the machine, `<hostname>-<8 hex>` — the 8 hex are derived from the OS machine id (random only where none can be read), so a reinstall keeps it and same-named machines differ |
 | `ts` | when the turn happened (`DateTime64(3,'UTC')`) |
 | `role` | `user`, `assistant`, `system` |
-| `is_subagent` | 1 for a turn that a Claude Code **subagent** (a fork) produced; folded into the parent session after the parent's own turns. Subagents are never separate sessions. |
+| `is_subagent` | 1 for a turn that a Claude Code **subagent** (a fork) produced; folded into the parent session after the parent's own turns, each subagent's turns contiguous and the subagents in the order they started. Subagents are never separate sessions. |
 | `extra` | JSON. For a subagent turn: `extra.agent.id`, `extra.agent.description` (what the parent asked it to do, else the fork's own first prompt), `extra.agent.type` (`general-purpose`, `workflow-subagent`, …), `extra.agent.turn` (position within that subagent), and `extra.agent.workflow` (`wf_…`) when a Workflow run spawned it. Empty `{}` otherwise, and on rows shipped before 0.18.3. |
 | `model`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens` | usage; **empty for several adapters** — see below |
 | `text` | the turn, **truncated at 50,000 chars** |

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

@@ -13,7 +13,7 @@ Two things that look alike and are not:
 - **Invite** mints a ClickHouse *user* and their own *house*. Needs an administrator.
 - **Share** grants an existing user `SELECT` on *your* house. You can do this yourself.
 
-**Read `../reference/HOUSE.md` first** for the connection block. One rule dominates
+**Read `../../reference/HOUSE.md` first** for the connection block. One rule dominates
 everything here: **a password must never enter this conversation.** memhouse ships this
 transcript into the house, and the archive is insert-only — a credential pasted here
 cannot be withdrawn.

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

@@ -12,7 +12,7 @@ A member owns a house, or rooms in one. An **administrator** owns the ClickHouse
 account, every grant. This skill is the second one, and it is the only skill allowed to
 act outside the caller's own house.
 
-**Read `../reference/HOUSE.md` first** — connection, schema, and the traps every query
+**Read `../../reference/HOUSE.md` first** — connection, schema, and the traps every query
 here inherits.
 
 **An admin password must never enter this conversation.** memhouse ships this transcript

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

@@ -11,7 +11,7 @@ allowed-tools: Bash
 **Invoking this IS the request. Run the report and present it; there is nothing to
 clarify.** Read-only throughout.
 
-**Read `../reference/HOUSE.md` first** — connection, schema, and the epoch filter every
+**Read `../../reference/HOUSE.md` first** — connection, schema, and the epoch filter every
 count below depends on.
 
 ## Nothing configured yet? Answer that instead

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

@@ -16,7 +16,7 @@ answer still exists.
 path — this skill retrieves rows and YOU read them. Never present a guess as a retrieval:
 if the house has nothing, say so.
 
-**Read `../reference/HOUSE.md` first** — connection, schema, and the three traps
+**Read `../../reference/HOUSE.md` first** — connection, schema, and the three traps
 (epoch filtering, `(session_id, user_id)` joins, escaping). Every query below assumes it.
 
 ## Which shape is being asked for
@@ -43,7 +43,8 @@ found 8 messages where `%clickhouse%` AND `%ttl%` found 1,461.
 ```sql
 SELECT session_id, user_id, any(folder) AS folder,
        formatDateTime(max(ts), '%Y-%m-%d') AS day, count() AS hits,
-       substring(anyIf(text, positionCaseInsensitive(text, 'NEEDLE') > 0), 1, 300) AS sample
+       min(seq) AS hit_seq,
+       substring(argMin(text, seq), 1, 300) AS sample
 FROM messages
 WHERE text_ngram LIKE '%needle%'
   AND (origin != 'ship'
@@ -55,8 +56,8 @@ ORDER BY hits DESC, max(ts) DESC
 LIMIT 8
 ```
 
-`anyIf(...)` so the sample is a line that actually matched — `any(text)` returns an
-arbitrary message from the session and misled two readers in three. **Order by `hits`,
+Every row counted here matched, so `sample` is a line that actually matched: the
+session's first hit, at `hit_seq`. Step 2 reads around that position. **Order by `hits`,
 not just recency**: a session mentioning the term 197 times outranks yesterday's passing
 reference.
 
@@ -64,15 +65,27 @@ reference.
 the match so you see the resolution, not the complaint:
 
 ```sql
-SELECT seq, role, substring(text, 1, 2000) AS text
-FROM messages
-WHERE session_id = '<sid>' AND user_id = '<uid>'
-  AND seq BETWEEN <hit_seq - 3> AND <hit_seq + 12>
+SELECT seq, role, is_subagent, substring(text, 1, 2000) AS text FROM (
+    (SELECT seq, role, is_subagent, text FROM messages FINAL
+     WHERE session_id = '<sid>' AND user_id = '<uid>' AND seq < <hit_seq>
+       AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+            WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+     ORDER BY seq DESC LIMIT 3)
+    UNION ALL
+    (SELECT seq, role, is_subagent, text FROM messages FINAL
+     WHERE session_id = '<sid>' AND user_id = '<uid>' AND seq >= <hit_seq>
+       AND (origin != 'ship' OR epoch = (SELECT max(epoch) FROM messages
+            WHERE session_id = '<sid>' AND user_id = '<uid>' AND origin = 'ship'))
+     ORDER BY seq LIMIT 13))
 ORDER BY seq
 ```
 
-Apply the epoch filter here too — an unfiltered read of a compacted session interleaves
-two parses of the same conversation.
+`<sid>`, `<uid>` and `<hit_seq>` come from step 1's row. The window is counted in rows,
+not in `seq` values: three turns before the hit and twelve after. `seq` has gaps. A
+subagent's turns are numbered in a block of their own, far above the parent's, so
+`seq BETWEEN hit_seq - 3 AND hit_seq + 12` could return the hit alone. The epoch filter
+keeps one parse: an unfiltered read of a compacted session interleaves two versions of
+the same conversation. `FINAL` collapses row versions the server has not merged yet.
 
 **3. Answer, then cite.** Lead with the answer. Under it list the sessions it came from —
 `session_id`, date, project — so the user can reopen one (`memhouse resume <session_id>`
@@ -95,13 +108,20 @@ one representative line each. Offer to read the strongest. Do not dump ten rows
 prefer it over hand-joining. For a plain list:
 
 ```sql
-SELECT session_id, name, source, host, project,
-       formatDateTime(started_at, '%Y-%m-%d %H:%i') AS started, message_count
-FROM sessions
-ORDER BY started_at DESC
+SELECT session_id, user_id, name, source, host, project,
+       formatDateTime(created_at, '%Y-%m-%d %H:%i') AS started,
+       formatDateTime(coalesce(last_updated_at, created_at), '%Y-%m-%d %H:%i') AS last_active,
+       message_count
+FROM sessions FINAL
+ORDER BY coalesce(last_updated_at, created_at) DESC
 LIMIT 20
 ```
 
+`sessions` keeps one row per session and the newest write wins, so read it `FINAL`.
+"Recent" means recently active (`last_updated_at`): a session started last month and
+worked on today is recent. The room has no `started_at`; `created_at` is when the
+session began.
+
 Narrow with `WHERE project = '…'`, `source = 'cursor'`, `host = '…'`, or a date range as
 asked. In a shared house every member's sessions are here — add `AND user_id = '<name>'`
 only when the user asks for one person's.

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

@@ -11,7 +11,7 @@ allowed-tools: Bash
 For **numbers**. When the answer is a passage from a past conversation, that is
 `/mem:recall` — this skill counts, groups and ranks.
 
-**Read `../reference/HOUSE.md` first.** Schema, connection, and the three traps. The epoch
+**Read `../../reference/HOUSE.md` first.** Schema, connection, and the three traps. The epoch
 filter in particular is not optional here: this is the skill most likely to produce a
 figure someone acts on, and omitting it over-counted a real house by **34%**.
 

package/memhouse/deploy.js

@@ -159,7 +159,9 @@ function up({ password, port = 8123, tag = DEFAULT_TAG, user = 'memhouse_root' }
     '--label', `${OWNER_LABEL}=1`,
     '--restart', 'unless-stopped',
     '-e', `CLICKHOUSE_USER=${user}`,
-    '-e', `CLICKHOUSE_PASSWORD=${password}`,
+    // By NAME only: the value goes in the child's environment below, never in argv, where
+    // `ps` would show it for as long as `docker run` lives.
+    '-e', 'CLICKHOUSE_PASSWORD',
     // The house itself is created by `memhouse install`, not here: pre-creating it
     // would skip the step an install is supposed to prove.
     '-e', 'CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1',
@@ -168,7 +170,7 @@ function up({ password, port = 8123, tag = DEFAULT_TAG, user = 'memhouse_root' }
     '--ulimit', 'nofile=262144:262144',
     image,
   ];
-  const r = spawnSync(eng, args, { encoding: 'utf-8' });
+  const r = spawnSync(eng, args, { encoding: 'utf-8', env: { ...process.env, CLICKHOUSE_PASSWORD: password } });
   if (r.status !== 0) {
     // The volume exists but the image never touched it — an unpullable tag, a port bind
     // that failed. Leaving it labelled would make the NEXT deploy read an empty volume as

package/memhouse/flags.js

@@ -16,11 +16,11 @@ const COMMAND_FLAGS = {
   null: [], help: [], version: [],
   whoami: ['admin'],
   share: ['only', 'revoke', 'list'],
-  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], instance: [], members: ['db','admin-user','admin-password'], convert: ['url','db','admin-user','admin-password','member','print-sql','dry-run','guides','out'],
+  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], instance: [], members: ['db','admin-user','admin-password','admin-password-file'], convert: ['url','db','admin-user','admin-password','admin-password-file','member','print-sql','dry-run','guides','out'],
   status: ['all'], start: [],
   onboard: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'target', 'house-port', 'tag', 'local'],
   install: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'env', 'print-sql', 'member',
-    'member-password', 'admin-user', 'admin-password', 'ensure-schema', 'rotate-password', 'force',
+    'member-password', 'admin-user', 'admin-password', 'admin-password-file', 'keep-admin', 'ensure-schema', 'rotate-password', 'force',
     'editors', 'claude-roots', 'channel'],
   setup: ['url', 'user', 'password', 'db', 'port', 'admin-user', 'admin-password', 'editors', 'claude-roots', 'channel'],
   ship: ['full', 'loop', 'ensure-schema'],
@@ -28,9 +28,9 @@ const COMMAND_FLAGS = {
   resume: [],
   update: ['check', 'migrate', 'no-install', 'channel'],
   reset: ['all-origins'],
-  invite: ['url', 'db', 'out', 'admin-user', 'admin-password', 'adopt', 'print-sql',
+  invite: ['url', 'db', 'out', 'admin-user', 'admin-password', 'admin-password-file', 'adopt', 'print-sql',
     'allow-local', 'member-password'],
-  passwd: ['password', 'admin-user', 'admin-password', 'print-sql', 'member'],
+  passwd: ['password', 'admin-user', 'admin-password', 'admin-password-file', 'print-sql', 'member'],
   nightly: ['out'],
   migrate: ['dry-run'], 'migrate-rooms': ['dry-run'],
   relocate: ['to', 'to-user', 'to-password', 'to-db', 'from-native-host', 'from-native-port',
@@ -75,4 +75,31 @@ function allowedFlags(cmd) {
   return new Set([...GLOBAL_FLAGS, ...known]);
 }
 
-module.exports = { GLOBAL_FLAGS, COMMAND_FLAGS, unknownFlags, allowedFlags, suggestFlag, editDistance };
+// Options that never take a value. The parser used to read `--x y` as x = "y" for every
+// option, so a switch swallowed the word after it: `update --no-install yes` set
+// no-install to "yes" (not true) and ran the npm install it was asked to skip, and
+// `share --revoke bob` revoked nobody. A switch is true when present, and the next word
+// stays a positional.
+const BOOLEAN_FLAGS = new Set([
+  'json', 'yes', 'help', 'version', 'full', 'check', 'migrate', 'no-install', 'all-origins',
+  'dry-run', 'print-sql', 'no-ship', 'keep-admin', 'ensure-schema', 'rotate-password', 'force',
+  'adopt', 'allow-local', 'local', 'down', 'credentials', 'full-removal', 'insecure-native',
+  'keep-shipper', 'guides', 'revoke', 'list', 'admin', 'install', 'all',
+]);
+
+/** argv (after the command) -> { flags, positional }. */
+function parseArgv(rest) {
+  const flags = {}; const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = rest[i + 1];
+      if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith('--')) { flags[key] = next; i++; }
+      else flags[key] = true;
+    } else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+module.exports = { GLOBAL_FLAGS, COMMAND_FLAGS, BOOLEAN_FLAGS, parseArgv, unknownFlags, allowedFlags, suggestFlag, editDistance };