memhouse 0.9.0 → 0.11.1

package/memhouse/DESIGN.md

@@ -64,9 +64,10 @@ them free and further along; **bet 3 is the one nobody else attempts.**
    Physical typed columns (what memory-house derives in views) + `tool_calls`
    (memory-house has no tool table) + one `extra JSON` escape hatch per room so
    unnormalized adapter fields are never lost. `ReplacingMergeTree(ingested_at)`;
-   `messages` keyed `(session_id, user_id, origin, seq)` so a re-ship of a
-   grown/changed session replaces stale rows (latest-wins) and two housemates' rows
-   never collapse into one. FTS text indexes built in (CH ≥ 26.2).
+   `messages` keyed `(session_id, user_id, origin, epoch, seq)` so a re-ship of a
+   grown session replaces stale rows (latest-wins), two housemates' rows never
+   collapse into one, and a re-parse that SHRANK or was rewritten lands under a new
+   epoch instead of over what it replaces. FTS text indexes built in (CH ≥ 26.2).
 3. **Kernel-installable agency.** Joining any ClickHouse — a kernel's included — is a
    database plus a credential: `CREATE USER`, `GRANT ALL ON <house>.* `, done. The
    shipper is the resident that lands with it and creates its own rooms. Identity is
@@ -116,15 +117,39 @@ Config file: `~/.memhouse/config.json` (`hiddenProjects`, future prefs).
 - 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
   safe (ReplacingMergeTree collapses).
-- Re-shipping a known session **deletes its message/tool rows first**: `ReplacingMergeTree`
-  collapses same-key rows but cannot remove a row the new parse no longer produces, so a
-  shrunken re-parse would leave a stale `seq` tail forever.
-- **A mutation predicate must bind the user, never call `currentUser()`.** A mutation does
-  not evaluate it in the caller's context: measured on ClickHouse 25.11 and chdb, the same
-  `DELETE` matched 0 rows with `user_id = currentUser()` and 2000 with the value bound —
-  silently, both times. Read the identity once (`SELECT currentUser()`) and pass it as a
-  query parameter. This applies to `DELETE`/`ALTER … UPDATE`, not to `SELECT`, where
-  `currentUser()` behaves as expected.
+- **The shipper is insert-only, and nothing may reintroduce a destructive verb.**
+  `ReplacingMergeTree` collapses same-key rows but cannot remove a row the new parse no
+  longer produces, so a shrunken re-parse leaves a stale `seq` tail. The shipper used to
+  clear the session's rows first; that destroyed content held nowhere else, because
+  Claude Code compacts transcripts and deletes them after `cleanupPeriodDays` (30 by
+  default), and a shorter re-parse cannot be told apart from a fixed adapter bug. Instead
+  `decideEpoch` bumps the session's `epoch` when the new parse is shorter than the stored
+  one, or diverges from it at an overlapping `seq` (compared on the stored `line_hash`),
+  and writes underneath the old parse rather than over it.
+- **memhouse is an accumulator, not a mirror.** Absence of a session on disk is never a
+  signal: retention cleanup, a manual delete, a second laptop, an unmounted folder, a
+  locked SQLite file and a thrown adapter all produce the identical observation. A
+  session that disappears is never cleared and never re-inserted. **No `sync` and no
+  `prune` feature may be built here** — either would destroy the archive by design.
+- Reads see one parse per session. `roomNames()` resolves `messages`/`tool_calls` to a
+  current-epoch subquery and the bare tables only as `*_raw`, so retention cannot silently
+  inflate a rollup, and a read path written by someone who has never heard of epochs is
+  still correct. Measured cost of the filter: **+10 ms** across the dashboard's queries on
+  a real 66k-message house (all of them under 200 ms), and **+13–37 ms** on a synthetic
+  1M-message / 20k-session one. The single shape that grows is a one-session read
+  (5 ms → 18 ms at 1M rows): the `IN` aggregates the whole room regardless of the outer
+  session filter. If that ever matters, the answer is a small materialized current-epoch
+  table maintained by the shipper — never a filter each caller has to remember.
+- **A mutation predicate must bind the user, never call `currentUser()`.** No mutation
+  survives in the shipper, but the finding outlives it — `migrate-rooms` and `reset` still
+  run statements where it applies. A mutation does not evaluate `currentUser()` in the
+  caller's context: measured on ClickHouse 25.11 and chdb, the same `DELETE` matched 0
+  rows with `user_id = currentUser()` and 2000 with the value bound — silently, both
+  times. Read the identity once (`SELECT currentUser()`) and pass it as a query parameter.
+  The same trap bites the other way in a rebuild: `user_id` is `MATERIALIZED
+  currentUser()`, so an `INSERT SELECT` that does not carry it explicitly (under
+  `insert_allow_materialized_columns=1`) restamps every copied row with whoever ran the
+  migration.
 - Costs are computed in the server from `pricing.js` (repo root) over per-model
   token sums; `<synthetic>` and empty models excluded from model lists.
 

