memhouse 0.18.12 → 0.20.1

package/examples/01-local-one-machine/README.md

@@ -40,40 +40,45 @@ alone.
 
 ## What you should see
 
-Trimmed from a run on a Linux VM with Docker, ClickHouse 26.7 and memhouse 0.18.9:
+Trimmed from a run on a lab host (Linux, Docker 29), ClickHouse 26.7 and memhouse
+0.20.0-dev.15, as root in a container, with `HOUSE_PORT=18129`:
 
 ```
 == 1. a house: ClickHouse in a container, bound to loopback, plus the install
-  ✓ ClickHouse starting via docker on http://localhost:8123 (loopback only)
+  ✓ ClickHouse starting via docker on http://localhost:18129 (loopback only)
   ✓ ClickHouse ready
-  ✓ member 'sam' holds mem.sam_* and nothing else; 'memhouse_root' administers the house
-  ✓ rooms for 'sam': sam_sessions, sam_messages, sam_tool_calls
+  ✓ member 'root' holds mem.root_* and nothing else; 'memhouse_root' administers the house
+  ✓ schema 3: mem.root_turns, mem.root_calls, mem.root_sessions, mem_archive.root_records, mem_archive.root_files; capture tables granted to 'root'
   ✓ installed
-  ✓ shipper started in the background (pid 617049) — loading your history now
+  ✓ shipper started in the background (pid 281) — loading your history now
 
 == 2. one shipping pass
-[memhouse] shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.7s
+[memhouse] v3 capture: 2/2 files changed in 2 sessions → 2 files rows, 10 archive rows (0.0 MiB), 10 turns, 2 calls, 0 tombstones, 2 sessions [new 2]
 
 == 3. what the house holds
-  ✓ connected: http://localhost:8123 / mem as sam
-  ✓ house: 2 sessions, 6 messages (freshest ingest 2026-10-07 21:08:06 UTC)
+  ✓ connected: http://localhost:18129 / mem as root
+  ✓ schema 3 — tables for 'root': mem.root_turns, mem.root_calls, mem.root_sessions
+  ✓ house: 2 sessions, 6 messages (freshest ingest 2026-10-22 15:34:18 UTC)
   ✓ fleet: 1 active writer(s)
-     sam@linux-vm-1f2e3d4c        0.18.9   last ship 0m ago
-  ✓ shipper: running — daemon (pid 617049)
+  ✓ shipper: running — daemon (pid 281)
 
 == 4. find a past conversation
-claude-code:421460e4-5e66-4c1c-afa4-f1b198c28c25  claude-code  alpha  2026-10-07 19:07  (1 hit)
-  The deploy fails with ClickHouse error ACCESS_DENIED on INSERT. Why?
+claude-code:f7204114-477a-4fcc-8bd0-353ed6426ae8~WyJy…  alpha  2026-10-22 13:34  (1 hit · The deploy fails with ClickHouse error ACCESS_DENIED on INSE)
+  user u1: The deploy fails with ClickHouse error ACCESS_DENIED on INSERT. Why?
+
+  read a hit with: memhouse q window <ref> --at <message_id>
 ```
 
-Three messages per session in the house, not four: the tool result is folded into the
-tool call it answers.
+Ten turns for six messages: a turn is one part of a message (its text, a thinking
+block, a tool call or a tool result), and `memhouse status` counts messages. The ref
+in step 4 names the session's store after the `~`; `memhouse q session <ref>` reads it.
 
-To look around, start the dashboard in the example's home (pick another port if 4640 is
-taken by a real install):
+To look around, start the dashboard in the example's home, then open it (when 4640 is taken
+by a real install, the dashboard takes the next free port and says which):
 
 ```bash
-MEMHOUSE_HOME=~/.memhouse-example-01 MEMHOUSE_PORT=4641 memhouse start
+MEMHOUSE_HOME=~/.memhouse-example-01 memhouse start
+MEMHOUSE_HOME=~/.memhouse-example-01 memhouse dashboard
 ```
 
 ## Teardown
