memhouse 0.16.0 → 0.17.0

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

@@ -1,226 +1,105 @@
 ---
 name: sql
-description: Run free-form read-only SQL against memhouse conversation memory (typed sessions/messages/tool_calls tables on ClickHouse, shared by the house). Use for ad-hoc analytics the other memhouse skills don't cover — token spend, model/editor usage, tool rankings, activity heatmaps, busiest days/projects, cache-hit ratios, or any custom question over conversation data — over your own house, or a friend's house shared with you when they name it.
+description: Run read-only SQL over memhouse conversation memory for numbers rather than transcripts — token spend, cost by model or editor or project, tool-call rankings, activity over time, busiest days, cache-hit ratios, session length distributions, or any custom aggregate across the typed sessions/messages/tool_calls tables. Use when the user wants a figure, a ranking, a trend or a breakdown - "what did I spend on Opus", "which tools do I use most", "how many sessions per project", "my busiest week", "compare editors". For finding or answering FROM past conversations, use /mem:recall instead. Works over your own house, or a housemate's when they name it.
 user-invocable: true
-argument-hint: "<question or SQL>"
+argument-hint: "<the question, or the SQL>"
 allowed-tools: Bash
 ---
 
-# /mem:sql — ad-hoc analytics
+# /mem:sql — analytics over the rooms
 
-If the user gives SQL, run it (append `FORMAT PrettyCompact` if no FORMAT
-given). If they give a question, write the SQL yourself from the schema below.
+For **numbers**. When the answer is a passage from a past conversation, that is
+`/mem:recall` — this skill counts, groups and ranks.
 
-**Read-only rule:** the shipper (`ship.js`) is the only writer, and it is INSERT-ONLY: it
-never deletes and never mutates, because a re-parse that shrank or was rewritten is
-written under a new `epoch` instead of over the stored one. Never INSERT/ALTER/DROP from
-here. The shipping path needs `SELECT, INSERT, ALTER ADD COLUMN, OPTIMIZE` and nothing
-more — the `ALTER DELETE` this line used to list was there for the per-session clear that
-no longer exists, so no unattended process can lose you a row. `ALTER DELETE` is still
-needed by the one command that is *meant* to remove rows, `memhouse reset`, which asks
-first. Most houses grant `ALL` on the database anyway. Reads need no scoping clause: the
-house you can name is already yours, and there is no policy to work around.
+**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%**.
 
-**One session can be in `messages` twice.** A session that Claude Code compacted, or that
-shrank for any other reason, keeps its earlier parse — that is the whole point of `epoch`,
-and it is why nothing is ever deleted. Ad-hoc SQL must filter to the current parse or it
-counts such a session twice:
+## Read-only, and that is enforced
 
-```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)
-```
+Every query goes through `readonly=1`. The shipper is the only writer; a skill that
+mutates the archive is a skill that can destroy it. Never `INSERT`, `ALTER`, `DROP`,
+`TRUNCATE` or `OPTIMIZE` from here — not even "just to tidy up". If the user genuinely
+wants a write, that is `/mem:admin` with its confirmations, not this.
 