package/memhouse/delivery/AGENT-INSTALL-PROMPT.md

@@ -42,8 +42,14 @@ already exist.
   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.
+- The house's rooms are three PLAIN, SHARED tables — `sessions`, `messages`,
+  `tool_calls` — in the connection's database. No suffixes, no per-member tables.
+  Direct reads of `messages`/`tool_calls` must filter to the current parse (the shipper
+  retains superseded parses under an `epoch` column); the installed skills carry the
+  filter, so prefer them for queries.
+- If `ship` refuses with "wrong sorting key … memhouse migrate", the house was built by
+  an older memhouse. Run `memhouse migrate` — it copies, swaps atomically, deletes
+  nothing, and shipping resumes on its own. Do NOT try to rebuild tables by hand.
 
 ## When you are done
 
@@ -52,6 +58,8 @@ 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 `memhouse plugins install claude` gives their agents /mem:ask, /mem:search,
+  /mem:sessions, /mem:share, /mem:sql, /mem:status, /mem:users — offer to run it
 - 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

package/memhouse/delivery/AGENT-INSTALL.md

@@ -45,28 +45,31 @@ From a checkout instead (contributors): `npm install --no-audit --no-fund` in th
 repo root — nothing compiles — then substitute `node bin/memhouse.js` for `memhouse`
 below.
 
-## 2. Configure the connection
+## 2 + 3. Configure, create the schema, first ship — one command
 
-Write `~/.memhouse/env` (or run `memhouse install --yes --url … --user … --password
-… --db …`, which writes it for you):
+Do NOT hand-write `~/.memhouse/env`. `install` validates the connection, builds the
+rooms, ships, and writes the config LAST — a hand-written file is read as truth by
+every later command even when it is wrong, and an example URL pasted verbatim points
+at somebody's real house.
+
+With a credential the user already has on the house:
 
 ```bash
-mkdir -p ~/.memhouse
-cat > ~/.memhouse/env <<'EOF'
-MEMHOUSE_URL=http://localhost:8123
-MEMHOUSE_USER=memhouse_root
-MEMHOUSE_PASSWORD=<credential>
-MEMHOUSE_DB=mem
-EOF
-chmod 600 ~/.memhouse/env
+memhouse install --url <house-url> --user <member> --password '<credential>' --db <house>
 ```
 
-## 3. Create the schema and run the first ship
+Or, holding an admin credential, mint the member and the house in one go:
 
 ```bash
-memhouse install --yes     # applies the schema, then runs the first full ship
+memhouse install --url <house-url> \
+  --admin-user <admin> --admin-password '<admin-credential>' \
+  --db <house> --member <member> --member-password '<credential>'
 ```
 
+The admin credential is used once and never stored. Ask the user for values; never
+invent them and never default to localhost:8123 — on many machines that is a real house
+belonging to someone else.
+
 Expected output shape: `[memhouse] shipped N sessions (0 skipped) → M msg rows, T
 tool rows in Xs` with N in the hundreds on a machine with real agent usage.
 
@@ -84,9 +87,11 @@ no longer exists, so anything named here is a single editor's own store (locked
 running editor, corrupt, or on a schema this parser does not know).
 
 `stats` should show one row per source (claude-code, codex, gemini-cli, …) with