@@ -95,5 +100,5 @@ memhouse deploy --local
 ```
 
 Every editor memhouse knows is read (`memhouse discover` lists what it finds first). Then
-`memhouse start` for the dashboard and `memhouse plugins install claude` to give your agents
-`/mem:recall` and the other skills.
+`memhouse start` and `memhouse dashboard` for the dashboard, and `memhouse plugins install
+claude` to give your agents `/mem:recall` and the other skills.

package/examples/01-local-one-machine/run.sh

@@ -57,5 +57,5 @@ echo "== 4. find a past conversation"
 mh search ACCESS_DENIED
 
 echo
-echo "Done. Open the dashboard:  MEMHOUSE_HOME=$MEMHOUSE_HOME $MH start   (then http://localhost:4640)"
+echo "Done. Open the dashboard:  MEMHOUSE_HOME=$MEMHOUSE_HOME $MH start, then MEMHOUSE_HOME=$MEMHOUSE_HOME $MH dashboard"
 echo "Remove everything:        $0 --teardown"

package/examples/02-existing-clickhouse/README.md

@@ -10,12 +10,15 @@ and keeps only the member's credential on disk.
 1. `memhouse whoami --admin` checks that the admin credential really can create users and
    grant, before anything is changed.
 2. `memhouse install --admin-user …` creates the member (default: your login name), grants
-   it `mem.<member>_*` and nothing else, creates its rooms, and verifies the install by
-   connecting **as the member**. The admin credential is used for this one command and not
+   it `mem.<member>_*`, builds its schema-3 tables (the six conversation tables in `mem`,
+   `<member>_session_parts`, `_sessions` and four more, and its capture archive
+   `<member>_session_units` and `_session_sources` in `mem_archive`, granted to it and nothing
+   more), and verifies the install by connecting **as the
+   member**. The admin credential is used for this one command and not
    saved (add `--keep-admin` if this machine should be able to invite people later).
-3. `memhouse ship --ensure-schema` creates any room or stat table that is missing — safe to
-   re-run, and the thing to run after an upgrade that adds one — then `memhouse ship`
-   ships two made-up sessions.
+3. `memhouse ship --ensure-schema` checks the member's five tables, as the member, and
+   creates what it may — safe to re-run — then `memhouse ship` ships two made-up
+   sessions.
 4. `memhouse whoami` and `memhouse status` show the credential this machine now keeps and
    what the house holds.
 
@@ -66,31 +69,34 @@ printf '%s' "$PASSWORD" | memhouse install --url "$MEMHOUSE_URL" --admin-user de
 
 ## What you should see
 
-Trimmed from a run against ClickHouse 26.7.1.1315 with memhouse 0.18.9 (the test endpoint is shown as `ch.example.com`):
+Trimmed from a run against a lab ClickHouse 26.7.4.58 with memhouse 0.20.0-dev.15, member
+`ex02`:
 
 ```
 == 1. whoami --admin: is this credential really an administrator?
-  ✓ admin at https://ch.example.com:8443 — administrator
+  ✓ ex_admin at https://ch.example.com:8443 — administrator
   credential from: MEMHOUSE_ADMIN_* environment
   may create users:    yes
 
-== 2. install: build member 'sam' with the admin credential, then verify as the member
-  ✓ created ClickHouse user 'sam'
-  ✓ granted 'sam' mem.sam_* — their rooms and nothing else; async_insert pinned
-  ✓ verified as 'sam' with the member credential
+== 2. install: build member 'ex02' with the admin credential, then verify as the member
+  ✓ created ClickHouse user 'ex02'
+  ✓ granted 'ex02' mem.ex02_* — their tables (the capture archive is granted below); async_insert pinned
+  ✓ schema 3: mem.ex02_turns, mem.ex02_calls, mem.ex02_sessions, mem_archive.ex02_records, mem_archive.ex02_files; capture tables granted to 'ex02'
+  ✓ verified as 'ex02' with the member credential
   ✓ installed
   the admin credential was used for this install and not saved. To invite later:
-     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite <name> --url … --admin-user admin
+     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite <name> --url … --admin-user ex_admin
 
-== 3. make sure every room and stat table exists, then ship once
-[memhouse] schema ensured (5 statements)
-[memhouse] shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.2s
+== 3. make sure the member's tables exist, then ship once
+[memhouse] schema ensured (v3: mem.ex02_turns, mem.ex02_calls, mem.ex02_sessions, mem_archive.ex02_records, mem_archive.ex02_files)
+[memhouse] v3 capture: 2/2 files changed in 2 sessions → 2 files rows, 10 archive rows (0.0 MiB), 10 turns, 2 calls, 0 tombstones, 2 sessions [new 2]
 
 == 4. whoami: the credential this machine keeps, and what it may do
