memhouse 0.4.4 → 0.7.0

package/{mem-house/delivery/skills/memhouse-search → memhouse/delivery/plugin/skills/search}/SKILL.md

@@ -1,28 +1,56 @@
 ---
-name: memhouse-search
+name: search
 description: Full-text search across ALL shipped agent conversations — every session from all 17 supported editors (Claude Code, Codex, Cursor, VS Code, Zed, OpenCode, Gemini CLI, …), every project, every machine — stored in the memhouse ClickHouse. Use whenever the user refers to something from the past that isn't in the current context, e.g. "what did I say about X", "find that conversation about Y", "when did I work on Z", "did I ever try W", "the chat where we discussed it", "remind me how I did it". Reach for this before saying you don't know about prior work.
 user-invocable: true
 argument-hint: "<search terms> [in <project>] [last <N> days] [from <editor>]"
-allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
+allowed-tools: Bash
 ---
 
-# memhouse-search — search conversation memory
+# /memhouse:search — search conversation memory
 
 Search the full message history in the memhouse house. Every room is named for your
 ClickHouse user — `messages_<you>`, `sessions_<you>` — see **Room names** below.
 
 ## Connection
 
-Credentials come from `~/.memhouse/env` (or already-exported `MEMHOUSE_*` vars).
-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
+**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
-set -a; [ -f ~/.memhouse/env ] && . ~/.memhouse/env; set +a
-curl -sS --fail-with-body --user "${MEMHOUSE_USER:-memhouse_root}:${MEMHOUSE_PASSWORD:-}" \
-  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-mem}&final=1&join_use_nulls=1" <<'SQL'
+# 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:-mem}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
 <the query>
 FORMAT PrettyCompact
 SQL
@@ -38,23 +66,37 @@ Every member owns their own rooms, named for their ClickHouse user:
 the bare names fail with `UNKNOWN_TABLE` rather than returning nothing. You hold no grant
 on anyone else's rooms, so isolation is not something a query can work around.
 
-Resolve your own name once and substitute it into every table name below:
+Ask the server your name once, then **type the literal room name into your SQL** — do not
+reference a shell variable inside the query:
 
 ```bash
-MEM_ME="$(curl -sS --fail-with-body --user "$MEMHOUSE_USER:$MEMHOUSE_PASSWORD" \
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
   --data-binary "SELECT currentUser() FORMAT TabSeparated" \
-  "${MEMHOUSE_URL:-http://localhost:8123}/" | tr -d '\r\n')"
-# rooms: messages_$MEM_ME, sessions_$MEM_ME, tool_calls_$MEM_ME
+  "$MEMHOUSE_URL/?readonly=1"
+# prints e.g. alice  →  your rooms are messages_alice, sessions_alice, tool_calls_alice
 ```
 
+**Keep the SQL heredoc quoted (`<<'SQL'`) and put the real name in the text.** This used to
+say "substitute it into every table name below" and show `messages_$MEM_ME`, 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 and the room name written
+out, 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.
 
-**Read the rollup with `join_use_nulls=1`.** The connection recipe above sets it. Without
-it, ClickHouse gives an unmatched `m.seq` a default instead of NULL, so a session with no
-messages reports `total_msgs = 1` rather than 0 — measured, not theoretical. A subquery
-has no `SETTINGS` clause of its own, so the setting has to come from the caller.
+**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. `final=1` on the connection still matters for reads of the rooms THEMSELVES,
+which carry no FINAL of their own.
 
 If you hold `SELECT` on them, `all_messages` / `all_sessions` / `all_tool_calls` read
 across every member at once, narrowed to whatever grants you actually have — a Merge room

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