-non-zero sessions/messages. Or verify by SQL — rooms are named for your ClickHouse
-user, and the session rollup is a saved query rather than an object, so
-`memhouse sessions-query` prints it:
+non-zero sessions/messages. Or verify by SQL — the rooms are plain shared tables
+(`sessions`, `messages`, `tool_calls`) and the session rollup is a saved query rather
+than an object, so `memhouse sessions-query` prints it (it also applies the
+current-parse filter that any hand-written read of `messages` needs — the shipper
+retains superseded parses under an `epoch`):
 
 ```bash
 curl -s -u "$MEMHOUSE_USER:$MEMHOUSE_PASSWORD" "$MEMHOUSE_URL/?database=$MEMHOUSE_DB" \
@@ -109,9 +114,26 @@ re-ship loop, so this replaces any separate cron. `memhouse stop` ends both.
 memhouse plugins install claude
 ```
 
-Installs the memhouse plugin into `<claude-config>/skills/memhouse`, which loads next
-session as `memhouse@skills-dir` and exposes `/memhouse:search`, `/memhouse:sessions`
-and `/memhouse:sql`. They read the connection from `$MEMHOUSE_HOME/env` (default
+Installs the memhouse plugin into `<claude-config>/skills/mem`, which loads next
+session as `mem@skills-dir` and exposes `/mem:ask`, `/mem:search`, `/mem:sessions`,
+`/mem:share`, `/mem:sql`, `/mem:status` and `/mem:users`. They read the connection from
+`$MEMHOUSE_HOME/env` (default
 `~/.memhouse/env`), with exported `MEMHOUSE_*` vars taking precedence, and refuse to run
 rather than guessing a URL when neither is set. `memhouse plugins list` shows what is
 installed, `memhouse plugins remove claude` undoes it.
+
+## 7. Upgrading a machine that already ran memhouse < 0.10
+
+The 0.10 schema changed the transcript tables' sorting keys, so the first `ship` against
+an old house refuses and names the fix. Run it:
+
+```bash
+memhouse migrate      # copies each room, swaps atomically, keeps <room>_pre_epoch
+```
+
+Nothing is deleted; a service-managed shipper resumes on its next pass by itself.
+`memhouse update` performs this for the user interactively (`--migrate` runs it
+unasked); as an agent, prefer `memhouse update --no-install --migrate` after an
+`npm install -g` you already performed. If OTHER machines still ship into the same
+house with an older memhouse, tell the user to upgrade them promptly — the migration
+output explains why and prints the admin-side alternative.

package/memhouse/delivery/PROMPT.md

@@ -9,9 +9,10 @@ long-term conversation memory.
 
 You have persistent memory of past agent sessions — every conversation this user
 has had with coding agents (Claude Code, Codex, Gemini CLI, Cursor, and other
-editors), across all of YOUR machines, stored in your own rooms in a ClickHouse
-database called **{{DB}}**. Other members of the same house have their own rooms and
-you hold no grant on them.
+editors), across all of THEIR machines, stored in a ClickHouse database called
+**{{DB}}** (their "house"). The house outlives the transcripts on disk: editors
+compact and delete local session files after weeks, and the house is then the only
+copy.
 Connection: read `{{ENV_FILE}}` (`MEMHOUSE_URL/USER/PASSWORD/DB`); query over
 HTTP with `curl -u "$MEMHOUSE_USER:$MEMHOUSE_PASSWORD" "$MEMHOUSE_URL/?database=$MEMHOUSE_DB"`
 and always add `SETTINGS final=1, join_use_nulls=1` to reads — the second matters