-Drop the filter deliberately when you want the history — "what did this session say before
-it was compacted" is a question only the house can answer, because the transcript on disk
-is gone.
-
-The recipe below pins `readonly=1` on every request, so a write that slips past the rule
-is refused by the server (`Code: 164 … Cannot execute query in readonly mode`) rather
-than by good intentions. Two honest limits: it is a **setting, not a grant** — a caller
-who writes their own URL can leave it off — and the HTTP interface refuses
-multi-statement bodies, so `SET readonly=0;` cannot be smuggled into a query. For
-enforcement that does not depend on this file, the house owner can mint a second
-`SELECT`-only credential and point the skills at that instead.
-
-## 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. Every query
-runs over ClickHouse HTTP with `final=1` and `join_use_nulls=1` (ReplacingMergeTree
-keeps stale row versions until merges; `final=1` collapses to latest-wins — always
-include it on reads):
-
-```bash
-# Config lives at $MEMHOUSE_HOME/env (default ~/.memhouse/env). Exported MEMHOUSE_*
-# vars WIN over the file — snapshot them, source, then put them back. Sourcing alone
-# lets a stale file silently override the house you were pointed at.
-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
-# No default URL. localhost:8123 as memhouse_root is a REAL house on many machines,
-# usually the pilot's own — guessing it reads someone else's memory and looks like it
-# worked. If there is no config, say so and stop.
-if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
-  # An explicit test, not ${VAR:?msg}: zsh does not expand the message, so under the
-  # shell Claude Code actually uses the refusal read "nothing in $MH_ENV" literally.
-  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
-
-# --user, not a -K config file. The config-file parser treats `"` and `\` specially, so a
-# password containing either authenticates fine from the CLI and fails from every skill
-# with "password is incorrect" — measured. The argv exposure -K was meant to avoid is not
-# observable here either: curl blanks the --user argument before `ps` can read it (0 hits
-# in 50 samples). What actually leaks a credential is PRINTING it, which the rule above
-# covers.
-curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
-  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
-<the query>
-FORMAT PrettyCompact
-SQL
-```
+## Method
+
+1. **Say what you are counting** before running it — "messages, current parse only, by
+   model, this year". Half of wrong analytics is a right query answering a different
+   question.
+2. **Apply the epoch filter to anything aggregating.** Copy it from the reference.
+3. **Group by `(session_id, user_id)`** wherever a session is the unit.
+4. **Show the SQL** beside the result. The user can re-run and adjust it; an unexplained
+   number is not an answer.
+5. **`FORMAT PrettyCompact`** for humans, `JSONEachRow` when you need to post-process.
 
-`FORMAT PrettyCompact` for display, `FORMAT JSONEachRow` to parse.
-
-## Room names — plain, shared tables
-
-The house's rooms are three plain tables: `messages`, `sessions`, `tool_calls` — resolved
-by the connection's database (`MEMHOUSE_DB`), not by who is asking. Everyone in the house
-writes into the same tables; `user_id` (stamped by the server) says whose row it is and
-`host` says which machine shipped it. Filter with `WHERE user_id = '<name>'` when you want
-one person, or leave it off for the whole house.
-
-**Another person's house (shared with you).** A house is a database; a share is a
-read-only GRANT on it. Because the rooms resolve by the connection's database, you read a
-friend's memory by pointing the connection at THEIR house — same credentials, different
-`database`. `SHOW DATABASES` lists what you may read; a name that is not `system` /
-`information_schema` / `default` and not your own `$MEMHOUSE_DB` is a house shared with
-you. When the user names one ("query yigit's house", "on yigit", "from yigit"), replace
-`database=${MEMHOUSE_DB:-$MEMHOUSE_USER}` with `database=<house>` in the connection recipe and leave
-the table names bare — or, to join across houses in one query, qualify tables explicitly
-(`yigit.messages`). Read-only: a refused SELECT means that house was not shared with you.
-
-**Keep the SQL heredoc quoted (`<<'SQL'`).** This skill once told the agent to substitute
-a shell variable into the table names, which cannot expand inside a quoted heredoc — so
-the agent unquotes it, and then the SEARCH TERMS expand too. Both instances driving this
-skill did exactly that, unprompted, on the first attempt. Measured consequences, from
-`system.query_log`:
-
-- a term containing `$home` became the empty string, so `LIKE '%%'` matched **every row**
-  and reported hits with exit 0 — silently wrong, not an error;
-- a term containing a backtick **executed the command inside it**.
-
-A user's search term is arbitrary text. With the heredoc quoted, neither can happen.
-
-**There is no `sessions_v` object.** The session rollup is a saved query over those same
-rooms — `memhouse sessions-query` prints it for whoever you are connected as, ready to
-paste into a `FROM (...) AS c` position.
-
-**The rollup is self-contained.** As of 0.4.5 the printed text carries its own `FINAL` on
-both rooms and a trailing `SETTINGS join_use_nulls = 1`, so it is correct wherever you
-paste it. Both matter: without `FINAL` every message is counted once per undeleted
-ReplacingMergeTree version (2x right after a ship, 3x a few ships later — measured, and it
-grows); without `join_use_nulls` a session with no messages reports `total_msgs = 1`
-rather than 0.
-
-**If the `memhouse` binary is not on PATH**, you cannot print the rollup — the skills are
-installable on their own. Query the rooms directly instead: `sessions` for metadata and
-`messages` for counts, each read `FINAL`, joined on `session_id` **and `user_id`** — the
-tables are shared, and joining on `session_id` alone can merge two housemates' rows.
-Prefer the binary when it is there; a rollup you assemble by hand and one printed by a
-DIFFERENT memhouse version are the two ways this goes quietly wrong.
-
-## Schema (the house)
-
-| Object | Kind | Columns |
-|---|---|---|
-| `sessions` | table, 1 row/session | `session_id, source, host, name, mode, folder, project, git_branch, created_at, last_updated_at, message_count, path, extra JSON, origin, epoch, user_id, ingested_at` |
-| `messages` | table, 1 row/message **per parse** | `session_id, seq, source, host, ts, role, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, text, project, folder, is_subagent, extra JSON, line_hash, origin, epoch, user_id, ingested_at` + FTS columns `text_ngram`/`text_word` (lowercased; see /mem:search) |
-| `tool_calls` | table, 1 row/tool call **per parse** | `session_id, seq, idx, source, host, tool_name, args, ts, project, folder, origin, epoch, user_id, ingested_at` |
-| `house_meta` | table, house's own record | `key, value, updated_at, updated_by, host` — `schema_version`, per-member `client_version:<user>` |
-| `house_events` | append-only log | `event_at, kind, id, status, from_version, to_version, actor, host, rows_before, rows_after, detail` — migrations, version changes |
-| the rollup | **saved query**, not an object — `memhouse sessions-query` prints it | `session_id, source, host, name, mode, folder, project, git_branch, user_id, created_at, last_updated_at, started, ended, duration_sec, total_msgs, user_msgs, assistant_msgs, subagent_msgs, models, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, user_chars, assistant_chars, first_prompt` |
-
-Notes: `source` = editor id (`claude-code`, `codex`, `cursor`, `cursor-agent`,
-`vscode`, `zed`, `opencode`, `gemini-cli`, `windsurf`, `antigravity`, …);
-`seq` = message index within its session (0-based); `tool_calls.idx` = call
-index within the session; `user_id` is server-stamped (`currentUser()`); `origin` is
-`ship` for rows the shipper wrote and anything else for imports; `epoch` is which parse
-of the session a row belongs to — see the filter above;
-`models` in the rollup is an `Array(String)`. Exclude `''` and
-`'<synthetic>'` from model aggregates.
-
-## Examples
-
-Token spend by model:
+## Shapes worth knowing
+
+Cost is **derived**, not stored — `pricing.json` × tokens, per model.
 
 ```sql