-  ✓ sam at https://ch.example.com:8443 — member
+  ✓ ex02 at https://ch.example.com:8443 — member
   may create users:    no
 
 == 5. status
+  ✓ schema 3 — tables for 'ex02': mem.ex02_turns, mem.ex02_calls, mem.ex02_sessions
   ✓ house: 2 sessions, 6 messages
   ✓ fleet: 1 active writer(s)
 ```
@@ -104,18 +110,20 @@ Step 2 generates the member password and writes it only to the home's `env` file
 ./run.sh --teardown
 ```
 
-Deletes the example's home. The member and its rooms stay in the house: dropping them is
+Deletes the example's home. The member and its tables stay in the house: dropping them is
 an administrator's decision. As the admin:
 
 ```sql
-DROP USER sam;
--- then each of mem.sam_sessions, _messages, _tool_calls, _meta, _events,
--- _session_stats, _session_model_stats, _session_tool_stats
+DROP USER ex02;
+-- then each of mem.ex02_session_parts, _session_usage, _session_links, _session_lifecycle,
+-- _calls, _sessions, _meta, _events, and mem_archive.ex02_session_units, _session_sources
+-- (docs/guides/operate.md, "Removing a member's tables", lists them by exact name)
 ```
 
 ## For real
 
 Leave out the two fixture flags (`--editors claude --claude-roots …`) and the
 `EXAMPLE_HOME`, and every editor on the machine ships into the house. Your other machines
-join the same rooms by installing with the same member credential (`memhouse install --url
-… --user <member> --password …`, or an invite file — see [03](../03-team-house/)).
+join the same tables by installing with the same member credential (`memhouse install --url
+… --user <member>` with the password in `MEMHOUSE_PASSWORD` or `--password-file`, or an
+invite file — see [03](../03-team-house/)).

package/examples/02-existing-clickhouse/run.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Example 02 — point memhouse at a ClickHouse you already run.
 #
-# The admin credential builds a member account (rooms mem.<member>_*, one grant on exactly
-# those), the install is verified AS that member, and the admin credential is then dropped:
+# The admin credential builds a member account (its tables mem.<member>_* and its capture
+# archive in mem_archive, grants on exactly those), the install is verified AS that member,
+# and the admin credential is then dropped:
 # what stays on disk is the member's. The admin password never touches the command line.
 #
 #   with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- ./run.sh
@@ -25,7 +26,7 @@ export MEMHOUSE_HOME=${EXAMPLE_HOME:-$HOME/.memhouse-example-02}
 if [ "${1:-}" = "--teardown" ]; then
   mh stop || true
   rm -rf "$MEMHOUSE_HOME"
-  echo "example 02 home removed. The member and its rooms stay in the house; dropping them is an admin's call."
+  echo "example 02 home removed. The member and its tables stay in the house; dropping them is an admin's call."
   exit 0
 fi
 
@@ -56,7 +57,7 @@ mh install --url "$MEMHOUSE_URL" --admin-user "$MEMHOUSE_ADMIN_USER" --member "$
 unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
 
 echo
-echo "== 3. make sure every room and stat table exists, then ship once"
+echo "== 3. make sure the member's tables exist, then ship once"
 # --ensure-schema only creates what is missing, as the member, and ships nothing; it is
 # safe to re-run, and the thing to run after an upgrade that adds a table.
 mh ship --ensure-schema

package/examples/03-team-house/README.md

@@ -7,14 +7,16 @@ exactly who can see what. Finally she withdraws both shares.
 
 ## The model in four lines
 
-- Every member owns `mem.<member>_*`: five rooms (sessions, messages, tool_calls, meta,
-  events) and three stat tables. One grant on that pattern is their whole access.
-- Housemates cannot read, list, or touch each other's rooms.
-- A **full share** (`memhouse share bob`) grants `SELECT ON mem.alice_*`: every room,
-  every project, every machine, and anything ever pasted into a session.
-- A **scoped share** (`memhouse share carol --only project=alpha`) grants the three
-  transcript rooms only, each behind a row policy. The stat tables, meta and events are
-  not shared at all, because they carry no per-session filter.
+- Every member owns `mem.<member>_*` (`session_parts`, `session_usage`, `session_links`,
+  `session_lifecycle`, `calls`, `sessions`, `meta`, `events`) and two tables in the capture
+  archive, `mem_archive.<member>_session_units` and `_session_sources`. Those grants are their
+  whole access.
+- Housemates cannot read, list, or touch each other's tables.
+- A **full share** (`memhouse share bob`) grants `SELECT` on exactly alice's six
+  conversation tables: every session, every project, every machine, and anything ever pasted
+  into one. Not the archive, not `meta` or `events`.
+- A **scoped share** (`memhouse share carol --only project=alpha`) grants the same six
+  tables, each behind a row policy, written before the grant.
 
 ## What it does
 
