memhouse 0.18.12 → 0.20.1

package/docs/README.md

@@ -22,12 +22,14 @@ One common operation each.
 | [Install and onboard](guides/install.md) | install against a local, existing, or invited house; fix `EACCES` |
 | [Configuration](guides/configuration.md) | choose which editors and directories ship; run several instances; follow a channel |
 | [Update](guides/update.md) | stay current, and upgrade every machine of a house |
-| [Daemons and services](guides/daemons.md) | keep the shipper and dashboard running, across reboots |
+| [Upgrade to 0.20](guides/upgrade-to-0.20.md) | move a 0.18 house to schema 3: prepare, convert, reconcile, then switch each machine |
+| [Daemons and services](guides/daemons.md) | keep the shipper and dashboard running, across reboots; open the dashboard |
 | [Invite members](guides/invite.md) | bring a teammate into a house you administer |
-| [Share and revoke](guides/share.md) | let someone read your rooms, scoped or whole |
+| [Share and revoke](guides/share.md) | let someone read your memory, scoped or whole |
 | [Admin password](guides/admin-password.md) | run an admin command without the password reaching `ps`, history, or a transcript |
 | [Search, resume and skills](guides/search-and-resume.md) | find an old session, reopen it, let an agent answer from history |
-| [How memory is stored](guides/storage.md) | houses, rooms, epochs, machine identity, what is never deleted |
+| [Import claude.ai conversations](guides/import-claude-ai.md) | bring a claude.ai data export into your house, and the next export after it |
+| [How memory is stored](guides/storage.md) | houses, a member's tables, machine identity, what is never deleted |
 | [Operate a house](guides/operate.md) | members, migrations, moving a house, backups |
 | [Troubleshooting](guides/troubleshooting.md) | an editor ships nothing, daemons stop, a dashboard looks empty |
 | [Uninstall](guides/uninstall.md) | stop, forget the house, or remove everything |
@@ -37,10 +39,10 @@ One common operation each.
 - `memhouse <command> --help`: every command's own usage. It always prints usage and
   never runs the command.
 - [Release notes](releases/): what changed in each version, and what to do about it.
-- [`../memhouse/house/HOUSE.md`](../memhouse/house/HOUSE.md): the layout and the schema,
-  column by column.
-- [`../memhouse/DESIGN.md`](../memhouse/DESIGN.md): the design, and why it is shaped this
-  way.
+- [`../memhouse/house/HOUSE.md`](../memhouse/house/HOUSE.md): the 0.18 rooms, column by
+  column. Schema 3's tables are in
+  [`../memhouse/house/schema-profile.sql.tpl`](../memhouse/house/schema-profile.sql.tpl).
+- `memhouse/DESIGN.md` (repository, not yet public): the design, and why it is shaped
+  this way.
 - [`../SECURITY.md`](../SECURITY.md): what holds, and what does not.
-- [`docs/design/`](https://github.com/agent-realm/memhouse/tree/main/docs/design) (in the
-  repository): designs captured before they are built.
+- `docs/design/` (repository, not yet public): designs captured before they are built.

package/docs/guides/admin-password.md

@@ -6,9 +6,13 @@ A few commands need the ClickHouse server's administrator:
 - `invite`;
 - `passwd --admin-user …`, for a member whose account predates self-rotation (0.11);
 - `members`;
-- `convert`.
+- `convert`;
+- `migrate --v3-prepare`, `--v3-convert`, `--v3-reconcile` and `--v3-shares`, which move a 0.18
+  house to schema 3 ([Upgrade to 0.20](upgrade-to-0.20.md)). `--v3-switch` is the member's own
+  step.
 
-Shipping, searching and sharing never need it.
+They name the admin with `--admin-user` or `MEMHOUSE_ADMIN_USER` (or the admin this install
+keeps); `MEMHOUSE_USER` names the member. Shipping, searching and sharing never need it.
 
 **The admin password owns the whole server.** Keep it out of three places:
 
