memhouse 0.18.12 → 0.20.1

package/docs/guides/operate.md

@@ -26,8 +26,18 @@ GROUP BY table;
 
 -- what someone may do
 SHOW GRANTS FOR alice;
+
+-- every scoped share's filter, and any left behind on a table that is gone
+SELECT database, short_name, table, select_filter, apply_to_list,
+       (database, table) NOT IN (SELECT database, name FROM system.tables) AS table_gone
+FROM system.row_policies
+ORDER BY database, table;
 ```
 
+A policy whose table is gone is dropped with `DROP ROW POLICY <short_name> ON <db>.<table>`:
+dropping a table leaves its policies, and a table later made under the same name inherits them.
+Members do not hold `SHOW ROW POLICIES`, so this listing is the admin's.
+
 ## Adding and removing people
 
 - **Add:** [`memhouse invite`](invite.md).
@@ -35,8 +45,57 @@ SHOW GRANTS FOR alice;
   member who is locked out there is no verb: run `ALTER USER <name> IDENTIFIED BY '…'` as
   the admin, and hand them an env file with the new password. Every machine shipping as
   them stops until its env file has it.
-- **Remove:** there is no verb yet. `DROP USER <name>` stops every machine shipping as
-  that member. Their rooms remain until you drop them as well.
+- **Remove:** there is no verb yet. Follow [Removing a member](#removing-a-member): their
+  shares first, then `DROP USER <name>`, which stops every machine shipping as them, then their
+  tables, in **both** databases.
+
+### Removing a member
+
+In this order. Each step is irreversible, and the last one deletes the member's memory.
+
+1. **Their shares.** Run as the member, while the account still exists:
+   `memhouse share <reader> --revoke` for each reader `memhouse share --list` names. A share's
+   grants and row policies are kept by name, and neither is dropped with the tables: one left
+   behind reaches, or filters, a later table of the same name. If the member cannot run it, find
+   both as the admin (the list below is every table name the member can have), and remove each
+   with `REVOKE … ON <db>.<table> FROM <reader>` and `DROP ROW POLICY <name> ON <db>.<table>`:
+
+   ```sql
+   WITH ['alice_session_parts', 'alice_session_usage', 'alice_session_links',
+         'alice_session_lifecycle', 'alice_calls', 'alice_sessions', 'alice_meta', 'alice_events',
+         'alice_session_stats', 'alice_session_model_stats', 'alice_session_tool_stats',
+         'alice_messages', 'alice_tool_calls', 'alice_turns',
+         'alice_session_units', 'alice_session_sources', 'alice_records', 'alice_files',
+         'alice_messages_pre_v3', 'alice_tool_calls_pre_v3', 'alice_sessions_pre_v3'] AS mine
+   SELECT 'grant' AS kind, user_name AS who, access_type AS what, database, table FROM system.grants
+   WHERE database IN ('mem', 'mem_archive') AND has(mine, table) AND user_name != 'alice'
+   UNION ALL
+   SELECT 'policy', short_name, '', database, table FROM system.row_policies
+   WHERE database IN ('mem', 'mem_archive') AND has(mine, table);
+   ```
+
+   A 0.18 full share is a wildcard grant, `mem.alice_*`: `SHOW GRANTS FOR <reader>` shows it.
+2. **The user:** `DROP USER alice`. Every machine shipping as them stops.
+3. **Their tables.** List them **by exact name**, never by prefix: `LIKE 'alice_%'` also matches
+   another member called `alice_smith`. The same list as above:
+
+   ```sql
+   WITH [ … the same names … ] AS mine
+   SELECT database, name, total_rows FROM system.tables
+   WHERE database IN ('mem', 'mem_archive') AND has(mine, name) ORDER BY database, name;
+   ```
+
+   Then drop each by its full name (`DROP TABLE mem.alice_session_parts`, …). Which of them
+   exist depends on the member's history:
+   - **on schema 3:** the six conversation tables in `mem`, plus `_meta` and `_events` once
+     the member has run `memhouse share` (step 1 does), and `_session_units` and
+     `_session_sources` in `mem_archive`;
+   - **from a 0.20 development build:** also `_turns` in `mem`, and `_records` and `_files` in
+     `mem_archive`;
+   - **converted from 0.18:** also `_meta`, `_events` and the three stats tables in `mem`, and
+     the three renamed rooms (`*_pre_v3`) in `mem_archive`;
+   - **still on the 0.18 rooms:** `_messages`, `_tool_calls`, `_sessions`, `_meta`, `_events` and
+     the stats tables, all in `mem`.
 
 **Before any destructive statement, look first.**
 
@@ -85,10 +144,58 @@ Afterwards, point each member at the new URL with `memhouse setup --url …`.
 
 ## Backups
 
-memhouse does not back up the house. Use ClickHouse's own `BACKUP DATABASE mem TO …`, to a
-disk or an object store, on a schedule, and test a `RESTORE` into a scratch server.
-[`examples/04-self-hosted-team`](../../examples/04-self-hosted-team/README.md) shows a nightly job,
-rotation, and a tested restore.
+memhouse does not back up the house. Use ClickHouse's own `BACKUP`, to a disk or an object
+store, on a schedule. **A schema-3 house is two databases:** `mem`, and `mem_archive`, the
+capture archive every session is derived from. A backup of `mem` alone leaves the archive out.
+The accounts (users, their grants, the row policies of scoped shares) live outside both, so
+take them in the same statement:
+
+```sql
+BACKUP DATABASE mem, DATABASE mem_archive,
+       TABLE system.users, TABLE system.roles, TABLE system.row_policies,
+       TABLE system.settings_profiles, TABLE system.quotas
+TO File('mem-2026-10-27.zip')
+```
+
+`File(…)` works on a stock server: the official image's configuration allows backups under
+`backups/` in the server's data directory (`/var/lib/clickhouse/backups/` in the image), and
+that is where the file lands. It is on the server's own disk, so copy it somewhere else. With a
+backups disk configured, write `TO Disk('backups', '…')` instead; a stock server refuses
+`Disk(…)` ("the 'backups.allowed_disk' configuration parameter is not set").
+[`examples/04-self-hosted-team`](../../examples/04-self-hosted-team/README.md) shows such a
+disk, with a nightly job, rotation, and a restore onto a fresh server. A house still on the
+0.18 rooms has no `mem_archive` until its upgrade begins: leave `DATABASE mem_archive` out until
+then.
+
+**Check a backup** without touching the live house: restore its two databases under other names,
+compare, and drop the copies.
+
+```sql
+RESTORE DATABASE mem AS mem_check, DATABASE mem_archive AS mem_archive_check
+FROM File('mem-2026-10-27.zip');
+
+-- every table on both sides
+SELECT database, count() FROM system.tables
+WHERE database IN ('mem', 'mem_check', 'mem_archive', 'mem_archive_check') GROUP BY database;
+
+-- rows per table, live against restored
+SELECT replaceRegexpOne(database, '_check$', '') AS db, table,
+       sumIf(rows, NOT endsWith(database, '_check')) AS live,
+       sumIf(rows, endsWith(database, '_check')) AS restored
+FROM system.parts
+WHERE active AND database IN ('mem', 'mem_check', 'mem_archive', 'mem_archive_check')
+GROUP BY db, table ORDER BY db, table;
+
+DROP DATABASE mem_check;
+DROP DATABASE mem_archive_check;
+```
+
+Each database and its `_check` copy should hold the same number of tables, and `restored` should
+be close to `live` on every table (the house may have grown since the backup). No
+`mem_archive_check` in the first result, or a table with no `restored` rows where `live` has
+many, means the backup does not hold what you think. For a house still on the 0.18 rooms, leave
+`DATABASE mem_archive AS mem_archive_check` out of the `RESTORE` too. These statements were
+checked on ClickHouse 26.7.
 
 - **Keep backups as private as the house.** They hold every member's transcripts.
 - **Backups outlive deletions.** A row removed from the house remains in every backup
@@ -98,7 +205,7 @@ rotation, and a tested restore.
 
 | setting | why |
 |---|---|
-| async inserts off for members | `user_id` is stamped at insert; memhouse pins `async_insert=0` on each member, and the shipper sets it per insert too |
+| async inserts off for members | the writing user is stamped at insert (`writer` on schema 3, `user_id` on the 0.18 rooms); memhouse pins `async_insert=0` on each member, and the shipper sets it per insert too |
 | `users_without_row_policies_can_read_rows` | scoped shares need it to behave as memhouse expects; `share` measures it and refuses if a policy would blind the owner |
 | `old_parts_lifetime` | how long replaced parts stay on disk after merges and mutations (480 s by default) |
 | HTTP behind TLS | members connect over HTTP(S); put the server behind TLS before exposing it beyond a LAN |

package/docs/guides/search-and-resume.md

@@ -10,6 +10,26 @@ memhouse search clickhouse auth --limit 50
 This is a full-text search across every session in your rooms, from every machine and
 every editor. Each hit names the session id, project, date and the matching line.
 
+### On schema 3: the named queries
+
+A house on schema 3 (every new house from 0.20) also answers named queries, the same ones the
+`/mem` skills use:
+
+```bash
+memhouse q                       # the list, with each one's usage
+memhouse q recent --limit 20     # the latest sessions
+memhouse q search clickhouse auth
+memhouse q session <ref>         # one session, page by page
+memhouse q spend --by model      # tokens and cost
+memhouse q removed               # what is kept as removed versions
+```
+
+- **A session's ref names its store,** `<harness>:<session_id>~<token>`, because the same id
+  on another machine, or in another data folder, is another session. `q recent` and
+  `q search` print full refs; a bare id still works where only one session has it.
+- **`q removed`** lists what every other read hides: a message an editor reverted, rewound
+  or deleted, kept as a removed version. Narrow it with a ref, `--harness` or `--days`.
+
 ## Resume
 
 ```bash