@@ -31,7 +33,7 @@ exactly who can see what. Finally she withdraws both shares.
 5. alice: `memhouse share bob --revoke`, `memhouse share carol --revoke`; the reads are
    denied again.
 
-At exit the script drops the three users and their rooms (`KEEP=1` keeps them).
+At exit the script drops the three users and their tables (`KEEP=1` keeps them).
 
 ## Needs
 
@@ -65,11 +67,11 @@ wrong, because their `localhost` is their own machine.
 | `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD` | (required) | the administrator |
 | `MEMHOUSE_BIN` | `memhouse` | the command to run |
 | `EXAMPLE_DIR` | a new temp dir | where the three homes live |
-| `KEEP` | `0` | `1` keeps the members and their rooms |
+| `KEEP` | `0` | `1` keeps the members and their tables |
 
 ## What you should see
 
-From a run against ClickHouse 26.7.1.1315, memhouse 0.18.9 (temp paths shortened):
+From a run against a lab ClickHouse 26.7.4.58, memhouse 0.20.0-dev.15 (temp paths shortened):
 
 ```
 == 1. the admin invites three members
@@ -81,38 +83,43 @@ From a run against ClickHouse 26.7.1.1315, memhouse 0.18.9 (temp paths shortened
   alice:   ✓ installed
   alice:   ✓ password rotated — this credential is now yours alone
   alice:   ✓ removed the spent invite file …/alice.env
-  alice: [memhouse] shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.3s
+  alice: [memhouse] v3 capture: 2/2 files changed in 2 sessions → 2 files rows, 10 archive rows (0.0 MiB), 10 turns, 2 calls, 0 tombstones, 2 sessions [new 2]
   (bob and carol the same)
 
 == 3. alice shares: everything with bob, project alpha only with carol
-  ✓ 'bob' can now read every session in your rooms (mem.alice_*)
-  ✓ 'carol' can read your rooms in 'mem' where project=alpha
-  who can read your rooms in 'mem' — memhouse's own record, not ClickHouse's grant table:
-    bob              granted 2026-10-07  (all your rooms)
-    carol            granted 2026-10-07 scope=project=alpha
-      alice_messages project = 'alpha'
+  ✓ 'bob' can now read every session in mem.alice_turns, mem.alice_calls, mem.alice_sessions
+  Those three tables only: not the capture archive, not meta or events.
+  ✓ 'carol' can read your sessions where project=alpha
+  turns     5 of 10 rows
+  calls     1 of 2 rows
+  sessions  1 of 2 rows
+  who can read your sessions in 'mem' — memhouse's own record, not ClickHouse's grant table:
+    bob              granted 2026-10-22  (every session: turns, calls, sessions)
+    carol            granted 2026-10-22 scope=project=alpha
+      alice_calls project = 'alpha'
       alice_sessions project = 'alpha'
-      alice_tool_calls project = 'alpha'
+      alice_turns project = 'alpha'
 
 == 4. who reads what — each with their own credential
-  alice, her own messages by project           alpha,beta 6
-  bob (full share), alice's messages           alpha,beta 6
-  carol (alpha only), alice's messages         alpha 3
-  bob, alice's session_stats                   2 rows
-  carol, alice's session_stats                 denied
-  carol, alice's meta                          denied
-  carol, bob's messages (never shared)         denied
+  alice, her own turns by project              alpha,beta 10
+  bob (full share), alice's turns              alpha,beta 10
+  carol (alpha only), alice's turns            alpha 5
+  bob, alice's meta                            denied
+  bob, alice's capture archive                 denied
+  carol, alice's sessions (alpha only)         1
+  carol, bob's turns (never shared)            denied
 
 == 5. alice withdraws both shares
-  ✓ revoked 'bob' — SELECT withdrawn and 3 row policies dropped
-  ✓ revoked 'carol' — SELECT withdrawn and 3 row policies dropped
-  bob, alice's messages                        denied
-  carol, alice's messages                      denied
-removed alice, bob, carol, their rooms and their homes
+  ✓ revoked 'bob' — SELECT withdrawn from mem.alice_turns, mem.alice_calls, mem.alice_sessions and its row policies dropped
+  ✓ revoked 'carol' — SELECT withdrawn from mem.alice_turns, mem.alice_calls, mem.alice_sessions and its row policies dropped
+  bob, alice's turns                           denied
+  carol, alice's turns                         denied
+removed alice, bob, carol, their tables and their homes
 ```
 
