memhouse 0.3.1 → 0.4.2

package/mem-house/delivery/kernel-install.md

@@ -2,14 +2,23 @@
 
 How to run mem-house as an **agency** on an ultimagent kernel — a ClickHouse server
 (a **town**) promoted into a realm — instead of a plain ClickHouse. Same flow proven
-for the agentlytics agency (`agency/AGENCY.md`); the agency/house name here is
-**`memhouse`** (CH identifiers can't carry a dash). What lands is a **house** (the
-`memhouse` database) with a **resident** (the shipper — `kind = "worker"`,
-`on = "loop"`) — that pairing is the agency. Residents write; routines read, and the
-`sessions_v` view is a routine. Terms: `../../TERMINOLOGY.md`.
+for the agentlytics agency (`agency/AGENCY.md`); the agency is named **`memhouse`** and
+its house is the **`mem`** database (CH identifiers can't carry a dash, and the owning
+role kept the longer name — `memhouse_root`). What lands is a **house** (the `mem`
+database) with a **resident** (the shipper — `kind = "worker"`, `on = "loop"`) — that
+pairing is the agency. Residents write; routines read, and the session rollup is a
+routine. Terms: `../../TERMINOLOGY.md`.
+
+**One set of rooms per member.** Each member owns `sessions_<them>`, `messages_<them>`,
+`tool_calls_<them>` and holds grants on those and nothing else, so isolation is an
+absent grant rather than a row policy — it fails closed. There is no shared
+`sessions`/`messages`/`tool_calls` layout and no row policy in the default path; 0.4.0
+removed both. Team-wide reads are the `Merge` rooms plus a `GRANT`. The session rollup
+is a **saved query**, not a stored view — `memhouse sessions-query` prints it.
+Design and measurements: `../per-member/`.
 
 This is an operator runbook, so it speaks machine vocabulary throughout — ClickHouse,
-`GRANT`, row policies. That is correct for this audience.
+`GRANT`, `currentUser()`. That is correct for this audience.
 
 ## 1. Provision (operator, one-time — from the kernel checkout)
 
@@ -17,8 +26,8 @@ This is an operator runbook, so it speaks machine vocabulary throughout — Clic
 python3 executor/executor.py provision memhouse
 ```
 
-Submits `install-agency{name:'memhouse'}`; the mayor — the human owner — approves;
-the executor (running as the ego, the `kernel` user) creates database `memhouse`
+Submits `install-agency{name:'memhouse'}`; the human owner approves; the executor
+(running as the realm's privileged user) creates database `mem`
 (the house), owner `memhouse_root`
 (`realm_user` profile), and owner grants. It returns a one-time **credential** —
 rotate on first connect (`issue-credential{user:'memhouse_root'}`).
@@ -31,7 +40,7 @@ memhouse install --yes \
   --url https://<kernel-host>:8443 \
   --user memhouse_root \
   --password <credential-from-provision> \
-  --db memhouse
+  --db mem
 ```
 
 That writes `~/.memhouse/env`, applies the schema, and runs the first ship.
@@ -50,34 +59,56 @@ injection surface). It is the only thing here that writes without being asked.
 For each person joining, split across the two authorities:
 
 ```bash
-# The EGO (the `kernel` user) mints the identity; the mayor approves:
+# The realm's privileged user mints the identity; the human owner approves:
 python3 executor/executor.py submit register-member '{"handle":"alice"}'
 python3 executor/executor.py approve <call_id> && python3 executor/executor.py drain
 
-# OWNER grants house access (memhouse_root has grant-option on memhouse.*):
-#   GRANT INSERT, SELECT ON memhouse.* TO alice
+# OWNER mints that member's three rooms and their grants (memhouse_root has
+# grant-option on mem.*). One idempotent step — see ../per-member/PROVISIONING.md:
+MEM_URL=https://<kernel-host>:8443 MEM_USER=memhouse_root \
+MEM_PASSWORD=<credential> MEM_DB=mem \
+  node mem-house/per-member/provision.js --member alice --merge
 ```
 