@@ -16,7 +20,9 @@ Shipping, searching and sharing never need it.
   runs, and shell history keeps it afterwards;
 - **an agent's conversation**, because memhouse ships that conversation into the house,
   and the archive is insert-only;
-- **disk**, unless you chose that: `--keep-admin`, or `deploy --local`.
+- **disk**, unless you chose that: `--keep-admin`, or `deploy --local`. `memhouse setup`
+  given a credential that administers the server writes nothing without `--keep-admin` (a
+  terminal is asked, default no), and refuses that password on the command line outright.
 
 ## Where memhouse takes it from
 
@@ -26,14 +32,19 @@ In order, first answer wins:
 |---|---|---|
 | 1 | `--admin-password-file <file>` | a file you control, mode 600. One trailing newline is dropped |
 | 1 | `--admin-password-file -` | piping it in: `printf '%s' "$P" \| memhouse … --admin-password-file -` |
-| 2 | `--admin-password <value>` | **deprecated**: works in 0.18.x with a warning, **removed in 0.19.0** |
-| 3 | `MEMHOUSE_ADMIN_PASSWORD` | a secret manager lends it to one command (below) |
-| 4 | the credential this install keeps | only when it belongs to the same admin user |
-| 5 | a prompt | when there is a terminal; input is hidden, and pasting works |
+| 2 | `MEMHOUSE_ADMIN_PASSWORD` | a secret manager lends it to one command (below) |
+| 3 | the credential this install keeps | only when it belongs to the same admin user |
+| 4 | a prompt | when there is a terminal; input is hidden, and pasting works |
 
-The two forms of `--admin-password-file` are one option, and it cannot be combined with
-`--admin-password`. With no source and no terminal, the command stops and prints these
-options. It never hangs, and it never guesses.
+The two forms of `--admin-password-file` are one option. A file that group or other users
+can read or write is refused, like an ssh key, with the `chmod 600` that fixes it; the
+secret mounts of a container (`/run/secrets/`, `/var/run/secrets/`) are the exception.
+With no source and no terminal, the command stops and prints these options. It never
+hangs, and it never guesses.
+
+`--admin-password <value>` is refused. It was deprecated in 0.18.10 and removed in 0.20.0:
+the command stops before doing anything, exits 2, names the forms above, and never prints
+the value.
 
 ## With a secret manager
 
@@ -93,3 +104,19 @@ it before a scripted run, rather than guessing from a grant string.
 Treat it as burned. Rotate it on the server (`ALTER USER … IDENTIFIED BY …`, as the
 admin) and update every place that legitimately holds it. Deleting the transcript does
 not help: the house is insert-only, and it may already have shipped.
+
+## The other passwords a command takes
+
+The same rule holds for `--password` (install, setup, onboard; for `passwd`, the new
+password), `--member-password` (install, invite) and relocate's `--to-password`. Each has a
+file form that takes a path at mode 600 or `-` for stdin, and the two that are not the
+member's own have an environment variable:
+
+| flag on the command line | instead |
+|---|---|
+| `--password <value>` | `MEMHOUSE_PASSWORD`, or `--password-file <file>` / `--password-file -` |
+| `--member-password <value>` | `MEMHOUSE_MEMBER_PASSWORD`, or `--member-password-file …` |
+| `--to-password <value>` | `MEMHOUSE_TO_PASSWORD`, or `--to-password-file …` |
+
+The command-line forms still work in 0.20, with a warning on every run, and are refused
+from the next minor release. Only one password can come from stdin per command.

package/docs/guides/configuration.md

@@ -12,14 +12,15 @@ default house.
 
 | Variable | Meaning |
 |---|---|
-| `MEMHOUSE_URL` | the house's HTTP(S) endpoint |
+| `MEMHOUSE_URL` | the house: its ClickHouse HTTP(S) endpoint, port included |
 | `MEMHOUSE_USER` / `MEMHOUSE_PASSWORD` | the member credential the shipper writes as |
+| `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD` | the server's administrator, for the admin commands only ([admin password](admin-password.md)); never passed to the shipper or the dashboard |
 | `MEMHOUSE_DB` | the database holding the rooms, normally `mem` |