-SELECT model, sum(input_tokens) AS in_tok, sum(output_tokens) AS out_tok,
-       sum(cache_read_tokens) AS cache_read
+-- spend by model, current parse only
+SELECT model,
+       count() AS messages,
+       sum(input_tokens)  AS in_tok,
+       sum(output_tokens) AS out_tok,
+       sum(cache_read_tokens)  AS cache_read,
+       sum(cache_write_tokens) AS cache_write
 FROM messages
-WHERE model NOT IN ('', '<synthetic>')
-GROUP BY model
-ORDER BY out_tok DESC
-FORMAT PrettyCompact
+WHERE model != ''
+  AND (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))
+GROUP BY model ORDER BY out_tok DESC
 ```
 
-Which tools do I use most (memhouse exclusive — memory-house has no tool table):
-
 ```sql
+-- which tools, how often
 SELECT tool_name, count() AS calls, uniqExact(session_id) AS sessions
 FROM tool_calls
-GROUP BY tool_name
-ORDER BY calls DESC
-LIMIT 20
-FORMAT PrettyCompact
+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)
+GROUP BY tool_name ORDER BY calls DESC LIMIT 25
 ```
 
-Busiest days, last two weeks:
+Note `tool_calls` takes its epoch from **`messages`** — both rooms are written by the same
+pass at the same epoch, and a parse that produced messages but no tool calls would
+otherwise resolve to a superseded epoch and serve the wrong parse's calls.
 
 ```sql
