memhouse 0.8.0 → 0.11.0

package/memhouse/RESUME-AND-UPDATE.md

@@ -95,18 +95,15 @@ original to duplicate the copy.
 
 ### The gap
 
-`npm i -g memhouse@latest` does one third of the job, and the other two thirds have each
-cost a real machine real sessions:
-
-1. **`--allow-scripts=better-sqlite3` is not remembered.** Omit it on the upgrade and
-   `better-sqlite3` has no binding again — cursor, zed, opencode, goose and antigravity
-   read zero sessions on every pass afterwards.
-2. **The daemons keep running the old code.** See §3.
-3. **The house can be older than the shipper.** A newer shipper may need a column an
+`npm i -g memhouse@latest` does half the job, and the other half has cost a real machine
+real sessions:
+
+1. **The daemons keep running the old code.** See §3.
+2. **The house can be older than the shipper.** A newer shipper may need a column an
    existing room lacks; it detects that and prints the rebuild, but only if something runs
    it.
 
-And from a checkout there is a fourth: `git pull` updates `ui/src` and leaves the built
+And from a checkout there is a third: `git pull` updates `ui/src` and leaves the built
 bundle in `public/`, so the dashboard serves the previous release however often it is
 restarted. A published tarball is immune — `prepack` builds `public/` before publish.
 
@@ -114,7 +111,7 @@ restarted. A published tarball is immune — `prepack` builds `public/` before p
 
 | Kind | Detected by | Action |
 |---|---|---|
-| `global` | under `npm prefix -g` | `npm i -g memhouse@latest --allow-scripts=better-sqlite3` |
+| `global` | under `npm prefix -g` | `npm i -g memhouse@latest` |
 | `checkout` | a `.git` at the root | `git pull --ff-only` → `npm install` → `npm run build` |
 | `local-dep` | `node_modules/memhouse`, not under the global prefix | refuse; print the right command for where it lives |
 | `npx` | `_npx` in the resolved path | refuse — the next `npx` resolves the registry anyway |

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

@@ -7,21 +7,21 @@ in order; every command is copy-pasteable.
 machine it runs on — which editors have sessions, whether a ClickHouse answers, whether
 docker or podman exists — and states the one route that applies. This file is the static
 long-form version and assumes a reachable ClickHouse already exists, which is the case
-`deploy --local` was added to remove. Prereqs: Node >= 20.19 and a reachable
+`deploy --local` was added to remove. Prereqs: Node >= 24 and a reachable
 ClickHouse >= 26.2 (local server, Cloud, or a kernel house — see
 `kernel-install.md` for the kernel path). No checkout required — memhouse is on npm.
 
 ## 1. Install
 
 ```bash
-npm install -g memhouse --allow-scripts=better-sqlite3
+npm install -g memhouse
 ```
 
-`--allow-scripts=better-sqlite3` is required, not cosmetic. Five adapters (cursor,
-goose, opencode, zed, antigravity) read SQLite session stores, and npm 12 blocks
-the install script that builds the native binding. Without it those five silently
-return zero sessions and you ship a partial history. Verify with step 4 —
-`memhouse discover` names any adapter it had to skip.
+No flags. This line used to require `--allow-scripts=better-sqlite3`, without which
+five adapters (cursor, goose, opencode, zed, antigravity) silently returned zero
+sessions and you shipped a partial history. SQLite now comes from `node:sqlite`, which
+is part of Node, so there is no install script and nothing to allow. Step 4 still
+verifies — `memhouse discover` names any adapter it had to skip, for any reason.
 
 On `EACCES`, decide by **who owns the prefix root**. Not the path — Homebrew's
 prefix is `/usr/local` on Intel and `/opt/homebrew` on Apple Silicon and is
@@ -34,7 +34,7 @@ ls -ld "$(npm prefix -g)"     # the prefix ROOT decides
 ```
 
 Prefix root owned by `root` → a system-managed Node; re-run as
-`sudo npm install -g memhouse --allow-scripts=better-sqlite3`.
+`sudo npm install -g memhouse`.
 
 Prefix root owned by the current user → the prefix is theirs (Homebrew, fnm, nvm,
 volta), so the root-owned file npm tripped on is a stray from an earlier `sudo npm`
@@ -42,31 +42,34 @@ and another `sudo` adds more. Repair that path instead:
 `sudo chown -R "$(id -u):$(id -g)" <path npm named>` (same for `~/.npm`).
 
 From a checkout instead (contributors): `npm install --no-audit --no-fund` in the
-repo root — its `allowScripts` field already covers the binding — then substitute
-`node bin/memhouse.js` for `memhouse` below.
+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.
 
@@ -77,14 +80,18 @@ memhouse discover     # which adapters were read, and which were SKIPPED
 memhouse stats        # per-source counts now in the house
 ```
 
-Read `discover` first. It prints one line per editor it found sessions for, and
-warns by name about any adapter it had to skip — that warning is the only signal
-that step 1's `--allow-scripts` flag was missed and five editors are dark.
+Read `discover` first. It prints one line per editor it found sessions for, and warns
+by name about any adapter it had to skip. On a healthy install that list is empty: the
+one cause that could take five adapters out at once — a missing native SQLite binding —
+no longer exists, so anything named here is a single editor's own store (locked by a
+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" \
@@ -107,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/kernel-install.md

@@ -35,7 +35,7 @@ rotate on first connect (`issue-credential{user:'memhouse_root'}`).
 ## 2. Owner sets up the house
 
 ```bash
-npm install -g memhouse --allow-scripts=better-sqlite3
+npm install -g memhouse
 memhouse install --yes \
   --url https://<kernel-host>:8443 \
   --user memhouse_root \
@@ -46,9 +46,9 @@ memhouse install --yes \
 That writes `~/.memhouse/env`, applies the schema, and runs the first ship.
 `memhouse start` then keeps it fresh on a 300s loop.
 
-Keep `--allow-scripts=better-sqlite3`: without it npm 12 leaves `better-sqlite3`
-with no native binding and the five SQLite-backed adapters ship nothing, silently.
-`memhouse discover` names any adapter it had to skip.
+No flags: SQLite comes from `node:sqlite`, so there is no native binding to build
+and no adapter that can go dark for want of one. `memhouse discover` still names any
+adapter it had to skip — now always a single editor's own store.
 
 The kernel never runs or reads any of this — it is content-blind; the shipper is
 the agency's own resident, a deterministic `worker` on a loop (no LLM, not an

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.