@@ -0,0 +1,177 @@
+---
+name: sessions
+description: List recent agent sessions from memhouse conversation memory — names, projects, editors, hosts, times, message and token counts across all 17 supported editors. Use for "what was I working on", "show my recent sessions", "sessions from last week", "what did I do in project X", "list my cursor sessions", or to orient before drilling into one session.
+user-invocable: true
+argument-hint: "[N] [project <name>] [from <editor>] [today|week|month]"
+allowed-tools: Bash
+---
+
+# /memhouse: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 +
+message aggregates) in the memhouse house.
+
+## When to use
+
+- The user wants an overview of recent activity rather than a specific quote.
+- As a first step before digging into one session, when they don't have an
+  id/name yet.
+
+## 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:-mem}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+## Room names — always suffixed
+
+Every member owns their own rooms, named for their ClickHouse user:
+`messages_<you>`, `sessions_<you>`, `tool_calls_<you>`. There are no unsuffixed rooms;
+the bare names fail with `UNKNOWN_TABLE` rather than returning nothing. You hold no grant
+on anyone else's rooms, so isolation is not something a query can work around.
+
+Ask the server your name once, then **type the literal room name into your SQL** — do not
+reference a shell variable inside the query:
+
+```bash
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary "SELECT currentUser() FORMAT TabSeparated" \
+  "$MEMHOUSE_URL/?readonly=1"
+# prints e.g. alice  →  your rooms are messages_alice, sessions_alice, tool_calls_alice
+```
+
+**Keep the SQL heredoc quoted (`<<'SQL'`) and put the real name in the text.** This used to
+say "substitute it into every table name below" and show `messages_$MEM_ME`, 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 and the room name written
+out, 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_<you>` for metadata
+and `messages_<you>` for counts, each read `FINAL`, joined on `session_id` and `user_id`.
+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.
+
+If you hold `SELECT` on them, `all_messages` / `all_sessions` / `all_tool_calls` read
+across every member at once, narrowed to whatever grants you actually have — a Merge room
+reduces to the rooms the caller can read, so it fails closed rather than denying outright.
+
+## Default listing
+
+```sql
+SELECT session_id, name, source, host, project,
+       started, ended, total_msgs, user_msgs, assistant_msgs,
+       output_tokens,
+       substring(first_prompt, 1, 80) AS first_prompt
+FROM (the rollup from `memhouse sessions-query`)
+ORDER BY ended DESC
+LIMIT 20
+FORMAT PrettyCompact
+```
+
+- Default `LIMIT 20`; `[N]` overrides.
+- `today` / `week` / `month` → `WHERE ended > now() - INTERVAL 1 DAY`
+  (`7 DAY` / `30 DAY`).
+- `project <name>` → `WHERE project ILIKE '%<name>%'`.
+- `from <editor>` → `WHERE source = '<id>'` (`claude-code`, `codex`, `cursor`,
+  `vscode`, `zed`, `opencode`, `gemini-cli`, `windsurf`, …).
+- Unnamed sessions (`name = ''`): fall back to `first_prompt` as the label.
+
+## More cuts
+
+Per-editor rollup ("where has my work been happening?"):
+
+```sql
+SELECT source, count() AS sessions, sum(total_msgs) AS msgs,
+       sum(output_tokens) AS out_tokens, max(ended) AS last_activity
+FROM (the rollup from `memhouse sessions-query`)
+GROUP BY source
+ORDER BY sessions DESC
+FORMAT PrettyCompact
+```
+
+Busiest projects this month:
+
+```sql
+SELECT project, count() AS sessions, sum(assistant_msgs) AS assistant_msgs
+FROM (the rollup from `memhouse sessions-query`)
+WHERE ended > now() - INTERVAL 30 DAY AND project != ''
+GROUP BY project
+ORDER BY sessions DESC
+LIMIT 15
+FORMAT PrettyCompact
+```
+
+## Examples
+
+| User says | What you do |
+|---|---|
+| "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 |
+
+## 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_<you> WHERE session_id = '…' ORDER BY seq`) or to
+run /memhouse:search for a specific quote.

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