-| `MEMHOUSE_PORT` | the dashboard port, default `4640` |
+| `MEMHOUSE_PORT` | this machine's dashboard port, default `4640`; never the house's port, which is part of `MEMHOUSE_URL`. When it is in use the dashboard takes the next free one, up to 10 above |
 | `MEMHOUSE_CHANNEL` | the npm dist-tag `update` follows |
 | `MEMHOUSE_EDITORS` | which adapters run (default: all) |
 | `MEMHOUSE_<EDITOR>_ROOTS` | where one adapter looks |
-| `MEMHOUSE_HOME` | where the env file, host identity, logs and pidfiles live |
+| `MEMHOUSE_HOME` | where the env file, host identity, logs, pidfiles and the dashboard's token live |
 | `MEMHOUSE_ENGINE` | `docker` or `podman`, for `deploy --local` |
 
 Never print this file or these variables in a terminal an agent is reading. memhouse ships
@@ -46,7 +47,11 @@ MEMHOUSE_EDITORS='claude'
 MEMHOUSE_CLAUDE_ROOTS='~/.claude-playbooks/work-team'
 ```
 
-- `MEMHOUSE_EDITORS` names the adapters to run.
+- `MEMHOUSE_EDITORS` names the adapters to run. On schema 3 it also names the normalisers,
+  which read ten editors' stores directly: `agy` (also answers to `antigravity`),
+  `copilot-cli`, `cursor`, `cursor-agent`, `devin`, `gemini-cli`, `goose`, `opencode`,
+  `vscode`, `zed`. An editor left out is never read, and logs its normaliser wrote earlier
+  are no longer captured.
 - `MEMHOUSE_<EDITOR>_ROOTS` replaces one adapter's location. The variable name is the
   adapter's name upper-cased, with dashes turned into underscores.
 - Claude is the one adapter with many roots, one per Claude Code config directory, so its
@@ -90,8 +95,10 @@ MEMHOUSE_HOME=~/.memhouse-work memhouse instance    # which memhouse this is
 `plugins install claude`, run from an instance, installs the skills into exactly the
 playbooks that instance ships, and **binds** them. It writes `MEMHOUSE_HOME` and
 `MEMHOUSE_BIN` into each playbook's `settings.json` `env`, and Claude Code applies that to
-every session there. So the `/mem:*` skills in a bound playbook read that instance's house
-and run that instance's binary, whatever the launching shell had set. `plugins list` shows
+every session there. So the `/mem:*` skills in a bound playbook read that instance's house,
+whatever the launching shell had set. The skills run plain `memhouse`, so the read commands they
+pre-approve match without a prompt; `MEMHOUSE_BIN` is the instance's binary, which they use
+instead only when `memhouse` is not on PATH or is a different binary. `plugins list` shows
 the binding; `plugins remove claude` takes it out.
 
 ## Channels

package/docs/guides/daemons.md

@@ -3,7 +3,8 @@
 memhouse runs two long-lived processes:
 
 - the **shipper**, which runs an incremental pass every 300 seconds;
-- the **dashboard**, on `http://localhost:4640` (`MEMHOUSE_PORT` changes it).
+- the **dashboard**, on port 4640 of `127.0.0.1` (`MEMHOUSE_PORT` changes it). Open it with
+  `memhouse dashboard`; see [The dashboard](#the-dashboard).
 
 ## Until the next reboot
 
@@ -34,6 +35,37 @@ memhouse service status | stop | start | restart | uninstall
   upgrade, run `memhouse service uninstall`, then `memhouse service install`, so the unit
   points at the new one.
 
+## The dashboard
+
+```bash
+memhouse dashboard             # open it in your browser
+memhouse dashboard --no-open   # write the page, open nothing
+```
+
+- **Every /api request needs this machine's token.** It is a random secret in
+  `$MEMHOUSE_HOME/dashboard-token` (default `~/.memhouse/dashboard-token`), mode 600, made by
+  the first `memhouse start`. A token file that group or other users can read is refused, with
+  the `chmod 600` that fixes it. To replace the token, delete the file and restart the
+  dashboard (`memhouse stop && memhouse start`).
+- **`memhouse dashboard` checks the dashboard, then opens a file.** It first asks the server on
+  `127.0.0.1:<port>` to prove it holds the token, without sending it; anything else listening
+  there gets nothing, and the command exits 1 with "port N is not your dashboard". Then it
+  writes `$MEMHOUSE_HOME/dashboard.html` (mode 600), a page that sends the browser to
+  `http://127.0.0.1:<port>/` with the token in the URL's fragment, and opens that file (`open` on
+  macOS, `xdg-open` on Linux). The page keeps the token for that browser tab only and removes it
+  from the address bar; no cookie is set. A new tab, or a restarted browser, needs
+  `memhouse dashboard` again. The URL with the token is printed only when standard output is a
+  terminal, never with `--json` or into a pipe or file.
+- **Scripts send the token as a header:** `Authorization: Bearer <token>`, read from the file.
+- **Without it,** `/api/*` answers 401, and a page opened without the token says to open the
+  dashboard with `memhouse dashboard`. The page itself holds no house data.
+- **When port 4640 is in use** (possibly by another account on this machine), the dashboard takes
+  the next free port, up to 4650, and `memhouse start` says which. `memhouse status` and
+  `memhouse dashboard` use the port it took. Set `MEMHOUSE_PORT` to choose the port.
+- **From another machine,** forward the port over SSH (`ssh -L 4640:127.0.0.1:4640 <host>`)
+  and keep the default bind. `MEMHOUSE_HOST=0.0.0.0` makes the dashboard reachable from other
+  machines over plain HTTP, token included; prefer the tunnel.
+
 ## One pass by hand
 
 ```bash
@@ -49,5 +81,34 @@ never deletes anything: see [How memory is stored](storage.md).
 ## Logs
 
 The daemons log to `$MEMHOUSE_HOME/logs/` (default `~/.memhouse/logs/`): `shipper.log` and
-`dashboard.log`. `memhouse status` reads the shipper's last pass from its log, and reports
-a failing pass as a failure even while the process is alive.
+`dashboard.log`. `memhouse start` exits 1 when the shipper exits right after starting; a
+dashboard that does is reported as a warning, with the reason from its log. `memhouse status`
+reads the shipper's last pass from its log, and reports a failing pass as a failure even while
+the process is alive.
+
+A pass that would not record an editor's deleted sessions as gone prints one line per store
+and cause after its own line, `[memhouse] vanish refused: <editor> <store>: <why>`: the store's
+list named none of the sessions the house holds of it (an empty or unreadable store), or left
+out a session the store still has, or one that could not be read. Nothing is recorded as
+vanished or removed, and `memhouse doctor` fails a line naming the store until a later pass
+has no such line.
+
+A store whose every session was deleted is refused in the same way, because an empty list is
+also what an unreadable store gives. Its line ends with the command for that case:
+
+```bash
+memhouse doctor --confirm-empty-store <editor>:<store>
+```
+
+Copy it from the line as printed: a store path with spaces is quoted there. It confirms the
+sessions that pass refused (sessions recorded as gone already replay without it), and records
+the confirmation in this machine's capture state, beside the store's sweep state under
+`$MEMHOUSE_HOME/state/derive-profile/stores/`; it needs no house. Removing that folder drops a
+confirmation not yet used. The next pass that finds the store there, its list still empty and
+no other session held takes each as gone where the editor's reader says it is gone, and no
+longer refuses the store. A list that names a session again, or a session held that the
+confirmation does not name, cancels it; a store with more than 100 sessions is taken over
+several passes on the one confirmation.
+
+A `[memhouse] vanish warning: …` line names a listed session's source the list left out that
+still reads: it is captured as usual, and doctor shows the warning without failing.

package/docs/guides/import-claude-ai.md

@@ -0,0 +1,204 @@
+# Import claude.ai conversations
+
+claude.ai keeps your conversations on its servers, not on your machine, so the shipper never
+sees them. `memhouse import claude-ai` reads a claude.ai data export and stores its conversations
+in your house beside your editor sessions. They then show up in search, in `memhouse q` and in
+the `/mem` skills.
+
+Each run is one **batch**. A later export adds only the conversations the house does not hold
+yet, so there is nothing to clean up between exports.
+
+```bash
+memhouse import claude-ai ~/Downloads/claude-export.zip            # dry run: counts only
+memhouse import claude-ai ~/Downloads/claude-export.zip --write    # import
+memhouse import claude-ai --list                                    # the batches in your house
+memhouse import claude-ai --undo <batch> --write                    # take a batch back out
+```
+
+The command needs schema 3: the profile tables (`<member>_session_parts`, `_calls`,
+`_sessions`), or a development house's layout 3.2 tables (`<member>_turns`). A member with both is
+written on the profile, which its readers read. It refuses any other layout before it reads or
+writes anything.
+
+## 1. Get an export
+
+In claude.ai, go to Settings, then Privacy, and choose **Export data**.
+
+The export arrives as **part zips**, one per kind: `conversations-000.zip`,
+`design_chats-000.zip`, `memories-000.zip`, `projects-000.zip` and so on. A large export can have
+more than one part of a kind (`conversations-001.zip`). Pass them all, or the folder that holds
+them:
+
+```bash
+memhouse import claude-ai ~/Downloads/*-000.zip                   # every part, by name
+memhouse import claude-ai ~/Downloads/claude-export/              # a folder holding the parts
+```
+
+- **What is read.** Every `conversations` part and every `design_chats` part, in index order. The
+  other parts are listed as ignored: they hold no conversations.
+- **A conversation in two parts** is stored once, from the first part, and counted as a duplicate.
+- **Refused before anything is read from the house:** no `conversations` part among the inputs,
+  the same part twice (a re-downloaded `conversations-000 (1).zip`, say), or a damaged zip.
+
+`memhouse import claude-ai` takes these forms:
+
+| Input | What it is | `project` of a chat |
+|---|---|---|
+| part zips, or their folder | the export as downloaded now, read in place | `claude-ai` |
+| one `.zip` | an older export, everything in one zip | `claude-ai` |
+| an unpacked folder | an export unpacked: `conversations.json`, `design_chats/` | `claude-ai` |
+| an archive folder | one JSON file per conversation: `projects/<project>/chats/`, `chats-unfiled/<year>/`, `design-chats/` | the folder name under `projects/`, or `claude-ai-unfiled` |
+
+- **Projects come only from an archive folder.** The export does not record which claude.ai
+  project a conversation belongs to. If an archive folder files conversations by project, the
+  import uses that folder's name as `project` and the folder's path as `folder`. From zips or an
+  unpacked export, every chat gets project `claude-ai` and an empty folder.
+- **Design chats** get project `claude-ai-design` from any of the three inputs.
+
+## 2. Dry run
+
+```bash
+memhouse import claude-ai ~/Downloads/claude-export.zip
+```
+
+The dry run connects to the house, and reads it, but writes nothing. It prints counts only, no
+titles or text:
+
+- conversations found, by category;
+- how many are **new**, how many are **already imported**, and how many have **changed since**
+  they were imported;
+- how many are **empty** (no message with any text), and therefore skipped;
+- what a `--write` would add: sessions, turns and tool calls;
+- blocks that are never stored (empty text, token budget markers and the like), by reason.
+
+Add `--json` to get the same as one JSON object.
+
+## 3. Import
+
+```bash
+memhouse import claude-ai ~/Downloads/claude-export.zip --write
+```
+
+It writes the new conversations as one batch, reads the batch back, and checks that the counts
+match. It prints the batch id and the command that undoes it. Batch ids look like
+`claude-ai-2026-01-15-160405`. `--batch <id>` names one yourself, and an id the house already has
+is refused.
+
+Check the result:
+
+```bash
+memhouse q coverage                          # a claude-ai row: sessions, span, origin import
+memhouse q recent --harness claude-ai
+memhouse q search <words> --harness claude-ai
+```
+
+## 4. The next export
+
+Run the same two commands on the new export. A conversation already in the house is skipped.
+Only conversations the house has never held are written.
+
+**Changed conversations** are listed, but not written, unless you ask:
+
+- **How a change is detected.** A conversation counts as *changed since* in two cases:
+  - **newer:** the export's `updated_at` is later than the one stored. claude.ai moves it when a
+    chat gets a new message or a new name;
+  - **same time, other content:** `updated_at` is the same, but what the conversation says
+    differs. claude.ai can add a summary, or a later export can carry what an earlier copy lacked,
+    without moving `updated_at`. The import compares the stored rows with the export's, row by
+    row: the conversation's name, mode and start, and each message part, tool call and result.
+    It ignores what only says where and when the conversation was imported: project, folder,
+    batch, `rev`.
+- **Older is never written.** A conversation whose `updated_at` in the export is earlier than the
+  stored one is counted as already imported, and as *older*. Its content is not compared, and
+  `--update` leaves the newer stored version in place.
+- **`--update` replaces it whole.** Every stored row of the conversation is tombstoned, and the
+  export's version is written above them. A message that is no longer in the export is gone
+  from reads. It is not kept as a removed version, because the export you keep is the record.
+- **The project stays.** From zips or an unpacked export, a replaced conversation keeps the
+  project the house already has, since the export carries none. From an archive folder it takes
+  the folder's.
+- **Without `--update`** the stored version stays as it is.
+- **A stopped `--update` hides what it was replacing.** The old rows are tombstoned before the
+  new ones are written. If the run stops in between, those conversations are missing from reads
+  until you run the same command again, which writes them above the tombstones.
+
+```bash
+memhouse import claude-ai ~/Downloads/claude-export-2.zip --update           # dry run
+memhouse import claude-ai ~/Downloads/claude-export-2.zip --update --write
+```
+
+## 5. Batches and undo
+
+```bash
+memhouse import claude-ai --list
+memhouse import claude-ai --undo claude-ai-2026-01-15-160405           # dry run: what it would remove
+memhouse import claude-ai --undo claude-ai-2026-01-15-160405 --write
+```
+
+- **What `--list` shows.** Every batch with live sessions in the house, with its span and what
+  the house recorded about it. Each batch is recorded in the member's `meta` table under
+  `import:<batch>`:
+  - `applying`: the write started and has not finished;
+  - `applied`: the write finished;
+  - `undoing`: an undo started and has not finished (run the same `--undo ... --write` again; it
+    keeps the counts the first run found);
+  - `undone`: the undo finished.
+- **What `--undo` writes.** A tombstone for every live row of the batch: a full copy at the next
+  `rev`, with `is_deleted = 1`. Nothing is deleted outright. Reads hide the rows at once, and the
+  shipper's maintenance removes them later.
+- **What an undo leaves.** A conversation that a later batch replaced with `--update` belongs to
+  that later batch. Undoing the earlier batch leaves it alone. Undoing the later one removes the
+  conversation; import it again to bring it back.
+- **Re-importing after an undo works.** A new import writes above any tombstones it finds, so
+  a conversation is never hidden behind its own undo.
+- **A run that stops part way (profile tables).** A session whose rows went in but whose totals
+  were not filled yet (`started` empty) is listed as `repair` by the next run, and a `--write`
+  fills it, with or without anything new to import. A batch whose run stopped after all its rows
+  went in is listed as `stopped`, and that `--write` records it `applied`, whatever it writes
+  again with `--update`. A batch whose insert stopped part way stays `applying`: the sessions it
+  did not write are new to the next run, which writes them in its own batch.
+- **One at a time per member.** Imports and undos take no lock, so run them one after another on
+  a member. Two imports at once can split a new conversation's rows between their two batches
+  (undo both and import again). An import beside an undo can record the undo's batch `applied`:
+  re-running the undo puts that right while any of its rows are still live.
+
+## What is stored
+
+Each conversation is one session: harness `claude-ai`, origin `import`, and the conversation's
+uuid as its id (ref `claude-ai:<uuid>`). Its store is the service, not a machine:
+
+- **On the profile tables:** host `s-` plus the first 32 hex of the sha256 of
+  `sessions-model/service-host/v0:claude.ai` (sessions-model's service host), `harness_path`
+  `https://claude.ai`, `host_label` `claude.ai`, adapter `memhouse-import`. A block is a part of its
+  message (`text`, `reasoning` for thinking, `tool_call`, `tool_result`; the summary is a `summary`
+  part in a system message of its own), and a tool use is also a row in `calls`.
+- **On layout 3.2:** host and data folder `claude.ai`, and a block is a turn, as the table below
+  shows.
+
+| From the export | Stored as |
+|---|---|
+| text and thinking blocks | one turn each (`text`, `thinking`) |
+| a tool use | a `tool_call` turn, `Name(args)`, and a row in `calls` |
+| a tool result | a `tool_result` turn with the result as text; its call gets `is_error` and `result_len` |
+| an attachment with extracted text | an extra user `text` turn, `[attachment: <name>]` and the text |
+| attached file names | the turn's `extra` |
+| the conversation's summary | one `summary` turn at the time of the last message |
+| a design chat's messages | one `text` turn each |
+
+- **Keys are stable.** A turn's key is the message uuid plus the block's position in the
+  message, and a call's is the tool use id. When a tool use has no id, the key is
+  `<message uuid>:<position>`, and its result is the next result without an id in the same
+  message. Importing the same conversation again produces the same keys.
+- **No tokens or models.** The export carries neither. On the profile no usage row is written. On
+  layout 3.2 they read as 0, with `usage_basis` set to
+  `none`: unmeasured, not free.
+- **Not imported:** project documents, memories, account data and artifact files. They are not
+  conversations.
+
+## How it fits with the rest of memhouse
+
+- **The shipper never touches imported sessions.** It captures only the stores on your
+  machines, and a `claude.ai` session is in none of them.
+- **`memhouse resume` refuses an imported session.** There is no local session to reopen.
+- **A full share includes them.** A share of your whole house reaches every row of your
+  tables, so a teammate you share it with sees your imported conversations too.

package/docs/guides/install.md

@@ -41,8 +41,9 @@ memhouse deploy --local --tag 26.7          # another ClickHouse version
 
 It runs ClickHouse in a container bound to loopback, with the data in a named volume. The
 container's superuser is `memhouse_root`, which administers the house. You ship as a
-**member** named after your OS user (the command asks; `--user` sets it). The member holds
-one grant, on `mem.<you>_*`. Both credentials go into `~/.memhouse/env`, mode 600, so that
+**member** named after your OS user (the command asks; `--user` sets it). A new house is
+schema 3: the member holds `mem.<you>_*`, its tables in the house, and `SELECT, INSERT` on its two
+capture tables in `mem_archive`. Both credentials go into `~/.memhouse/env`, mode 600, so that
 inviting someone later needs no flags. It then installs and ships.
 
 The user name and password are fixed when the volume is first initialised and reused on
@@ -81,7 +82,7 @@ Useful flags:
 | `--claude-roots DIR[,DIR]` | ship only these Claude Code config directories |
 | `--channel team` | follow this npm dist-tag on `update` |
 | `--keep-admin` | keep the admin credential in the env file (not done by default) |
-| `--ensure-schema` | create any room or stats table the house is missing |
+| `--schema 2` / `--schema 3` | for a member not yet in the house: which layout its tables take. A house holding members on both (mid-upgrade) needs it; otherwise the install follows the house |
 
 The admin password never needs to be on the command line. See
 [Admin password](admin-password.md).
@@ -93,7 +94,7 @@ what an invite install ships, pass `--editors` / `--claude-roots` as flags.
 ### What install checks
 
 Before it writes any config, install connects, confirms who the credential is, and checks
-that it can reach its rooms. The config is written last, so a refused install leaves no
+that it can reach its tables. The config is written last, so a refused install leaves no
 half-configured machine behind.
 
 Configuration resolves in this order: flags, then exported `MEMHOUSE_*` variables, then
@@ -124,5 +125,9 @@ The path proves nothing on its own: Homebrew's prefix is `/usr/local` on Intel a
 
 - `memhouse status`: connection, counts, freshness.
 - `memhouse start` or `memhouse service install`: keep shipping. See [Daemons](daemons.md).
-- `memhouse plugins install claude`: the `/mem:*` skills. See
-  [Search, resume and skills](search-and-resume.md).
+- `memhouse plugins install claude`: the `/mem:*` skills, for Claude Code only. Codex and the
+  other editors' sessions ship all the same; an agent there reads the house with the CLI
+  (`memhouse q`, `memhouse room-sql`). See [Search, resume and skills](search-and-resume.md).
+- `memhouse plugins install codex`: for Codex, a short block in its `AGENTS.md` (the rules) and
+  a `memhouse` skill (the read recipes). Nothing is written under the Codex home unless you run
+  it. See [Codex](search-and-resume.md#codex).

package/docs/guides/invite.md

@@ -1,6 +1,6 @@
 # Invite members
 
-Inviting creates a ClickHouse user and their rooms, and writes one file the invitee
+Inviting creates a ClickHouse user and their tables, and writes one file the invitee
 installs from. It needs a credential that can create users, which means the server's
 admin.
 
@@ -13,15 +13,27 @@ memhouse invite alice --url https://house.example.com
   loopback: `localhost` on their machine is their machine. Use a LAN address, a hostname
   or a tunnel. `--allow-local` overrides this, for the case where the invitee is on the
   same machine.
-- **The rooms are named for them:** `mem.alice_sessions`, `mem.alice_messages`, and so on.
-  Alice is granted exactly `mem.alice_*`, nothing else. A different database:
-  `--db <name>`.
+- **The tables are named for them:** `mem.alice_session_parts`, `mem.alice_sessions` and four
+  more conversation tables, and her capture archive `mem_archive.alice_session_units` and `_session_sources`.
+  Alice is granted `mem.alice_*` and her two archive tables, nothing else. A different
+  database: `--db <name>`.
+- **The house decides the layout,** as it does for an install: a new house is schema 3, a
+  house still on the 0.18 rooms gets rooms (`mem.alice_messages`, …), and a house with
+  members on both is refused until `--schema 3` or `--schema 2` says which.
 - **The file is a credential.** It holds the house URL, alice's user name, a generated
   password and the database. Hand it over a channel you trust: croc, a password manager.
-  Not chat or email. `--out <path>` writes it somewhere else.
+  Not chat or email. `--out <path>` writes it somewhere else. The invitation page,
+  `MEMHOUSE-INVITATION.md`, is written beside it and names that file and the invitee's tables.
 - **Alice installs with `memhouse install --env invite-alice.env`.** It offers to rotate
   the password to one only she knows, which works because she is granted `ALTER USER` on
   herself. Then it deletes the file. Once she rotates, the password you saw stops working.
+- **The invite expires.** The password in the file stops working 7 days after the invite
+  (`--expires <days>` sets 1 to 365), counted by the server's clock. The output, the file and
+  the invitation page say when. Installing lifts the expiry, whether she changes the password
+  or keeps it with `--keep-password`. After the date, `install` refuses the file and tells her
+  to ask for a new invite. Her account is still there, so remove it first (`DROP USER alice`, as
+  the administrator; `invite` says so when it meets it), then invite her again. Her tables are
+  kept and reused.
 
 ## Which admin credential
 
@@ -83,5 +95,7 @@ memhouse members --db other      # another database
 ## Removing a member
 
 There is no `memhouse` verb for it yet. With the admin credential, `DROP USER <name>`
-stops every machine shipping as them. Their rooms stay until you drop them too. See
-[Operate a house](operate.md) before you drop anything: there is no undo.
+stops every machine shipping as them. Their shares and tables stay until you remove them too,
+in `mem` and in `mem_archive`, shares first: [Operate a house](operate.md#removing-a-member) has
+the order and lists the tables by exact name. Read it before you drop anything: there is no
+undo.