+**Never `GRANT … ON mem.*` to a member.** A member who can read `mem.*` can read every
+other member's rooms, and then this is a shared house with longer table names.
+`provision.js` grants per room: `ALL` on each of alice's three, plus a re-grantable
+`SELECT` on each (that split is what makes a share read-only by construction), plus
+`SELECT` on the `Merge` rooms.
+
 Each member then runs the shipper with **their own** credential
-(`MEMHOUSE_USER=alice`) — the house stamps `user_id='alice'` on their rows,
-un-spoofably (`MATERIALIZED currentUser()`, `async_insert=0`).
+(`MEMHOUSE_USER=alice`) — it writes to `sessions_alice` / `messages_alice` /
+`tool_calls_alice`, resolved from `SELECT currentUser()` rather than from config, and
+the house stamps `user_id='alice'` on their rows, un-spoofably
+(`MATERIALIZED currentUser()`, `async_insert=0`).
+
+## 4. Visibility
+
+**Own-only is the default and needs no policy.** Alice is granted her own three rooms
+and nobody else's, so bob's rooms are not hidden from her — they are simply not hers to
+read, and the failure mode of a missing grant is a denial rather than a leak.
 
-## 4. Visibility: own-only vs team pool
+**Team-wide reads are the `Merge` rooms** (`all_sessions`, `all_messages`,
+`all_tool_calls`) plus a `GRANT SELECT` on them, which `provision.js --merge` issues. A
+`Merge` room narrows to whatever underlying rooms the caller already holds grants for —
+measured on 26.7.1: no leak, no error — so it can be granted broadly. It also
+auto-discovers rooms created after it, so onboarding a member needs no DDL there.
 