@@ -0,0 +1,206 @@
+---
+name: sql
+description: Run free-form read-only SQL against memhouse conversation memory (typed sessions/messages/tool_calls rooms on ClickHouse, one set per member). 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.
+user-invocable: true
+argument-hint: "<question or SQL>"
+allowed-tools: Bash
+---
+
+# /memhouse:sql — ad-hoc analytics
+
+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.
+
+**Read-only rule:** the shipper (`ship.js`) is the only writer. Never INSERT/ALTER/DROP
+from here. A member credential holds `SELECT, INSERT, ALTER UPDATE, ALTER DELETE, ALTER ADD
+COLUMN, OPTIMIZE` on its **own three rooms** — enough to destroy the rows, though not
+the rooms — and nothing at all on anyone else's. Reads need no scoping
+clause: the rooms you can name are already only yours, and there is no policy to work
+around.
+
+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:-mem}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+`FORMAT PrettyCompact` for display, `FORMAT JSONEachRow` to parse.
+
+## Room names — always suffixed
+
+Every member owns their own rooms, named for their ClickHouse user:
+`messages_<you>`, `sessions_<you>`, `tool_calls_<you>`. There are no unsuffixed rooms;
+the bare names fail with `UNKNOWN_TABLE` rather than returning nothing. You hold no grant
+on anyone else's rooms, so isolation is not something a query can work around.
+
+Ask the server your name once, then **type the literal room name into your SQL** — do not
+reference a shell variable inside the query:
+
+```bash
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary "SELECT currentUser() FORMAT TabSeparated" \
+  "$MEMHOUSE_URL/?readonly=1"
+# prints e.g. alice  →  your rooms are messages_alice, sessions_alice, tool_calls_alice
+```
+
+**Keep the SQL heredoc quoted (`<<'SQL'`) and put the real name in the text.** This used to
+say "substitute it into every table name below" and show `messages_$MEM_ME`, 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 and the room name written
+out, 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_<you>` for metadata
+and `messages_<you>` for counts, each read `FINAL`, joined on `session_id` and `user_id`.
+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.
+
+If you hold `SELECT` on them, `all_messages` / `all_sessions` / `all_tool_calls` read
+across every member at once, narrowed to whatever grants you actually have — a Merge room
+reduces to the rooms the caller can read, so it fails closed rather than denying outright.
+
+## Schema (the house)
+
+| Object | Kind | Columns |
+|---|---|---|
+| `sessions_<you>` | table, 1 row/session | `session_id, source, host, name, mode, folder, project, git_branch, created_at, last_updated_at, message_count, path, extra JSON, user_id, ingested_at` |
+| `messages_<you>` | table, 1 row/message | `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, user_id, ingested_at` + FTS columns `text_ngram`/`text_word` (lowercased; see /memhouse:search) |
+| `tool_calls_<you>` | table, 1 row/tool call | `session_id, seq, idx, source, host, tool_name, args, ts, project, folder, user_id, ingested_at` |
+| 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()`);
+`models` in the rollup is an `Array(String)`. Exclude `''` and
+`'<synthetic>'` from model aggregates.
+
+## Examples
+
+Token spend by model:
+
+```sql
+SELECT model, sum(input_tokens) AS in_tok, sum(output_tokens) AS out_tok,
+       sum(cache_read_tokens) AS cache_read
+FROM messages_<you>
+WHERE model NOT IN ('', '<synthetic>')
+GROUP BY model
+ORDER BY out_tok DESC
+FORMAT PrettyCompact
+```
+
+Which tools do I use most (memhouse exclusive — memory-house has no tool table):
+
+```sql
+SELECT tool_name, count() AS calls, uniqExact(session_id) AS sessions
+FROM tool_calls_<you>
+GROUP BY tool_name
+ORDER BY calls DESC
+LIMIT 20
+FORMAT PrettyCompact
+```
+
+Busiest days, last two weeks:
+
+```sql
+SELECT toDate(ts) AS day, uniqExact(session_id) AS sessions, count() AS msgs
+FROM messages_<you>
+WHERE ts > now() - INTERVAL 14 DAY
+GROUP BY day
+ORDER BY day DESC
+FORMAT PrettyCompact
+```
+
+Activity by editor this week / subagent share:
+
+```sql
+SELECT source, count() AS msgs, countIf(is_subagent) AS subagent_msgs
+FROM messages_<you>
+WHERE ts > now() - INTERVAL 7 DAY
+GROUP BY source
+ORDER BY msgs DESC
+FORMAT PrettyCompact
+```
+
+Longest sessions by wall-clock:
+
+```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
+```
+
+## Output
+
+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.

package/memhouse/host.js