-The revoke line for bob counts the three policy drops memhouse attempts on every revoke;
-a full share has no policies, so none existed to drop.
+On a house still on the 0.18 rooms the same script's reads would fail: they name the
+schema-3 tables. An invite follows the house's layout, so a team house made with 0.20 is
+schema 3 throughout.
 
 ## For real
 
@@ -123,7 +130,7 @@ a full share has no policies, so none existed to drop.
 - **Each member** runs `memhouse install --env <name>.env` on their laptop, without the
   fixture flags, then `memhouse start` (or `memhouse service install`) to keep shipping.
 - **Sharing** is the member's own decision and needs no admin: `memhouse share <user>`,
-  `--only project=<p>` (also `session=`, `host=`, `source=`, `folder=`, `since=`,
-  `until=`), `--revoke`, `--list`.
-- A grantee reads the shared rooms with their own credential: `/mem:recall` and the other
-  agent skills, or SQL against `mem.<owner>_messages`.
+  `--only project=<p>` (also `session=`, `host=`, `harness=`, `folder=`, `since=`,
+  `until=`), `--revoke`, `--list`. See [Share and revoke](../../docs/guides/share.md).
+- A grantee reads the shared tables with their own credential: `/mem:sql`, or SQL against
+  `mem.<owner>_session_parts` and `mem.<owner>_sessions FINAL`.

package/examples/03-team-house/run.sh

@@ -11,7 +11,7 @@
 # if users named alice, bob or carol already exist.
 #
 #   with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- ./run.sh
-#   KEEP=1 ...  keep the three members and their rooms afterwards (default: removed)
+#   KEEP=1 ...  keep the three members and their tables afterwards (default: removed)
 #
 # Environment:
 #   MEMHOUSE_URL              required  the house's HTTP endpoint, as the members will reach it
@@ -46,28 +46,41 @@ as() {
     | curl -sS -K - --data-binary "$sql" "$URL/" 2>&1 | head -1
 }
 denied() { case "$1" in *ACCESS_DENIED*|*"Not enough privileges"*) return 0;; *) return 1;; esac; }