-- **Own-only** (memory-house's model — each member sees only their own rows): the
-  **ego (the `kernel` user) or the mayor** applies `mem-house/rls.sql` (three row
-  policies bound to the `member` role). The owner cannot — `CREATE ROW POLICY` needs
-  ACCESS MANAGEMENT, which the kernel withholds from agency owners by design.
-- **Team pool** (everyone sees everything): apply no policy; the owner GRANTs from
-  step 3 are the whole model.
+A member widens what a colleague sees by granting their own rooms directly
+(`GRANT SELECT ON mem.messages_alice TO bob`) — self-serve, no operator, because the
+member holds grant-option on their own `SELECT`. See `../per-member/SHARING.md`.
 
-Pick one; do not mix on the same role.
+Row policies are still the only way to share a *subset* of rows, which is owner-mediated
+and documented in `SHARING.md` — they are not how isolation works.
 
 ## 5. Verify
 
 ```bash
 memhouse stats                              # per-source counts as the owner
-# as a member (own-only): counts reflect only that member's rows
-curl -s -u "alice:<pw>" "$MEMHOUSE_URL/?database=memhouse" \
-  --data-binary "SELECT count() FROM sessions_v SETTINGS final=1"
+# as a member: the rollup resolves to alice's own rooms, so counts are hers alone
+curl -s -u "alice:<pw>" "$MEMHOUSE_URL/?database=mem" \
+  --data-binary "SELECT count() FROM $(memhouse sessions-query) AS c SETTINGS final=1, join_use_nulls=1"
+# and the team room narrows rather than denying — alice sees herself plus whoever granted her
+curl -s -u "alice:<pw>" "$MEMHOUSE_URL/?database=mem" \
+  --data-binary "SELECT user_id, count() FROM all_messages GROUP BY user_id SETTINGS final=1"
 ```

package/mem-house/delivery/skills/memhouse-search/SKILL.md

@@ -8,20 +8,21 @@ allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
 
 # memhouse-search — search conversation memory
 
-Search the full message history in the memhouse house (`messages` + `sessions`
-tables on ClickHouse).
+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` (ReplacingMergeTree keeps
-stale row versions until merges; `final=1` collapses to latest-wins — always
+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:-memhouse}&final=1" <<'SQL'
+  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-mem}&final=1&join_use_nulls=1" <<'SQL'
 <the query>
 FORMAT PrettyCompact
 SQL
@@ -30,9 +31,38 @@ SQL
 `FORMAT PrettyCompact` for display; `FORMAT JSONEachRow` when you want to parse
 the rows yourself.
 
+## 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.
+
+Resolve your own name once and substitute it into every table name below:
+
+```bash
+MEM_ME="$(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
+```
+
+**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.
+
+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.
+
 ## How to search (the FTS columns)
 
-`messages` carries two MATERIALIZED lowercase copies of `text`, each with a
+`messages_<you>` carries two MATERIALIZED lowercase copies of `text`, each with a
 text index — search those, display `text`:
 
 - `text_ngram` (ngram index) → substring match: `text_ngram LIKE '%term%'`
@@ -48,8 +78,8 @@ phrase → one `LIKE` clause for the whole phrase.
 SELECT m.ts, m.source, m.project, m.role, m.session_id,
        s.name AS session,
        substring(m.text, 1, 300) AS snippet
-FROM messages AS m
-LEFT JOIN sessions AS s USING (session_id)
+FROM messages_<you> AS m
+LEFT JOIN sessions_<you> AS s USING (session_id)
 WHERE m.text_ngram LIKE '%postgres%' AND m.text_ngram LIKE '%migration%'
 ORDER BY m.ts DESC
 LIMIT 30
@@ -60,7 +90,7 @@ FORMAT PrettyCompact
 
 ```sql
 SELECT ts, project, session_id, substring(text, 1, 200) AS snippet
-FROM messages
+FROM messages_<you>
 WHERE hasToken(text_word, 'rls')
   AND source = 'claude-code'
   AND ts > now() - INTERVAL 14 DAY
@@ -74,8 +104,8 @@ FORMAT PrettyCompact
 ```sql
 SELECT m.session_id, any(s.name) AS session, any(m.project) AS project,
        count() AS hits, max(m.ts) AS last_hit
-FROM messages AS m
-LEFT JOIN sessions AS s USING (session_id)
+FROM messages_<you> AS m
+LEFT JOIN sessions_<you> AS s USING (session_id)
 WHERE m.text_ngram LIKE '%clickhouse cache%'
 GROUP BY m.session_id
 ORDER BY hits DESC
@@ -91,14 +121,14 @@ FORMAT PrettyCompact
   `cursor`, `cursor-agent`, `vscode`, `zed`, `opencode`, `gemini-cli`,
   `windsurf`, `antigravity`, `copilot-cli`, `goose`, `kiro`, …)
 - Skip subagent noise → `AND NOT m.is_subagent`
-- Only user/assistant text lives in `messages`; tool invocations are in
-  `tool_calls` (`tool_name`, `args`) — search `args ILIKE '%term%'` there only
-  if the user explicitly wants tool calls searched.
+- Only user/assistant text lives in `messages_<you>`; tool invocations are in
+  `tool_calls_<you>` (`tool_name`, `args`) — search `args ILIKE '%term%'` there
+  only if the user explicitly wants tool calls searched.
 
 ## Output
 
 Summarize hits grouped by session (name, source, project, date, 1–2 best
 snippets each) and give the total hit count. Offer to pull the full transcript
-of the best session (`SELECT role, text FROM messages WHERE session_id = '…'
+of the best session (`SELECT role, text FROM messages_<you> WHERE session_id = '…'
 ORDER BY seq`). If zero hits, retry with broader/fewer terms and report the
-corpus size (`SELECT count() FROM messages`).
+corpus size (`SELECT count() FROM messages_<you>`).

package/mem-house/delivery/skills/memhouse-sessions/SKILL.md

@@ -8,7 +8,8 @@ allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
 
 # memhouse-sessions — browse session history
 
-List/filter sessions from the `sessions_v` rollup view (session metadata +
+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
@@ -20,17 +21,47 @@ message aggregates) in the memhouse house.
 ## Connection
 
 Credentials from `~/.memhouse/env` (or exported `MEMHOUSE_*`). Always read with
-`final=1` (collapses ReplacingMergeTree duplicates to latest-wins):
+`final=1` (collapses ReplacingMergeTree duplicates to latest-wins) and
+`join_use_nulls=1` (see below — the session rollup needs it):
 
 ```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:-memhouse}&final=1" <<'SQL'
+  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-mem}&final=1&join_use_nulls=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.
+
+Resolve your own name once and substitute it into every table name below:
+
+```bash
+MEM_ME="$(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
+```
+
+**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.
+
+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
@@ -38,7 +69,7 @@ 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 sessions_v
+FROM (the rollup from `memhouse sessions-query`)
 ORDER BY ended DESC
 LIMIT 20
 FORMAT PrettyCompact
@@ -59,7 +90,7 @@ 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 sessions_v
+FROM (the rollup from `memhouse sessions-query`)
 GROUP BY source
 ORDER BY sessions DESC
 FORMAT PrettyCompact
@@ -69,7 +100,7 @@ Busiest projects this month:
 
 ```sql
 SELECT project, count() AS sessions, sum(assistant_msgs) AS assistant_msgs
-FROM sessions_v
+FROM (the rollup from `memhouse sessions-query`)
 WHERE ended > now() - INTERVAL 30 DAY AND project != ''
 GROUP BY project
 ORDER BY sessions DESC
@@ -90,5 +121,5 @@ FORMAT PrettyCompact
 
 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
+(`SELECT role, text FROM messages_<you> WHERE session_id = '…' ORDER BY seq`) or to
 run memhouse-search for a specific quote.

package/mem-house/delivery/skills/memhouse-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memhouse-sql
-description: Run free-form read-only SQL against memhouse conversation memory (typed sessions/messages/tool_calls tables + the sessions_v view on ClickHouse). 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.
+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(set -a*), Bash(. *), Bash(curl*)
@@ -11,21 +11,23 @@ allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
 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 — member credentials typically hold only
-`INSERT, SELECT ON memhouse.*`, and on shared instances own-only row policies
-scope reads to your rows.
+**Read-only rule:** the shipper (`ship.js`) is the only writer. Never INSERT/ALTER/DROP
+from here. A member credential normally holds `ALL` on its **own three rooms** — enough
+to destroy that memory — 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.
 
 ## Connection
 
 Credentials from `~/.memhouse/env` (or exported `MEMHOUSE_*`). Always read with
 `final=1` — every table is `ReplacingMergeTree(ingested_at)`, so without it you
-can double-count stale row versions:
+can double-count stale row versions — and `join_use_nulls=1`, which the session
+rollup depends on (see below):
 
 ```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:-memhouse}&final=1" <<'SQL'
+  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-mem}&final=1&join_use_nulls=1" <<'SQL'
 <the query>
 FORMAT PrettyCompact
 SQL
@@ -33,20 +35,49 @@ 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.
+
+Resolve your own name once and substitute it into every table name below:
+
+```bash
+MEM_ME="$(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
+```
+
+**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.
+
+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` | 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` | 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` | table, 1 row/tool call | `session_id, seq, idx, source, host, tool_name, args, ts, project, folder, user_id, ingested_at` |
-| `sessions_v` | view, rollup | `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` |
+| `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 `sessions_v` is an `Array(String)`. Exclude `''` and
+`models` in the rollup is an `Array(String)`. Exclude `''` and
 `'<synthetic>'` from model aggregates.
 
 ## Examples
@@ -56,7 +87,7 @@ 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
+FROM messages_<you>
 WHERE model NOT IN ('', '<synthetic>')
 GROUP BY model
 ORDER BY out_tok DESC
@@ -67,7 +98,7 @@ 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
+FROM tool_calls_<you>
 GROUP BY tool_name
 ORDER BY calls DESC
 LIMIT 20
@@ -78,7 +109,7 @@ Busiest days, last two weeks:
 
 ```sql
 SELECT toDate(ts) AS day, uniqExact(session_id) AS sessions, count() AS msgs
-FROM messages
+FROM messages_<you>
 WHERE ts > now() - INTERVAL 14 DAY
 GROUP BY day
 ORDER BY day DESC
@@ -89,7 +120,7 @@ Activity by editor this week / subagent share:
 
 ```sql
 SELECT source, count() AS msgs, countIf(is_subagent) AS subagent_msgs
-FROM messages
+FROM messages_<you>
 WHERE ts > now() - INTERVAL 7 DAY
 GROUP BY source
 ORDER BY msgs DESC
@@ -100,7 +131,7 @@ Longest sessions by wall-clock:
 
 ```sql
 SELECT name, project, source, duration_sec, total_msgs, output_tokens
-FROM sessions_v
+FROM (the rollup from `memhouse sessions-query`)
 ORDER BY duration_sec DESC
 LIMIT 10
 FORMAT PrettyCompact