-SELECT toDate(ts) AS day, uniqExact(session_id) AS sessions, count() AS msgs
+-- activity by day, one machine
+SELECT toDate(ts) AS day, uniqExact(session_id) AS sessions, count() AS messages
 FROM messages
-WHERE ts > now() - INTERVAL 14 DAY
-GROUP BY day
-ORDER BY day DESC
-FORMAT PrettyCompact
+WHERE host = '<host>'
+  AND (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))
+GROUP BY day ORDER BY day DESC LIMIT 30
 ```
 
-Activity by editor this week / subagent share:
+For per-session totals, `memhouse sessions-query` prints a self-contained rollup that
+already carries `FINAL` — prefer it to hand-joining `sessions` and `messages`.
 
-```sql
-SELECT source, count() AS msgs, countIf(is_subagent) AS subagent_msgs
-FROM messages
-WHERE ts > now() - INTERVAL 7 DAY
-GROUP BY source
-ORDER BY msgs DESC
-FORMAT PrettyCompact
-```
+## Caveat the answer, every time it needs it
 
-Longest sessions by wall-clock:
+These are properties of the data, not of your query, and a number presented without them
+misleads:
 
-```sql
-SELECT name, project, source, duration_sec, total_msgs, output_tokens
-FROM (the rollup from `memhouse sessions-query`)
-ORDER BY duration_sec DESC
-LIMIT 10
-FORMAT PrettyCompact
-```
+- **Several adapters ship no tokens at all** — `kiro`, `vscode`, `zed`, and `cursor` on
+  one storage path. Their cost reads `$0`, which means *unknown*. Exclude them or label
+  them; never let them dilute an average silently.
+- **Per-message timestamps are interpolated** for most adapters — only session bounds are
+  real. Any hour-of-day or "peak time" result inherits that and should say so.
+- **`text` truncates at 50,000 chars**, `args` at 20,000, so length statistics have a
+  ceiling.
+- **Tool results are not stored**, so nothing here can measure what a command returned.
 
-## Output
+## Someone else's house
 
-Run the query, present the result as a compact table, and add one or two lines
-of interpretation. Offer a natural follow-up cut (by source, by project, by
-host, by token volume) when relevant. Dollar costs are computed by the
-dashboard server from pricing.js — token sums here are the raw material, not
-dollars.
+`SHOW DATABASES` lists what your credential may read; anything that is not `system`,
+`information_schema`, `default` or your own is a share. Point `database=` at it, leave
+table names bare, and say whose house the number came from.

package/memhouse/flags.js

@@ -15,6 +15,7 @@ const GLOBAL_FLAGS = ['json', 'yes', 'help', 'version'];
 const COMMAND_FLAGS = {
   null: [], help: [], version: [],
   whoami: ['admin'],
+  share: ['only', 'revoke', 'list'],
   discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [],
   status: [], start: [],
   onboard: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'target', 'house-port', 'tag', 'local'],

package/memhouse/share.js

@@ -0,0 +1,64 @@
+/**
+ * `memhouse share <user> [--only <scope>] [--revoke]` / `memhouse share --list`
+ *
+ * Full share is one statement: GRANT SELECT on the house. Partial share adds a ROW
+ * POLICY per room, so the grantee reads only the rows the scope allows.
+ *
+ * Why no permissive catch-all policy for everyone else, which is the obvious design:
+ * row policies are OR'd, so a `USING 1 TO ALL EXCEPT alice` policy silently overrides
+ * the NEXT scoped grantee's filter — measured, bob saw all 22,500 rows instead of his
+ * 1,860. It fails OPEN and it fails quietly. ClickHouse already answers this correctly
+ * through `users_without_row_policies_can_read_rows`: a reader with no policy on a table
+ * still sees every row. Verified against a non-superuser member owning its own house —
+ * owner and full-share grantees were both unaffected while a third user was scoped.
+ *
+ * That setting is server config, not a query setting, and its default has moved between
+ * versions. So `probePermissive()` measures the behaviour before the first policy is
+ * created rather than assuming it, and refuses when the server would blindfold everyone.
+ */
+
+/** Columns a scope may filter on, and the column each room spells time with. */
+const SCOPE_COLUMNS = {
+  session: { column: () => 'session_id', quote: true },
+  project: { column: () => 'project', quote: true },
+  folder: { column: () => 'folder', quote: true },
+  host: { column: () => 'host', quote: true },
+  source: { column: () => 'source', quote: true },
+  // `sessions` has no `ts`; its clock is `created_at`. One literal predicate cannot span
+  // the rooms, so time scopes render per room.
+  since: { column: (room) => (room === 'sessions' ? 'created_at' : 'ts'), op: '>=' },
+  until: { column: (room) => (room === 'sessions' ? 'created_at' : 'ts'), op: '<' },
+};
+
+/** `project=memhouse,since=2026-01-01` -> [{key, value}], rejecting anything unknown. */
+function parseScope(raw) {
+  const out = [];
+  for (const part of String(raw).split(',').map((s) => s.trim()).filter(Boolean)) {
+    const m = /^([a-z_]+)\s*=\s*(.+)$/.exec(part);
+    if (!m) throw new Error(`scope "${part}" is not <key>=<value>`);
+    const key = m[1].toLowerCase();
+    if (!SCOPE_COLUMNS[key]) {
+      throw new Error(`unknown scope key "${key}" — try: ${Object.keys(SCOPE_COLUMNS).join(', ')}`);
+    }
+    out.push({ key, value: m[2].trim() });
+  }
+  if (!out.length) throw new Error('--only was given nothing to scope on');
+  return out;
+}
+
+/** The WHERE-shaped predicate for one room. Values are escaped, never interpolated raw. */
+function scopePredicate(scope, room, sqlStr) {
+  return scope.map(({ key, value }) => {
+    const spec = SCOPE_COLUMNS[key];
+    const col = spec.column(room);
+    if (spec.op) return `${col} ${spec.op} parseDateTimeBestEffort(${sqlStr(value)})`;
+    return `${col} = ${sqlStr(value)}`;
+  }).join(' AND ');
+}
+
+/** Policy name for a grantee's room — predictable, so revoke can find every one. */
+function policyName(user, room) {
+  return `mh_share_${user}_${room}`;
+}
+
+module.exports = { SCOPE_COLUMNS, parseScope, scopePredicate, policyName };

package/package.json

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

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

@@ -1,131 +0,0 @@
----
-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". Also answers from a friend's house shared with you when they name it ("how did yigit fix X", "ask yigit's memory"). 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:-$MEMHOUSE_USER}&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.
-
-## Answering from another person's house (shared with you)
-
-The house is a ClickHouse database; a share is a read-only GRANT on it. When the user asks
-about a FRIEND's memory — "how did yigit fix X", "in yigit's house", "ask yigit's memory",
-"from yigit" — answer from THEIR house without changing your credentials:
-
-1. **Resolve the house.** `SHOW DATABASES` returns what your credential may read; a name
-   that is not `system` / `information_schema` / `default` and not your own `$MEMHOUSE_DB`
-   is a house shared with you. Match the named person to one; set `HOUSE=yigit`. With no
-   house named, `HOUSE=$MEMHOUSE_DB`.
-2. **Point the connection at it:** replace `database=${MEMHOUSE_DB:-$MEMHOUSE_USER}` with
-   `database=<HOUSE>` in the recipe above. The rooms (`messages`, `sessions`) resolve by
-   the connection's database, so retrieval, the transcript read, and the citation all run
-   against that house — leave the table names bare.
-3. **Cite the house.** Say whose memory the answer came from ("from yigit's house") so the
-   user never mistakes a friend's session for their own.
-4. **Read-only, thin by design.** A refused SELECT means the house was not shared with you
-   (or the share was revoked) — say so; never guess another database.
-
-## 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

@@ -1,121 +0,0 @@
----
-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:-$MEMHOUSE_USER}&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.)
-
-## What memhouse is — the overview (give this in every state, before the tour)
-
-One paragraph, grounded not sold: **memhouse is your personal, permanent archive of every
-AI coding session.** A background shipper reads the session files your editors write —
-Claude Code, Codex, Cursor, VS Code, Zed, OpenCode, Gemini CLI and 10 more, 17 in all —
-and ships them into a ClickHouse database you own, called a **house**. YOU choose that
-ClickHouse: a local one on your laptop, one on your own VM, or any ClickHouse server you
-control — managed or remote. memhouse itself is not a hosted service and phones nothing
-home; your sessions go only to the house you point it at, and it runs no LLM in its write
-or read path — it stores rows, the agent reading them (this chat) does the thinking. It
-outlives the transcripts on disk: editors compact and delete their local session files
-after weeks, so for anything older than ~30 days the house is the only place it still
-exists. One archive spans every editor, every project, every machine you ship from.
-
-What it gives you, in one breath: **ask** your own history a question and get a cited
-answer, **search** for the session you half-remember, **query** the raw data for numbers,
-browse a **dashboard**, and **invite** other people onto your ClickHouse so memories can be
-**shared** read-only. The tour below names each.
-
-## 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
-
-The first three overlap — same words work in each — so give the reader the rule that
-separates them: **want a session → search. Want an answer → ask. Want a number → sql.**
-`ask` runs a `search` first, then reads the turns it finds and writes you a cited answer;
-`search` stops at the ranked list of sessions; `sql` counts and aggregates the columns
-rather than hunting text.
-
-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
-- **Read a friend's shared memory** — once they've shared theirs with you, name their
-  house right in the question: `/mem:ask <question> in <their-house>`, or
-  `/mem:search <terms> in <their-house>` / `/mem:sql … on <their-house>`. It reads THEIR
-  house read-only, with your own credentials; `/mem:users` lists the houses shared with
-  you. (A house is a whole ClickHouse database — sharing grants read on it, not on single
-  sessions.)
-
-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.
-
-**Freshness check** — quietly compare the installed client to the latest release; mention
-it ONLY if there's a real gap (don't clutter the welcome otherwise):
-
-```bash
-INSTALLED=$(memhouse version 2>/dev/null | head -1 | tr -d '[:space:]')
-LATEST=$(curl -sS -m 5 https://registry.npmjs.org/memhouse/latest 2>/dev/null | sed -n 's/.*"version":"\([^"]*\)".*/\1/p')
-echo "installed=${INSTALLED:-unknown} latest=${LATEST:-unknown}"
-```
-
-If the installed version is a MINOR or MAJOR behind (or many patches), add one line:
-"heads-up — you're on 0.A.B, 0.C.D is out; `memhouse update` upgrades it and refreshes
-these `/mem:*` skills." A patch or two behind isn't worth mentioning here. Never run the
-update yourself.
-
-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.