+# A "denied" means something only for a table that exists: a query on a missing table is refused
+# too (UNKNOWN_TABLE, or ACCESS_DENIED on a server that checks grants first), and would read as
+# a share that holds. So every table a check reads is first proved to exist, as the admin.
+need() {
+  local db=${1%%.*} t=${1#*.} n
+  n=$(admin_q "SELECT count() FROM system.tables WHERE database = '$db' AND name = '$t' FORMAT TSV")
+  [ "$n" = "1" ] || { echo "MISSING TABLE $1: this check would read a refusal as a closed door. Nothing it says can be trusted; stopping." >&2; exit 1; }
+}
+# What a user gets from one table: the result, or "denied".
+reads() { local r; r=$(as "$1" "SELECT count() FROM $2 FORMAT TSV"); if denied "$r"; then echo denied; else echo "$r rows"; fi; }
+# One line of the table below. `need` runs here, in the script's own shell, so a missing table
+# stops the script (inside $(…) its exit would end only the subshell).
+show_reads() { need "$3"; show "$1" "$(reads "$2" "$3")"; }
 
 cleanup() {
-  [ "${KEEP:-0}" = "1" ] && { echo "KEEP=1: members and rooms left in place; homes in $WORK"; return; }
+  [ "${KEEP:-0}" = "1" ] && { echo "KEEP=1: members and tables left in place; homes in $WORK"; return; }
   [ "${CREATED:-0}" = "1" ] || return 0
   for p in $PEOPLE; do
     admin_q "DROP USER IF EXISTS $p" >/dev/null 2>&1 || true
-    for t in $(admin_q "SELECT name FROM system.tables WHERE database = 'mem' AND startsWith(name, '${p}_') FORMAT TSV" 2>/dev/null); do
-      admin_q "DROP TABLE IF EXISTS mem.$t SYNC" >/dev/null 2>&1 || true
+    for t in $(admin_q "SELECT database || '.' || name FROM system.tables WHERE database IN ('mem', 'mem_archive') AND startsWith(name, '${p}_') FORMAT TSV" 2>/dev/null); do
+      admin_q "DROP TABLE IF EXISTS $t SYNC" >/dev/null 2>&1 || true
     done
   done
   rm -rf "$WORK"
-  echo "removed alice, bob, carol, their rooms and their homes"
+  echo "removed alice, bob, carol, their tables and their homes"
 }
 trap cleanup EXIT
 
-# Refuse anything this run did not make: the users, and any table under their room prefixes
-# (orphaned rooms can outlive their users). The cleanup below drops by those prefixes, so it
+# Refuse anything this run did not make: the users, and any table under their prefixes
+# (orphaned tables can outlive their users). The cleanup below drops by those prefixes, so it
 # may only run when this check proved them empty first.
 existing=$(admin_q "SELECT count() FROM system.users WHERE name IN ('alice','bob','carol') FORMAT TSV")
 [ "$existing" = "0" ] || { echo "refusing: users alice/bob/carol already exist on this server — use a throwaway ClickHouse"; exit 1; }
-rooms=$(admin_q "SELECT count() FROM system.tables WHERE database = 'mem' AND (startsWith(name, 'alice_') OR startsWith(name, 'bob_') OR startsWith(name, 'carol_')) FORMAT TSV")
-[ "$rooms" = "0" ] || { echo "refusing: mem.alice_*/bob_*/carol_* tables already exist ($rooms) — use a throwaway ClickHouse"; exit 1; }
+tables=$(admin_q "SELECT count() FROM system.tables WHERE database IN ('mem', 'mem_archive') AND (startsWith(name, 'alice_') OR startsWith(name, 'bob_') OR startsWith(name, 'carol_')) FORMAT TSV")
+[ "$tables" = "0" ] || { echo "refusing: alice_*/bob_*/carol_* tables already exist ($tables) — use a throwaway ClickHouse"; exit 1; }
 CREATED=1
 
 # A loopback URL is right only through a tunnel; invite refuses one unless told so.
@@ -107,18 +120,22 @@ mh share --list
 echo
 echo "== 4. who reads what — each with their own credential"
 show() { printf '  %-44s %s\n' "$1" "$2"; }
-show "alice, her own messages by project"   "$(as alice "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.alice_messages FORMAT TSV")"
-show "bob (full share), alice's messages"   "$(as bob   "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.alice_messages FORMAT TSV")"
-show "carol (alpha only), alice's messages" "$(as carol "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.alice_messages FORMAT TSV")"
-r=$(as bob "SELECT count() FROM mem.alice_session_stats FORMAT TSV");   show "bob, alice's session_stats"   "$(denied "$r" && echo denied || echo "$r rows")"
-r=$(as carol "SELECT count() FROM mem.alice_session_stats FORMAT TSV"); show "carol, alice's session_stats" "$(denied "$r" && echo denied || echo "$r rows")"
-r=$(as carol "SELECT count() FROM mem.alice_meta FORMAT TSV");          show "carol, alice's meta"          "$(denied "$r" && echo denied || echo "$r rows")"
-r=$(as carol "SELECT count() FROM mem.bob_messages FORMAT TSV");        show "carol, bob's messages (never shared)" "$(denied "$r" && echo denied || echo "$r rows")"
+parts() { as "$1" "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.$2_session_parts FINAL WHERE removed = 0 FORMAT TSV"; }
+need mem.alice_session_parts
+show "alice, her own message parts by project"   "$(parts alice alice)"
+show "bob (full share), alice's message parts"   "$(parts bob alice)"
+show "carol (alpha only), alice's message parts" "$(parts carol alice)"
+# A share is SELECT on exactly alice's six conversation tables: full or scoped, nothing else.
+show_reads "bob, alice's meta"                         bob mem.alice_meta
+show_reads "bob, alice's capture archive"              bob mem_archive.alice_session_units
+need mem.alice_sessions
+show "carol, alice's sessions (alpha only)"      "$(as carol "SELECT count() FROM mem.alice_sessions FINAL FORMAT TSV")"
+show_reads "carol, bob's message parts (never shared)" carol mem.bob_session_parts
 
 echo
 echo "== 5. alice withdraws both shares"
 mh share bob --revoke --yes
 mh share carol --revoke --yes
-r=$(as bob "SELECT count() FROM mem.alice_messages FORMAT TSV");   show "bob, alice's messages"   "$(denied "$r" && echo denied || echo "$r rows")"
-r=$(as carol "SELECT count() FROM mem.alice_messages FORMAT TSV"); show "carol, alice's messages" "$(denied "$r" && echo denied || echo "$r rows")"
+show_reads "bob, alice's message parts"   bob mem.alice_session_parts
+show_reads "carol, alice's message parts" carol mem.alice_session_parts
 unset MEMHOUSE_HOME

package/examples/04-self-hosted-team/README.md

@@ -15,7 +15,7 @@ with members shipping from their own laptops. One compose file holds all of it.
 |---|---|---|
 | `clickhouse` | `clickhouse/clickhouse-server:26.7.1.1315` | the house. No published port; reachable only through Caddy. |
 | `caddy` | `caddy:2.10` | TLS on 443: a Let's Encrypt certificate for your domain, or Caddy's own CA. Port 80 answers the ACME challenge and redirects. |
-| `backup` | the ClickHouse image | at `BACKUP_AT` (UTC) writes the house **and its accounts** to the `backups` volume; keeps the newest `BACKUP_KEEP` (14). |
+| `backup` | the ClickHouse image | at `BACKUP_AT` (UTC) writes the house, its capture archive **and its accounts** to the `backups` volume; keeps the newest `BACKUP_KEEP` (14). |
 
 ClickHouse is configured inline (`configs:` in [compose.yml](compose.yml)): the `backups`
 disk, and `users_without_row_policies_can_read_rows` set explicitly to `true`, which
@@ -81,7 +81,7 @@ memhouse plugins install claude            # /mem:recall and the other agent ski
 ```
 
 `memhouse service status` shows the unit; `memhouse status` shows freshness and every
-machine writing to her rooms. Without a service, `memhouse start` runs the shipper and the
+machine writing to her tables. Without a service, `memhouse start` runs the shipper and the
 dashboard as background processes until logout.
 
 ## Smoke test
@@ -89,11 +89,12 @@ dashboard as background processes until logout.
 `./smoke.sh` brings the stack up with `.env`, then, through the proxy only: checks the
 certificate, that the `default` user is gone, invites a member `smoke`, installs it from
 the invite file, ships two made-up sessions, reads them back as the member, backs up and
-restores the member's messages, and checks the nightly job. At exit it drops `smoke` and
-its rooms (`KEEP=1` keeps them). `SKIP_UP=1` tests a stack that is already running; see
+restores the member's message parts and archive units, and checks the nightly job. At exit it drops `smoke` and
+its tables (`KEEP=1` keeps them). `SKIP_UP=1` tests a stack that is already running; see
 the top of the script.
 
-From a run with `MEMHOUSE_TLS=internal` on a Linux VM with Docker:
+From a run with `MEMHOUSE_TLS=internal` on a lab host (Linux, Docker 29, Compose 5.3),
+memhouse 0.20.0-dev.15:
 
 ```
 smoke test against https://localhost:18443
@@ -102,28 +103,36 @@ smoke test against https://localhost:18443
   ok    admin reaches ClickHouse 26.7.1.1315
   ok    admin invited member 'smoke'
   ok    the member installed from the invite file, over https
-  ok    shipped: shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.6s
-  ok    the member reads its 6 messages back through the proxy
+  ok    shipped: v3 capture: 2/2 files changed in 2 sessions → 2 files rows, 10 archive rows (0.0 MiB), 10 turns, 2 calls, 0 tombstones, 2 sessions [new 2]
+  ok    the member reads its 2 sessions back through the proxy
   ok    the member cannot create tables outside mem.smoke_*
   ok    BACKUP to the backups disk
   ok    RESTORE from it
-  ok    the restored copy holds the same 6 rows
-  ok    the backup service has written a nightly backup since the server started
+  ok    the restored copy holds the same 10 turns
+  info  no nightly backup yet this server lifetime (BACKUP_ON_START=1 runs one at start)
 
-12 passed, 0 failed
+11 passed, 0 failed
 ```
 
+The nightly job was then run at once (`BACKUP_ON_START=1 docker compose up -d
+--force-recreate backup`): `backup written: mem-2026-10-22-15_38.zip`, and `mem_archive`
+restored from that file under another name held the member's 10 capture records, as
+the live one did.
+
 ## Backups and restore
 
 Every night the `backup` service runs
 
 ```sql
-BACKUP DATABASE mem, TABLE system.users, TABLE system.roles, TABLE system.row_policies,
+BACKUP DATABASE mem, DATABASE mem_archive,
+       TABLE system.users, TABLE system.roles, TABLE system.row_policies,
        TABLE system.settings_profiles, TABLE system.quotas
 TO Disk('backups', 'mem-YYYY-MM-DD-HH_MM.zip')
 ```
 
-and deletes all but the newest `BACKUP_KEEP`. The accounts are in the same file on
+and deletes all but the newest `BACKUP_KEEP`. `mem_archive` is the capture archive of a
+0.20 house: every transcript byte as captured, which the sessions in `mem` are derived
+from. It is left out while it does not exist (a house on the 0.18 rooms). The accounts are in the same file on
 purpose: users, their password hashes, their grants and the row policies of scoped shares
 live outside the database, and a restored house without them is one nobody can log in to.
 `docker compose logs backup` shows each run.
@@ -149,11 +158,14 @@ docker compose exec clickhouse chown clickhouse:clickhouse /backups/mem-2026-10-
 then, as the admin:
 
 ```sql
-RESTORE DATABASE mem, TABLE system.users, TABLE system.roles, TABLE system.row_policies,
+RESTORE DATABASE mem, DATABASE mem_archive,
+        TABLE system.users, TABLE system.roles, TABLE system.row_policies,
         TABLE system.settings_profiles, TABLE system.quotas
 FROM Disk('backups', 'mem-2026-10-07-21_17.zip')
 ```
 
+(Leave out `DATABASE mem_archive` for a file written before the house had one.)
+
 Members come back with their own passwords and grants, so their machines keep shipping
 once the DNS name points at the new server. Restoring accounts fails if a user of the same
 name already exists, which is why this is a restore onto a fresh stack. To look inside a
@@ -161,9 +173,12 @@ backup without touching the live house, restore just the data under another name
 `RESTORE DATABASE mem AS mem_check FROM Disk('backups', '<file>')`, then
 `DROP DATABASE mem_check`.
 
-Tested on ClickHouse 26.7.1.1315: a nightly file copied off the server with the command
+Tested on ClickHouse 26.7.1.1315 with memhouse 0.18.9 (no archive yet): a nightly file copied off the server with the command
 above, a fresh stack (`down -v`, `up`), the copy put back and restored — the data came
 back, and the member logged in with its original password.
+With 0.20 the archive's part was checked on its own: `mem_archive` restored from a nightly
+file under another name held the same records as the live one. The full fresh-stack
+restore has not been repeated on 0.20.
 
 ## Upgrading ClickHouse
 

package/examples/04-self-hosted-team/compose.yml

@@ -122,7 +122,8 @@ configs:
     content: |
       #!/bin/bash
       # Nightly backup at BACKUP_AT (UTC), keeping the newest BACKUP_KEEP. One file holds
-      # the house AND the accounts: users, their grants and the row policies of scoped
+      # the house, its capture archive (<db>_archive, schema 3: every transcript byte as
+      # captured) AND the accounts: users, their grants and the row policies of scoped
       # shares live outside the database, and a restore without them is a house nobody
       # can log in to. README.md has the restore.
       set -uo pipefail
@@ -133,8 +134,10 @@ configs:
           return
         fi
         name="$$MEMHOUSE_DB-$$(date -u +%Y-%m-%d-%H_%M).zip"
+        DBS="DATABASE $$MEMHOUSE_DB"
+        [ "$$(clickhouse-client --host clickhouse --query "EXISTS DATABASE $${MEMHOUSE_DB}_archive")" = "1" ] && DBS="$$DBS, DATABASE $${MEMHOUSE_DB}_archive"
         if clickhouse-client --host clickhouse --query \
-             "BACKUP DATABASE $$MEMHOUSE_DB, $$ACCESS TO Disk('backups', '$$name')" >/dev/null; then
+             "BACKUP $$DBS, $$ACCESS TO Disk('backups', '$$name')" >/dev/null; then
           echo "$$(date -u +%FT%TZ) backup written: $$name"
         else
           echo "$$(date -u +%FT%TZ) backup FAILED: $$name" >&2