@@ -0,0 +1,101 @@
+// Which machine shipped this row.
+//
+// All of one member's machines ship into that member's rooms — that is the point of the
+// per-member layout — and the `host` column is the only thing telling them apart. So the
+// value has to be BOTH unique per machine and stable across that machine's lifetime.
+//
+// It used to be derived, `sha256(hostname|platform|arch)`, and that fails in both
+// directions:
+//
+//   * Two machines collide. A pilot with two MacBooks that both answer to
+//     `MacBook-Pro` on the same darwin/arm64 produce the SAME id — their sessions merge
+//     into one apparent host and neither can be told from the other. Default hostnames
+//     are exactly the case where a person owns several.
+//   * One machine splits. Rename the box and every row shipped afterwards lands under a
+//     new host, so the machine's own history appears to end and a stranger's to begin.
+//
+// A random fingerprint, written once and kept, fixes both: nothing derives it, so nothing
+// can collide with it, and nothing about the machine changing can move it.
+//
+// It lives in MEMHOUSE_HOME and is deliberately NOT removed by a plain `memhouse
+// uninstall` — reinstalling on the same machine should continue that machine's history,
+// not start a second one beside it. `uninstall --full-removal` drops it, and then the
+// machine genuinely is a new host next time; that is the honest meaning of full removal.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const FILE = 'host.json';
+
+function homeDir() {
+  return process.env.MEMHOUSE_HOME || path.join(os.homedir(), '.memhouse');
+}
+
+function filePath(home = homeDir()) {
+  return path.join(home, FILE);
+}
+
+// `<short-hostname>-<8 hex>`: the same SHAPE the derived id had, so dashboards and
+// existing queries read the same, but the hex half now comes from the stored fingerprint
+// rather than from a hash of facts that can collide or change.
+function idFrom(hostname, fingerprint) {
+  const short = (hostname || 'host').split('.')[0].replace(/[^A-Za-z0-9_-]/g, '') || 'host';
+  return `${short}-${fingerprint.slice(0, 8)}`;
+}
+
+function read(home = homeDir()) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath(home), 'utf-8'));
+    if (raw && typeof raw.fingerprint === 'string' && raw.fingerprint.length >= 8) return raw;
+  } catch { /* absent or unreadable — treated as "not yet created" */ }
+  return null;
+}
+
+/**
+ * The identity of this machine, creating it on first use.
+ *
+ * Every entry point calls this rather than only `install`, because a checkout can ship
+ * without ever running install — and a shipper that could not name its host would either
+ * refuse to run or invent a different name each pass.
+ *
+ * @param {string} [home]
+ * @returns {{id: string, fingerprint: string, hostname: string, created: string,
+ *            renamed: boolean, platform: string, arch: string}}
+ */
+function identity(home = homeDir()) {
+  const hostname = os.hostname();
+  let rec = read(home);
+  if (!rec) {
+    rec = {
+      fingerprint: crypto.randomBytes(16).toString('hex'),
+      hostname,
+      platform: os.platform(),
+      arch: os.arch(),
+      // Stamped once. Never rewritten, so it says when this machine joined, not when the
+      // file was last touched.
+      created: new Date().toISOString(),
+    };
+    rec.id = idFrom(hostname, rec.fingerprint);
+    try {
+      fs.mkdirSync(home, { recursive: true });
+      // Written with the same 0600 the credential gets. It is not a secret, but it is an
+      // identity: anything that can read it can impersonate this host's rows.
+      fs.writeFileSync(filePath(home), JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 });
+    } catch { /* read-only home: fall through with an in-memory identity for this run */ }
+  }
+  // The id is frozen at creation, INCLUDING the hostname baked into it. A rename must not
+  // move the id — that is the split this exists to prevent — so the current hostname is
+  // reported alongside instead, and `renamed` lets callers say so out loud rather than
+  // printing a name the machine no longer answers to and leaving the reader to wonder.
+  return {
+    ...rec,
+    id: rec.id || idFrom(rec.hostname, rec.fingerprint),
+    hostname: rec.hostname,
+    current_hostname: hostname,
+    renamed: rec.hostname !== hostname,
+  };
+}
+
+module.exports = { identity, read, filePath, idFrom, FILE };