@@ -22,9 +23,12 @@ work that is not in your current context ("that session where…", "how did I so
 X before", "did we ever…", "what was I working on last week"), search memhouse
 FIRST. Only say you don't know after a search comes back empty.
 
-**How to query.** Prefer the installed skills when present: `/memhouse:search`
-(full-text over messages), `/memhouse:sessions` (list/filter sessions),
-`/memhouse:sql` (free-form read-only SQL). Without skills, query directly.
+**How to query.** Prefer the installed skills when present: `/mem:ask` (answer a
+question from memory, with citations), `/mem:search` (full-text over messages),
+`/mem:sessions` (list/filter sessions), `/mem:sql` (free-form read-only SQL),
+`/mem:status` (what the system holds and its health), `/mem:share` and `/mem:users`
+(read-only sharing between users), `/mem:invite` (mint a new member — inviting comes
+before sharing), `/mem:hello` (introduce the system). Without skills, query directly.
 
 **Table names.** The house's rooms are three plain, shared tables — `messages`,
 `sessions`, `tool_calls` — in the connection's database. Everyone in the house writes
@@ -33,21 +37,41 @@ which machine. Query the whole house by default; add `WHERE user_id = '<name>'`
 person. **There is no `sessions_v` object** — the rollup is a saved query, and
 `memhouse sessions-query` prints it ready to drop into a `FROM (...) AS c`.
 
+**One session can be stored more than once.** The shipper never deletes: when an editor
+compacts or shortens a session, the new parse is written under a higher `epoch` and the
+old one is retained. Every direct read of `messages`/`tool_calls` must filter to the
+current parse, or counts double and a replay interleaves two versions of the session:
+
+```sql
+-- call this CUR below
+WHERE origin != 'ship'
+   OR (session_id, user_id, epoch) IN (
+        SELECT session_id, user_id, max(epoch) FROM messages
+        WHERE origin = 'ship' GROUP BY session_id, user_id)
+```
+
+Drop CUR deliberately only when asked what a session said BEFORE it was compacted —
+the retained epochs are the only place that content still exists.
+
 - Find sessions about a topic (FTS, lowercase your terms):
   `SELECT DISTINCT session_id, any(project), min(ts) FROM messages
-   WHERE hasToken(text_word, 'clickhouse') GROUP BY session_id
+   WHERE hasToken(text_word, 'clickhouse') AND <CUR> GROUP BY session_id
    ORDER BY 3 DESC LIMIT 10 SETTINGS final=1, join_use_nulls=1 FORMAT PrettyCompact`
 - Recent sessions: `SELECT session_id, source, project, started, first_prompt
    FROM $(memhouse sessions-query) AS c ORDER BY started DESC LIMIT 20 SETTINGS final=1, join_use_nulls=1`
+  (the rollup applies the current-parse filter itself)
 - Replay one session: `SELECT role, text FROM messages
-   WHERE session_id = '<id>' ORDER BY seq SETTINGS final=1, join_use_nulls=1`
+   WHERE session_id = '<id>' AND <CUR> ORDER BY seq SETTINGS final=1, join_use_nulls=1`
 
 **Rules.**
-- Memory is READ-ONLY for you. Never INSERT/ALTER/DROP — ingestion belongs to the
-  memhouse shipper alone.
+- Memory is READ-ONLY for you: never INSERT/ALTER/DROP the ROOMS (sessions, messages,
+  tool_calls) — ingestion belongs to the memhouse shipper alone. The one exception is
+  membership administration through the `memhouse` CLI: `/mem:invite` mints a user and
+  `/mem:share` grants read access, both via the tool, not by you writing to the rooms.
 - Quote retrieved content as *the user's past sessions*, and cite the session_id
   when the user may want to dig deeper.
-- Other members' sessions are invisible to you unless they have granted you their rooms.
-  You hold no grant on them otherwise, so naming one fails rather than returning nothing.
-  An empty result means "nothing visible", not "nothing ever happened".
+- Other users' HOUSES (other databases on the same server) are readable only when
+  shared with this credential (`/mem:share` on their side). Query a shared house by
+  qualified names — `polat.messages` — with the same CUR filter. An empty result
+  means "nothing visible", not "nothing ever happened".
 - Do not paste credentials from `{{ENV_FILE}}` into responses, commits, or logs.

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

@@ -1,8 +1,17 @@
 {
-  "name": "memhouse",
-  "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: search, browse, and analyze every past session across all 17 supported editors and machines. Skills install as /memhouse:search, /memhouse:sessions, and /memhouse:sql.",
-  "version": "0.4.6",
-  "author": { "name": "Ramazan Polat" },
+  "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.11.0",
+  "author": {
+    "name": "Ramazan Polat"
+  },
   "homepage": "https://github.com/agent-realm/memhouse",
-  "keywords": ["memory", "clickhouse", "search", "sessions", "analytics", "agentlytics"]
+  "keywords": [
+    "memory",
+    "clickhouse",
+    "search",
+    "sessions",
+    "analytics",
+    "agentlytics"
+  ]
 }

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

@@ -0,0 +1,112 @@
+---
+name: ask
+description: Answer a question FROM conversation memory — retrieve the relevant past sessions out of the memhouse ClickHouse store, read the actual transcripts, and synthesize an answer with citations. Use when the user asks something their past work already answered, e.g. "how did I fix X last time", "what approach did we settle on for Y", "why did we choose Z", "have I solved this error before", "what did the reviewer say about W". This is the retrieve-and-answer skill; /mem:search is find-the-session, /mem:sql is run-a-query.
+user-invocable: true
+argument-hint: "<question about past work>"
+allowed-tools: Bash
+---
+
+# /mem:ask — answer from conversation memory
+
+Answer the user's question from what the house holds, not from what you assume. The
+house is the archive that OUTLIVES the transcripts on disk — Claude Code compacts and
+deletes local session files, so for anything older than ~30 days memhouse is the only
+place the answer still exists.
+
+The synthesis is yours; the store is not. memhouse itself runs no LLM anywhere in its
+write or read path — this skill retrieves rows and YOU read them. Never present a guess
+as a retrieval: if the house has nothing on the question, say so.
+
+## Connection
+
+**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
+MEMHOUSE`, no `set -x` around these commands. Anything you print becomes part of a
+transcript that memhouse itself ships into the house.
+
+Credentials resolve as **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`**
+(default `~/.memhouse/env`) — the same order the `memhouse` CLI uses:
+
+```bash
+MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
+_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
+set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
+[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
+[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
+if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
+  echo "no memhouse house configured — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
+  echo "Run: memhouse install" >&2
+  exit 1
+fi
+
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-mem}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
+<the query>
+FORMAT JSONEachRow
+SQL
+```
+
+`readonly=1` is pinned on every request: this skill never writes.
+
+## The method — retrieve, read, answer, cite
+
+**Escaping, before anything touches SQL.** Search terms, session ids and user ids are
+arbitrary text going inside single-quoted literals: escape backslashes then single
+quotes (`\` → `\\`, `'` → `\'`) in every value you splice in. A term like `O'Reilly`
+otherwise breaks the query — and crafted text could reshape it.
+
+**1. Extract search terms from the question.** Not the question verbatim — the terms
+that would appear in the ANSWER. "How did I fix the ClickHouse auth error?" → search
+`ClickHouse auth`, `Authentication failed`, `ACCESS_DENIED` — error strings beat
+paraphrases, identifiers beat prose. Run 2–3 term variants; the FTS columns are
+lowercased, so lowercase your needle.
+
+```sql
+SELECT session_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
+FROM messages
+WHERE text_ngram LIKE '%needle%'
+GROUP BY session_id ORDER BY max(ts) DESC LIMIT 8
+```
+
+**2. Read the strongest sessions — the actual turns, not just the hit line.** Pull a
+window around the hits 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>
+ORDER BY seq
+```
+
+Join on `(session_id, user_id)` always — two housemates can collide on an
+adapter-local session id.
+
+**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>` prints the command). Quote the decisive lines verbatim where the exact
+wording matters (error text, a command, a config value).
+
+**4. Nothing found is an answer too.** Say what you searched and where the house's
+coverage ends (`SELECT min(ts), max(ts), count() FROM messages`) rather than padding.
+
+## What can bite
+
+- **Rows can hold more than one PARSE of a session** (`origin`/`epoch` are in the key —
+  the house retains superseded parses instead of deleting them). Counts and rollups must
+  filter to the current epoch:
+  ```sql
+  WHERE origin != 'ship'
+     OR (session_id, user_id, epoch) IN (
+          SELECT session_id, user_id, max(epoch) FROM messages
+          WHERE origin = 'ship' GROUP BY session_id, user_id)
+  ```
+  For step 2's transcript reads, PREFER the filter as well — an unfiltered read of a
+  compacted session interleaves two parses. Drop it deliberately only when the question
+  is about what a session said BEFORE it was compacted; the superseded epochs are the
+  one place that content still exists.
+- **`text` is truncated at 50,000 chars** and tool args at 20,000 — a missing tail is
+  truncation, not absence.
+- The rollup (`sessions_v`) is a saved query, not a table — get it with
+  `memhouse sessions-query` if you need per-session totals.

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

@@ -0,0 +1,76 @@
+---
+name: hello
+description: Introduce memhouse — what it is, what it remembers, and how to use it from here. Use when the user asks "what is memhouse", "what can my memory do", "how do I use this", invokes /mem:hello, or seems new to the memory system. Also the right first answer when another /mem skill fails because nothing is configured yet.
+user-invocable: true
+argument-hint: ""
+allowed-tools: Bash
+---
+
+# /mem:hello — welcome to your memory
+
+**Invoking this skill IS the request. Give the introduction immediately — grounded in
+this machine's actual state, not hypotheticals. Nothing to clarify first.**
+
+## First: find out what state this machine is in
+
+RUN this yourself with the Bash tool — do not print it for the user to run, and do not
+show the env values it sources. Read its output, then write the introduction using the
+ACTUAL numbers it returns (interpolate them; never emit the literal "N sessions").
+
+```bash
+MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
+_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
+set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
+[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
+[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
+if [ -n "${MEMHOUSE_URL:-}" ] && [ -n "${MEMHOUSE_USER:-}" ]; then
+  curl -sS -m 5 --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+    --data-binary "SELECT uniqExact(session_id), count(), formatDateTime(min(ts),'%Y-%m-%d') FROM messages" \
+    "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-mem}&final=1&readonly=1" 2>&1
+else
+  echo "NOT_CONFIGURED"
+fi
+```
+
+(Do not print the env values, and do not narrate that you are withholding them — just use them.)
+
+## Then introduce it — three states, three openings
+
+**Configured and answering** — open with the numbers: "Your memory holds N sessions
+(M messages) going back to <date> — every conversation you've had with coding agents
+(Claude Code, Codex, Cursor, Gemini CLI and 13 more), across all your machines. It
+outlives the transcripts on disk: editors delete their session files after weeks; this
+doesn't." Then the tour below.
+
+**Not configured** — say what memhouse IS (one paragraph: a personal, permanent archive
+of every AI coding session, stored in a ClickHouse "house" you own), then how to start:
+`memhouse onboard` (wizard) or `memhouse install --env <file>` if someone invited them
+(the file came from `/mem:invite` on the inviter's side).
+
+**Configured but unreachable** — say which URL refused, point at `memhouse doctor`,
+stop. Never guess another endpoint.
+
+## The tour (keep it to one screen)
+
+What you can DO from this chat:
+
+- `/mem:ask <question>` — answer from your past work, with citations ("how did I fix X
+  last time?")
+- `/mem:search <terms>` — find the session ("that conversation about Y")
+- `/mem:sessions` — browse and filter what's stored
+- `/mem:sql <question or SQL>` — ad-hoc analytics (tokens, costs, rankings)
+- `/mem:status` — is it healthy, how much is stored, which machines ship into it
+
+And around other people — **inviting comes before sharing**:
+
+- `/mem:invite <name>` — mint a friend's account + their own house on your ClickHouse,
+  hand them one env file; they install with it and have their own memory
+- `/mem:share <name>` — once they exist, open a read-only window into YOUR memory
+  (`/mem:share revoke <name>` closes it); `/mem:users` shows who's around
+
+Also worth naming: `memhouse start` serves a dashboard at http://localhost:4640 for
+browsing and analytics outside the chat, and everything here is read-only for agents —
+only the shipper writes.
+
+End by offering one concrete action: a search for something they mentioned recently, or
+`/mem:status` if they seem unsure it's working. One offer, not a menu.

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

@@ -0,0 +1,65 @@
+---
+name: invite
+description: Invite another person onto this memhouse ClickHouse — mint their user and their own house (database) with the right grants, producing the one env file their install needs. Use when the user says "invite X", "add X to memhouse", "get my friend set up". Inviting comes BEFORE sharing — /mem:share can only grant a user who exists.
+user-invocable: true
+argument-hint: "<name> [into <db>]"
+allowed-tools: Bash
+---
+
+# /mem:invite — mint a member and hand them one file
+
+This runs the `memhouse invite` CLI and nothing else. Inviting mints a ClickHouse user
+and a house, which takes an ADMIN credential — and an admin password must never enter
+this conversation, because memhouse ships the transcript into the house it just
+provisioned. The CLI is the only safe path: the admin password is passed to one process
+and never echoed. **Do not hand-run `CREATE USER` / `GRANT` with an admin password
+substituted into a command — that burns the credential into the transcript on disk.**
+
+## Do this
+
+1. Confirm the `memhouse` binary is present: `command -v memhouse`. If it is not, tell
+   the user to install it first (`npm install -g memhouse`) — there is no in-skill
+   fallback, on purpose (see above).
+
+2. Gather ONLY two things by asking:
+   - the invitee's **name** (validate `[A-Za-z][A-Za-z0-9_]*`; refuse otherwise)
+   - the **URL the invitee will reach the house at** — NOT localhost (that is the
+     invitee's own machine). A LAN IP, hostname, or tunnel.
+
+   Do NOT ask for an admin user or password yet — the next step usually needs neither.
+   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:
+
+   ```
+   memhouse invite <name> --url <url> [--db <shared-house>]
+   ```
+
+   If it prints `invite written: …`, go to step 4 — you are done, and no admin secret
+   ever touched this conversation.
+
+   ONLY if it fails with "your configured credential cannot create users" does
+   provisioning need a real admin. Do NOT take the admin password in chat — memhouse
+   archives this transcript. Hand the user the line to run THEMSELVES (a leading space
+   keeps it out of shell history):
+
+   ```
+   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
+
+## 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.

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

@@ -6,7 +6,7 @@ argument-hint: "<search terms> [in <project>] [last <N> days] [from <editor>]"
 allowed-tools: Bash
 ---
 
-# /memhouse:search — search conversation memory
+# /mem:search — search conversation memory
 
 Search the full message history in the memhouse house. Every room is named for your
 ClickHouse user — `messages`, `sessions` — see **Room names** below.

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

@@ -6,7 +6,7 @@ argument-hint: "[N] [project <name>] [from <editor>] [today|week|month]"
 allowed-tools: Bash
 ---
 
-# /memhouse:sessions — browse session history
+# /mem:sessions — browse session history
 
 List/filter sessions from the session rollup — a saved query over your own rooms, not an
 object; `memhouse sessions-query` prints it (session metadata +
@@ -154,11 +154,11 @@ FORMAT PrettyCompact
 | "what was I working on yesterday?" | `WHERE ended > now() - INTERVAL 1 DAY` |
 | "show my last 10 sessions in agentlytics" | `LIMIT 10 … WHERE project ILIKE '%agentlytics%'` |
 | "list my cursor sessions this month" | `WHERE source = 'cursor' AND ended > now() - INTERVAL 30 DAY` |
-| "which machine did I do the schema work on?" | search via /memhouse:search, or filter `host` here |
+| "which machine did I do the schema work on?" | search via /mem:search, or filter `host` here |
 
 ## Output
 
 A compact table: when, name (or first prompt), source, host, project, msgs,
 tokens. Offer to pull a full transcript next
 (`SELECT role, text FROM messages WHERE session_id = '…' ORDER BY seq`) or to
-run /memhouse:search for a specific quote.
+run /mem:search for a specific quote.