@@ -35,7 +55,7 @@ memhouse stats              # sessions, messages and tokens per editor
 memhouse sessions-query     # the per-session rollup as SQL, to paste into your own queries
 ```
 
-The dashboard (`memhouse start`, then http://localhost:4640) shows the same and more:
+The dashboard (`memhouse start`, then `memhouse dashboard`) shows the same and more:
 
 - cost by model, editor and project;
 - tool-call rankings;
@@ -55,6 +75,11 @@ memhouse plugins list
 memhouse plugins remove claude
 ```
 
+Each copy is bound to the install that put it there, and kept at that install's version: after
+an upgrade, by `memhouse update` or by `npm install -g`, the first `memhouse` command (or the
+shipper's restart) replaces it with the new version's skills. `memhouse doctor` names any copy
+it could not refresh.
+
 The five skills:
 
 | skill | for |
@@ -74,11 +99,55 @@ missing skill never announces itself.
 For an agent that does not use Claude Code skills, `memhouse prompt` prints a snippet for
 its system prompt: where memory lives and how to query it.
 
+### Codex
+
+The `/mem` skills are for Claude Code. For Codex:
+
+```bash
+memhouse plugins install codex      # under CODEX_HOME, or ~/.codex
+memhouse plugins list               # shows the codex copy and the command it runs
+memhouse plugins remove codex
+```
+
+It writes two things, and only when you run it:
+
+- **A block at the top of `AGENTS.md`**, between `<!-- memhouse:begin … -->` and
+  `<!-- memhouse:end -->`. Codex puts this file in every prompt, so the block holds only what must
+  always hold: never read or print `~/.memhouse/env` or a `MEMHOUSE_*` value; `MEMHOUSE_URL` is the
+  house and `MEMHOUSE_PORT` the dashboard; questions about past sessions go to the `memhouse`
+  skill. The file is created if it is missing. Installing again replaces the block where it
+  stands. Removing takes out the block and the blank line after it, so the rest of the file is
+  what it was, byte for byte; a file that held only the block is deleted, or, when `AGENTS.md`
+  is a symlink, its target is emptied and the link kept. Leave the markers
+  alone: with one of them missing, install and remove refuse and change nothing.
+- **A skill, `skills/memhouse/`**, with the read recipes: `memhouse q`, `--member` for a
+  housemate's sessions, `memhouse room-sql`. Codex lists it by name and description and reads
+  the rest when it uses it. The directory carries `.memhouse.json`; a `skills/memhouse` without
+  it is someone else's, and install refuses to replace it and remove leaves it.
+
+For an instance with its own home or binary, both name it: `MEMHOUSE_HOME=<home> <binary> q …`.
+After an upgrade, the first `memhouse` command refreshes both, as it does the `/mem` copies; a
+block you took out by hand stays out.
+
 ## Writing your own queries
 
-The rooms are documented column by column in
+On schema 3 (0.20), the tables are `mem.<you>_session_parts` (one row per part of a message:
+text, thinking, a tool call or its result), `mem.<you>_session_usage` (one row per usage
+record), `mem.<you>_calls` and `mem.<you>_sessions` (one row per session, with its totals),
+with `_session_links` and `_session_lifecycle` beside them. Their columns are described in
+[`memhouse/house/schema-profile.sql.tpl`](../../memhouse/house/schema-profile.sql.tpl). Three rules:
+
+1. **Read with `FINAL`, and keep `is_deleted = 0 AND removed = 0`.** Removed content is
+   kept as removed versions (`memhouse q removed` lists them); it is not current.
+2. **A session is its store:** `(host, harness, harness_path, session_id, incarnation)`.
+   A bare `session_id` can repeat across editors and machines.
+3. **Count a session's messages as its text parts (`kind = 'text'`), as `sessions.messages`
+   does, and take its totals from `sessions`.** A forked session's copied prefix is billed once, in `sessions`;
+   summing the parts or the usage rows of a fork and its parent counts that prefix twice.
+
+On the 0.18 rooms, the rooms are documented column by column in
 [`memhouse/house/HOUSE.md`](../../memhouse/house/HOUSE.md). Two rules matter for every
-query:
+query there:
 
 1. **Join on `(session_id, user_id)`**, never on `session_id` alone. Two members' editors
    can produce the same local session id.

package/docs/guides/share.md

@@ -1,29 +1,32 @@
 # Share and revoke
 
-A share lets another member of the same server read your rooms. It is a ClickHouse
+A share lets another member of the same server read your sessions. It is a ClickHouse
 `GRANT SELECT`, so it is read-only, and you can withdraw it. Run these on a machine
-installed as yourself. Each command acts on your own rooms only.
+installed as yourself. Each command acts on your own tables only.
 
 ```bash
-memhouse share bob                          # full: everything in mem.<you>_*
-memhouse share bob --only project=billing   # scoped: three rooms, filtered
+memhouse share bob                          # full: every session
+memhouse share bob --only project=billing   # scoped: the sessions that match
 memhouse share --list                       # what memhouse has recorded
 memhouse share bob --revoke                 # take it back
 ```
 
-## Full or scoped
+This page describes a 0.20 house (schema 3). For a house still on the 0.18 rooms, see
+[the last section](#a-house-on-the-018-rooms).
+
+## What a share reaches
+
+Full or scoped, a share is `SELECT` on exactly your six conversation tables:
+`<you>_session_parts`, `<you>_session_usage`, `<you>_session_links`, `<you>_session_lifecycle`,
+`<you>_calls` and `<you>_sessions`. Never a wildcard, never the database.
 
 | | full (`share bob`) | scoped (`share bob --only …`) |
 |---|---|---|
-| grant | `SELECT ON mem.<you>_*` | `SELECT` on `<you>_sessions`, `<you>_messages`, `<you>_tool_calls` |
-| rows | all | those matching the scope, through row policies |
-| stats tables (`<you>_session_stats`, model and tool stats) | readable: first prompts, folders, projects and tokens of every session | not granted |
-| `<you>_meta`, `<you>_events` | readable, including your other share records | not granted |
-| rooms created later | readable | not granted |
-
-**A full share is for someone you would hand your laptop to.** It reaches every table in
-your pattern, including ones memhouse adds in a later release. The command says so when
-you run it.
+| grant | `SELECT` on the six tables | `SELECT` on the six tables |
+| rows | all | those matching the scope, through a row policy on each table |
+| capture archive (`<db>_archive`) | not granted | not granted |
+| `<you>_meta`, `<you>_events` | not granted | not granted |
+| tables added later | not granted | not granted |
 
 ## Scopes
 
@@ -31,31 +34,20 @@ you run it.
 
 | key | filters on |
 |---|---|
-| `project=` | the project name |
-| `folder=` | the working directory |
-| `session=` | one session id |
-| `host=` | one machine (its fingerprint, as `status` shows it) |
-| `source=` | one editor, by the value stored in the `source` column (below) |
-| `since=` / `until=` | a date range: message time, or session creation time for `sessions` |
-
-`source=` compares against the stored value, which is not always the adapter name you
+| `project=` | the project name. Only message parts, calls and sessions carry one: a project scope passes no usage, link or lifecycle rows, and the `sessions` row carries the totals |
+| `folder=` | the working directory, on the same three tables as `project=` |
+| `session=` | one session: a ref with its store (`<harness>:<id>~…`, as `memhouse q recent` prints it), or a bare id, which matches that id in every store |
+| `host=` | one machine, by its id (`memhouse doctor` lists it under "host identity") |
+| `harness=` | one editor, by the stored value (below); `source=` means the same |
+| `since=` / `until=` | a date range: the row's own time for message parts, usage, calls and lifecycle records, the start for `sessions`. A row with no time, and every link, never matches |
+
+`harness=` compares against the stored value, which is not always the adapter name you
 use in `MEMHOUSE_EDITORS`. Claude Code rows, for example, say `claude-code`, not `claude`.
-The values:
+To see what your tables hold:
 
-| editor | `source` |
-|---|---|
-| Claude Code | `claude-code` |
-| Codex | `codex` |
-| Cursor / Cursor Agent | `cursor` / `cursor-agent` |
-| VS Code / VS Code Insiders | `vscode` / `vscode-insiders` |
-| GitHub Copilot / Copilot for JetBrains | `copilot-cli` / `copilot-jetbrains` |
-| Gemini CLI | `gemini-cli` |
-| Zed, OpenCode, Goose, Kiro, Codebuff, Antigravity | `zed`, `opencode`, `goose`, `kiro`, `codebuff`, `antigravity` |
-| Devin / Devin Next | `devin` / `devin-next` |
-| Command Code | `commandcode` |
-
-To see what your rooms actually hold:
-`SELECT source, count() FROM mem.<you>_sessions FINAL GROUP BY source`.
+```sql
+SELECT harness, count() FROM mem.<you>_sessions FINAL GROUP BY harness
+```
 
 An empty scope (`--only ""`, or `--only "$SCOPE"` with the variable unset) is refused.
 It never falls back to a full share.
@@ -68,35 +60,82 @@ your full-share grantees. Before it creates the first policy, `share` measures h
 server behaves, and refuses if a policy would blind you. The fix is server configuration
 (`users_without_row_policies_can_read_rows`), and it is the administrator's to make.
 
+## The order, and what a failure leaves
+
+- **Scoped:** the row policies are written first, then the grants. If a policy cannot be
+  written, nothing is granted.
+- **Full:** the grants first, then any leftover policies are dropped. Until they are
+  dropped they only narrow.
+- **A reader who still holds your 0.18 share** (`<you>_*`, from before the conversion): a
+  new share refuses, because it would sit beside that grant and narrow nothing. So does a
+  share when what the reader holds cannot be read. Revoke first, or, for a full share memhouse
+  recorded, the admin moves it with `migrate --v3-shares`. In a house where member names
+  collide, a revoke may leave the grant and `--v3-shares` refuses: see
+  [Troubleshooting](troubleshooting.md#two-member-names-that-collide).
+- If a grant fails part-way, memhouse withdraws what it granted. If it cannot confirm that,
+  the filters stay, and it tells you to retry or revoke.
+
 ## Changing a share
 
 - **Scoped to full:** `memhouse share bob`.
-- **Full to scoped:** `memhouse share bob --only …`. The wildcard grant is withdrawn
-  first, so a failure part-way leaves bob with less access, never more.
+- **Full to scoped:** `memhouse share bob --only …`. The filters are written first, so
+  bob's view narrows before anything else changes.
 - **One scope to another:** run `--only` again with the new scope. It replaces the
   policies.
 
-**Scoped shares made before 0.18.10** granted the whole pattern while filtering only three
-rooms. Re-run `memhouse share <user> --only <scope>` once for each, and it is narrowed to
-the three rooms.
-
 ## Revoking
 
-`--revoke` withdraws the grants (the wildcard and the three rooms), then drops the row
-policies. If the server refuses a step, the policies are kept unless every grant is
-confirmed gone, so a failed revoke never leaves an unfiltered share behind.
+`--revoke` withdraws the grants on the six tables and on your 0.18 rooms, then drops the
+row policies. If the server refuses a step, the policies are kept, so a failed revoke never
+leaves an unfiltered share behind.
+
+A 0.18 wildcard grant the reader still holds (`<you>_*`) is taken back too, unless it also
+matches another member's tables (see [Troubleshooting](troubleshooting.md#two-member-names-that-collide))
+or a table memhouse did not make for you. A REVOKE on the wildcard would strip the reader's
+grants on those too, so the revoke leaves it for the admin and says so. It does the same when
+the reader's grants cannot be read, or the house's tables or users cannot be listed. The admin then
+takes it back by hand: the share is recorded as revoked, and `migrate --v3-shares` refuses a
+revoked share that still holds a grant.
 
 A revoke cannot recall what was already read.
 
 ## What `--list` shows
 
-`share --list` reads memhouse's own record, the `share:` keys in `<you>_meta`. A grant
-someone made by hand in SQL does not appear there. A member cannot read `system.grants`;
-an administrator can, with `SHOW GRANTS FOR <user>`.
+`share --list` reads memhouse's own record, the `share:` keys in `<you>_meta`, a share's scope
+included. A grant someone made by hand in SQL does not appear there. A member cannot read
+`system.grants` or `system.row_policies`; an administrator can, with `SHOW GRANTS FOR <user>`
+and the queries in [Operate](operate.md#who-is-here).
+
+It also lists the other direction: each member whose sessions your credential can read, with
+the command that reads them. A scoped share shows only the rows its owner chose, and its filter
+is the owner's to see.
 
 ## Reading what was shared with you
 
-Shared rooms sit in the same database as yours, under the other member's name, for
-example `mem.alice_messages`. Query them with `/mem:sql` or any ClickHouse client, joining
-on `(session_id, user_id)` as you would on your own rooms. A table you were not granted is
+Shared tables sit in the same database as yours, under the other member's name, for
+example `mem.alice_session_parts`. Query them with `/mem:sql` or any ClickHouse client. Read
+`<m>_sessions` with `FINAL`, as you would your own. A table you were not granted is
 refused, and a scope you are under returns only its rows.
+
+## When a house is converted from 0.18
+
+A 0.18 share is a grant on the old rooms, which the conversion renames into the archive.
+The administrator moves the shares with `memhouse migrate --v3-shares`, part of
+[Upgrade to 0.20](upgrade-to-0.20.md). It re-creates only the shares memhouse recorded,
+narrows a 0.18 full share to the six tables, and refuses when the record and the live
+grants disagree. Run it as part of the conversion: until it runs, readers hold whatever
+their 0.18 grants still reach.
+
+## A house on the 0.18 rooms
+
+On a house not yet converted, `share` works as in 0.18:
+
+- a full share is `SELECT ON mem.<you>_*`, which also reaches the stats tables, `meta`,
+  `events` and any room added later;
+- a scoped share is `SELECT` on `<you>_sessions`, `<you>_messages` and
+  `<you>_tool_calls`, filtered by row policies;
+- `source=` filters on the `source` column.
+
+**Scoped shares made before 0.18.10** granted the whole pattern while filtering only three
+rooms. Re-run `memhouse share <user> --only <scope>` once for each, and it is narrowed to
+the three rooms.

package/docs/guides/storage.md

@@ -1,6 +1,46 @@
 # How memory is stored
 
-## A house, rooms, and members
+A house created by memhouse 0.20 is on **schema 3**, described first. A house from 0.18 is on
+the **rooms**, described after it, until its admin converts it
+([Upgrade to 0.20](upgrade-to-0.20.md)).
+
+## Schema 3 (memhouse 0.20)
+
+A member's sessions live in six conversation tables, the harness-sessions-sql profile, plus two capture
+tables only the shipper writes:
+
+| table | holds |
+|---|---|
+| `<db>.<member>_session_parts` | one row per message part: text, thinking, a tool call and its full result, an attachment's hash |
+| `<db>.<member>_session_usage` | one row per usage record, at the editor's granularity (a record, a message or a turn): tokens, model, and how the editor counted them |
+| `<db>.<member>_session_links` | one row per link between sessions, such as a fork or a sub-agent, as a session states it or as the engine inferred or verified it |
+| `<db>.<member>_session_lifecycle` | one row per lifecycle record a session states: an operation on a message, a range of messages or the whole session |
+| `<db>.<member>_calls` | one row per tool call: name, arguments, whether it failed, the result's length (the result itself is a `session_parts` row) |
+| `<db>.<member>_sessions` | one row per session: title, folder, counts, tokens per model and hour, links to forks and sub-agents |
+| `<db>_archive.<member>_session_units` | the source as read: every unit (a line, a row, a file) of every transcript or normalised log, and a manifest for each read that changed something |
+| `<db>_archive.<member>_session_sources` | the shipper's cursor per source |
+
+- **A session is its store.** It is keyed by `host` (a fingerprint of the machine), `harness`,
+  `harness_path` (the harness's data folder; for OpenCode, its DB file), its `session_id`, and an `incarnation` where a
+  harness reuses ids. The same id on another machine, or in another data folder, is another
+  session.
+- **Nothing is overwritten in place.** A row is replaced by a newer version (`rev`). When a
+  message leaves its source (a revert, a rewind, a deleted message), it is written once more
+  as a **removed version** (`removed = 1`). Every read hides it, `memhouse q removed` lists it,
+  and no total counts it.
+- **The archive outlives the editors.** Its units keep every line, row or file as it was read,
+  and a manifest for each read that changed something says what that read delivered. So a session can be rebuilt from the
+  archive alone, including what later went away. A transcript the editor deleted stays in the
+  house.
+- **A fork is billed once.** Where one session is a verified copy of another's beginning, the
+  copy's share of the tokens is subtracted on the fork. The copies stay messages of the fork.
+
+`memhouse doctor` checks all of it: tables and sorting keys, identity stamping, duplicate
+timestamps, removed content, forks billed once, and the machine's host identity.
+
+## The 0.18 rooms
+
+### A house, rooms, and members
 
 - **A house is a ClickHouse database,** normally `mem`.
 - **A member is a ClickHouse user** who ships into it.
@@ -29,7 +69,7 @@ database once leaked into each other. A member can read their isolation back wit
 Reading across members is a `UNION ALL` over the rooms you hold: your own, and any shared
 with you. Naming a room you were not granted is an error, never a silent omission.
 
-## Every row says where it came from
+### Every row says where it came from
 
 - **`user_id`** is stamped by the server: `MATERIALIZED currentUser()`. Async inserts are
   pinned off for members, so the stamp cannot be skipped. `WHERE user_id = 'alice'` is one
@@ -48,7 +88,7 @@ with you. Naming a room you were not granted is an error, never a silent omissio
 - **`origin`** says who wrote the row. The shipper writes `ship`; an import writes its own
   value.
 
-## The house never destroys what it cannot rebuild
+### The house never destroys what it cannot rebuild
 
 **The shipper is insert-only.** It runs no `DELETE`, no `TRUNCATE`, and no mutation of
 any kind, so no privilege it holds can lose you a row.
@@ -83,7 +123,7 @@ a second row would make every rollup count its messages twice.
 The shipper checks the rooms' sorting keys before it writes, and refuses if they are
 wrong. See [Update](update.md#when-the-house-itself-must-change).
 
-## What is not in the house
+### What is not in the house
 
 - Nothing is embedded, summarised or rewritten. Text is stored as the editor wrote it,
   truncated at 50,000 characters per message and 20,000 per tool argument.