memhouse 0.18.8 → 0.18.10

package/docs/guides/admin-password.md

@@ -0,0 +1,95 @@
+# Admin password
+
+A few commands need the ClickHouse server's administrator:
+
+- `install --admin-user …`, which creates a member;
+- `invite`;
+- `passwd --admin-user …`, for a member whose account predates self-rotation (0.11);
+- `members`;
+- `convert`.
+
+Shipping, searching and sharing never need it.
+
+**The admin password owns the whole server.** Keep it out of three places:
+
+- **the command line**, where `ps` shows it to every user on the machine while the command
+  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`.
+
+## Where memhouse takes it from
+
+In order, first answer wins:
+
+| # | source | use it when |
+|---|---|---|
+| 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 |
+
+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.
+
+## With a secret manager
+
+The best form: the value exists only in the one command's environment.
+
+```bash
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:pilot/house-admin -- \
+  memhouse invite alice --url https://house.example.com --admin-user default
+
+# 1Password
+op run --env-file=<(echo 'MEMHOUSE_ADMIN_PASSWORD=op://Infra/house-admin/password') -- \
+  memhouse members --admin-user default
+```
+
+In CI, put it in the job's secret store and expose it as `MEMHOUSE_ADMIN_PASSWORD` for
+that step only.
+
+## Typing it once, in a terminal
+
+```bash
+memhouse invite alice --url https://house.example.com --admin-user default
+# prompts for the admin password; what you type or paste is not shown
+```
+
+Or, to reuse it for a few commands in one shell without it reaching history:
+
+```bash
+read -rs MEMHOUSE_ADMIN_PASSWORD && export MEMHOUSE_ADMIN_PASSWORD
+memhouse members --admin-user default
+unset MEMHOUSE_ADMIN_PASSWORD
+```
+
+## Keeping it on this machine
+
+`install --admin-user … --keep-admin` writes the admin credential into
+`~/.memhouse/env`, so later `invite` and `members` need no flags. `deploy --local` does
+the same, because a local house's admin is yours. Otherwise memhouse does not save it.
+
+Even when it is saved, the daemons never carry it: service units and the started
+shipper and dashboard have `MEMHOUSE_ADMIN_*` removed from their environment.
+
+To stop keeping it, delete the `MEMHOUSE_ADMIN_USER` and `MEMHOUSE_ADMIN_PASSWORD` lines
+from the env file.
+
+## What `whoami --admin` tells you
+
+```bash
+memhouse whoami --admin --json
+```
+
+This reports what the admin credential (`MEMHOUSE_ADMIN_*`, or the kept one) may
+actually do on the server, for example `canProvision`. It never prints the password. Use
+it before a scripted run, rather than guessing from a grant string.
+
+## If a password reached a transcript
+
+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.

package/docs/guides/configuration.md

@@ -0,0 +1,109 @@
+# Configuration
+
+Everything memhouse needs is in one env file, `~/.memhouse/env` (mode 600), or in the
+directory named by `MEMHOUSE_HOME`. Values resolve in this order:
+
+1. command-line flags;
+2. exported `MEMHOUSE_*` variables;
+3. `$MEMHOUSE_HOME/env`.
+
+With nothing configured, commands that touch the house refuse and say so. There is no
+default house.
+
+| Variable | Meaning |
+|---|---|
+| `MEMHOUSE_URL` | the house's HTTP(S) endpoint |
+| `MEMHOUSE_USER` / `MEMHOUSE_PASSWORD` | the member credential the shipper writes as |
+| `MEMHOUSE_DB` | the database holding the rooms, normally `mem` |
+| `MEMHOUSE_PORT` | the dashboard port, default `4640` |
+| `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_ENGINE` | `docker` or `podman`, for `deploy --local` |
+
+Never print this file or these variables in a terminal an agent is reading. memhouse ships
+transcripts, and a password that appears in one is in the archive.
+
+## Which sessions ship
+
+By default, everything on the machine: every adapter, from wherever that editor keeps its
+sessions. `memhouse discover` prints what each adapter watches and the variable that moves
+it:
+
+```
+Watched directories (override with the variable shown, in the env file):
+    claude       ~/.claude, ~/.claude-playbooks/kommander, …   [MEMHOUSE_CLAUDE_ROOTS]
+    codex        ~/.codex                                      [MEMHOUSE_CODEX_ROOTS]
+    gemini-cli   ~/.gemini                                     [MEMHOUSE_GEMINI_CLI_ROOTS]
+    cursor       ~/Library/Application Support/Cursor/User, …  [built-in]
+```
+
+Two kinds of line in the env file narrow it, or `--editors` / `--claude-roots` at install:
+
+```
+MEMHOUSE_EDITORS='claude'
+MEMHOUSE_CLAUDE_ROOTS='~/.claude-playbooks/kommander-chaos'
+```
+
+- `MEMHOUSE_EDITORS` names the adapters to run.
+- `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
+  list may hold several. Every other adapter has one store and takes one path.
+- Adapters marked `[built-in]` resolve a platform app-data directory and cannot be moved
+  yet.
+
+An adapter name or a directory that does not exist is refused and reported against that
+adapter. It is never shipped from the default instead: a typo that quietly shipped
+nothing would look like a working install with an empty house.
+
+Restart the shipper after changing these (`memhouse stop && memhouse start`, or
+`memhouse service restart`).
+
+## Instances: several memhouses on one machine
+
+An **instance** is a home. It has:
+
+- an env file naming a house;
+- the daemons shipping to that house;
+- the playbooks whose sessions it ships (`MEMHOUSE_CLAUDE_ROOTS`).
+
+A machine can run several, each under its own `MEMHOUSE_HOME` and on its own channel:
+
+```bash
+MEMHOUSE_HOME=~/.memhouse-work memhouse install --env invite-work.env
+MEMHOUSE_HOME=~/.memhouse-work memhouse instance    # which memhouse this is
+```
+
+`memhouse instance` prints one screen:
+
+- the instance's name and home;
+- the binary and its channel;
+- the house, its database and member, and whether an admin credential is present;
+- the rooms, with row counts;
+- what this machine ships;
+- the host identity;
+- the daemons;
+- which playbooks are bound to this instance.
+
+`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
+the binding; `plugins remove claude` takes it out.
+
+## Channels
+
+`memhouse update` follows the npm dist-tag the install came from, not `latest` by reflex.
+
+- The channel is inferred from the installed version.
+- To pin it, add `MEMHOUSE_CHANNEL='team'` to the env file, or run
+  `memhouse update --channel team`, which writes the same line.
+- An invite from a house on a channel carries that channel, so the invitee follows it
+  too.
+- A tarball or checkout build sits on no tag and is never auto-updated. `update --check`
+  says so.
+
+Today there is one release line: `latest`, with `team` as an alias for the same build.

package/docs/guides/daemons.md

@@ -0,0 +1,53 @@
+# Daemons and services
+
+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).
+
+## Until the next reboot
+
+```bash
+memhouse start      # both, detached, with pidfiles in $MEMHOUSE_HOME
+memhouse stop
+memhouse status     # running or not, and whether the last pass succeeded
+```
+
+`start` detaches, so the processes outlive the shell, but not a restart.
+
+## Across reboots
+
+```bash
+memhouse service install             # systemd --user on Linux, a LaunchAgent on macOS
+memhouse service install --interval 600
+memhouse service status | stop | start | restart | uninstall
+```
+
+`service install` writes a real user service and takes over from any `start` daemons.
+
+- **The unit gets the member credential only.** `MEMHOUSE_ADMIN_*` is dropped before the
+  environment is written into the unit, and the shipper and dashboard are started without
+  it, even when your shell exported it.
+- **On Linux, a `--user` unit stops at logout unless lingering is on.** `service install`
+  detects this and prints the `loginctl enable-linger <you>` command.
+- **The unit runs the Node binary that installed it.** After a Homebrew or nvm Node
+  upgrade, run `memhouse service uninstall`, then `memhouse service install`, so the unit
+  points at the new one.
+
+## One pass by hand
+
+```bash
+memhouse ship           # one incremental pass, in the foreground
+memhouse ship --full    # re-read every session, not just the changed ones
+```
+
+A pass is incremental. A session is skipped when the house already holds it at least as
+fresh and at least as large. For a session that grew, only the new turns are sent, when
+every earlier turn is already in the house unchanged. `--full` rereads everything. It
+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.

package/docs/guides/install.md

@@ -0,0 +1,128 @@
+# Install and onboard
+
+memhouse is one npm package with no build step and no native dependency. It needs
+**Node 24 or newer**. SQLite comes from `node:sqlite`, which is stable in 24. On 22.13+ it
+works but prints an `ExperimentalWarning` on every command, and Node 20 is past end of life.
+
+```bash
+npm install -g memhouse
+```
+
+Then pick the path that matches your situation.
+
+| You have | Run |
+|---|---|
+| nothing yet, and want the guided route | `memhouse onboard` |
+| nothing, but docker or podman | `memhouse deploy --local` |
+| an invite file from someone's house | `memhouse install --env invite-<you>.env` |
+| a ClickHouse and a member credential | `memhouse install --url … --user … --db mem` |
+| a ClickHouse and its admin credential | `memhouse install --url … --admin-user … --member <you>` |
+| a ClickHouse someone else administers | `memhouse install --print-sql`, then hand them the SQL |
+
+## `onboard`: the guided route
+
+`memhouse onboard` is interactive:
+
+1. it discovers your editors;
+2. it asks where the house is. If none exists and docker or podman is present, it offers
+   to run one locally;
+3. it ships;
+4. it offers to start the daemons and to install the Claude Code skills.
+
+Everything it does can also be done with the scriptable commands below.
+
+## `deploy --local`: a house on this machine
+
+```bash
+memhouse deploy --local                     # ClickHouse 25.11 on 127.0.0.1:8123
+memhouse deploy --local --house-port 18123  # another port, if 8123 is taken
+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
+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
+every redeploy. `memhouse deploy --down` removes the container **and the volume, which
+deletes the memory**.
+
+When both docker and podman are installed and one of them cannot answer, choose with
+`MEMHOUSE_ENGINE=docker` or `MEMHOUSE_ENGINE=podman`. With rootless podman on Linux, the
+container may stop at logout unless lingering is on. `deploy` detects this and prints the
+`loginctl enable-linger` command.
+
+## `install`: the scriptable route
+
+```bash
+# a member credential you already have
+MEMHOUSE_PASSWORD=… memhouse install --url https://house.example.com --user alice --db mem --yes
+
+# from an invite file (the usual way to join a team)
+memhouse install --env invite-alice.env
+
+# you hold the server's admin: memhouse creates the member, then ships as the member
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:pilot/house-admin -- \
+  memhouse install --url https://house.example.com --admin-user default --member alice
+
+# you hold nothing: print the SQL for whoever administers the server
+memhouse install --print-sql --member alice
+```
+
+Useful flags:
+
+| Flag | Effect |
+|---|---|
+| `--yes` | no questions; take the defaults |
+| `--no-ship` | configure and verify, but do not ship yet |
+| `--editors claude,codex` | ship only these adapters ([configuration](configuration.md)) |
+| `--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 |
+
+The admin password never needs to be on the command line. See
+[Admin password](admin-password.md).
+
+`install --env <file>` reads the connection **only** from the file. Exported `MEMHOUSE_*`
+variables are ignored, including `MEMHOUSE_EDITORS` and `MEMHOUSE_CLAUDE_ROOTS`. To narrow
+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
+half-configured machine behind.
+
+Configuration resolves in this order: flags, then exported `MEMHOUSE_*` variables, then
+`~/.memhouse/env`. There is no built-in default house. With nothing configured, commands
+that read or write memory refuse and say so. They never guess `localhost:8123`, which on
+many machines is somebody else's house.
+
+## `EACCES` on install
+
+`sudo` is right for only one of the two causes. What tells them apart is **who owns the
+prefix root**, not the path, and not the file npm named.
+
+```bash
+ls -ld "$(npm prefix -g)"
+```
+
+- **Owned by `root`:** a system-managed Node (distro packages under `/usr`). Re-run with
+  `sudo npm install -g memhouse`.
+- **Owned by you:** the prefix is yours (Homebrew, fnm, nvm, volta). The root-owned file
+  npm tripped on is left over from an earlier `sudo npm`, and another `sudo` adds more.
+  Repair just that path: `sudo chown -R "$(id -u):$(id -g)" <the path npm named>`. Do the
+  same for `~/.npm` if npm names it.
+
+The path proves nothing on its own: Homebrew's prefix is `/usr/local` on Intel and
+`/opt/homebrew` on Apple Silicon, and it is yours in both cases.
+
+## After installing
+
+- `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).

package/docs/guides/invite.md

@@ -0,0 +1,87 @@
+# Invite members
+
+Inviting creates a ClickHouse user and their rooms, and writes one file the invitee
+installs from. It needs a credential that can create users, which means the server's
+admin.
+
+```bash
+memhouse invite alice --url https://house.example.com
+#   invite written: invite-alice.env
+```
+
+- **`--url` is the address the invitee will reach the house at,** not yours. It cannot be
+  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 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.
+- **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.
+
+## Which admin credential
+
+`invite` uses, in order:
+
+1. the admin credential this install keeps. `deploy --local` keeps one;
+   `install --keep-admin` keeps one;
+2. otherwise, `--admin-user <name>` plus the password from `MEMHOUSE_ADMIN_PASSWORD`, from
+   `--admin-password-file`, or from a prompt.
+
+```bash
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:pilot/house-admin -- \
+  memhouse invite alice --url https://house.example.com --admin-user default
+```
+
+Never paste the admin password into an agent's conversation. memhouse ships that
+conversation into the house. See [Admin password](admin-password.md).
+
+Not the admin? `memhouse invite alice --url … --print-sql` prints the statements for
+whoever is, plus the env-file lines to hand alice. The printed plan never holds a password:
+it says `IDENTIFIED BY <member-password>`, which does not parse until the administrator
+puts a quoted password they generate in its place, and the same password goes into the
+env file. `install --print-sql` works the same way.
+
+## When the name is taken
+
+`invite` refuses a name whose messages room already holds rows. Inviting into it would
+hand the newcomer somebody else's memory, and their first ship would land on top of it.
+It suggests another name or another database.
+
+`--adopt` overrides the refusal for one case: **the same person with a new credential**.
+For example, someone lost their password and their old machine. The rooms and their
+history stay; the new credential takes them over.
+
+**Inviting a ClickHouse user who already exists is refused.** memhouse does not reset an
+existing member's password through an invite.
+
+- To change your own password: `memhouse passwd`. Since 0.11 a member may alter their own
+  account, so no admin is needed. memhouse writes the new password to the env file and
+  never prints it.
+- There is no verb for resetting **someone else's** password. If a member is locked out,
+  an administrator runs `ALTER USER <name> IDENTIFIED BY '<new password>'` in a ClickHouse
+  client, then hands the member an env file holding it, the way an invite does. Keep the
+  new password out of any agent's conversation.
+
+Either way, every machine shipping under the old password fails authentication until its
+env file has the new one.
+
+## Seeing who is in a house
+
+```bash
+memhouse members                 # every member, and what each one's grants reach
+memhouse members --db other      # another database
+```
+
+`members` needs the admin credential. A member sees their own grants with
+`memhouse whoami`.
+
+## 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.

package/docs/guides/operate.md

@@ -0,0 +1,112 @@
+# Operate a house
+
+For whoever administers the ClickHouse server behind a house. Each command below takes the
+admin credential as described in [Admin password](admin-password.md). From Claude
+Code, `/mem:admin` does the same work and keeps the password out of the conversation.
+
+## Who is here
+
+```bash
+memhouse members                 # every member of the house, and what each grant reaches
+memhouse members --db other
+memhouse whoami --admin          # what the admin credential may actually do
+```
+
+Useful read-only SQL, run as the admin:
+
+```sql
+-- every house and its size
+SELECT database, formatReadableSize(sum(bytes_on_disk)) AS disk, sum(rows) AS rows
+FROM system.parts WHERE active GROUP BY database ORDER BY sum(bytes_on_disk) DESC;
+
+-- one member's rooms
+SELECT table, formatReadableSize(sum(bytes_on_disk)) AS disk, sum(rows) AS rows
+FROM system.parts WHERE active AND database = 'mem' AND table LIKE 'alice\_%'
+GROUP BY table;
+
+-- what someone may do
+SHOW GRANTS FOR alice;
+```
+
+## Adding and removing people
+
+- **Add:** [`memhouse invite`](invite.md).
+- **Reset a member's password:** the member runs `memhouse passwd` themselves. For a
+  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.
+
+**Before any destructive statement, look first.**
+
+- Count the rows in each room, find who wrote them and when, and from which machines.
+- Run every predicate as a `SELECT` before you run it as a `DELETE` or `DROP`.
+
+There are no backups unless you made them, and the transcripts behind a room may already
+be gone from the editors that produced them.
+
+## Migrations
+
+When a release needs the rooms rebuilt, the shipper refuses to write until the house is
+migrated:
+
+```bash
+memhouse migrate --dry-run
+memhouse migrate             # copy, atomic swap; the old room is kept as <room>_pre_<suffix>
+memhouse migrate-rooms       # the same, rooms only
+```
+
+Nothing is deleted. Drop the `_pre_` tables when you are satisfied. See
+[Update](update.md#when-the-house-itself-must-change).
+
+## Convert
+
+A house from before 0.18 has a database per member. `memhouse convert` moves it to the one
+layout, `mem.<member>_*`:
+
+```bash
+memhouse convert --admin-user default --dry-run        # what would move
+memhouse convert --admin-user default --print-sql      # the statements, to run yourself
+memhouse convert --admin-user default                  # do it
+memhouse convert --admin-user default --guides --out ~/Downloads/upgrade
+```
+
+`--guides` writes a per-member upgrade guide. Members then run `memhouse update`, and
+their shipper adopts the moved rooms itself. Take a server snapshot first.
+
+## Moving a house to another server
+
+`memhouse relocate --to <url>` copies a whole house server-to-server and repoints this
+install. **Known gap:** relocate predates the one layout and fails on a one-layout house
+before it changes anything. Until it is updated, moving a house is an operator
+task with ClickHouse's own tools (`BACKUP`/`RESTORE`, or `INSERT … SELECT FROM remote()`).
+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.
+
+- **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
+  taken before the removal, until that backup rotates out.
+
+## Server settings that matter
+
+| 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 |
+| `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 |
+
+ClickHouse 25.11 and 26.x are tested in CI.
+
+## A build to test with
+
+`memhouse nightly --out DIR`, run from a checkout, builds an installable, version-stamped
+tarball and publishes nothing. Install it on a test machine with
+`npm install -g <tarball>`.

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

@@ -0,0 +1,95 @@
+# Search, resume and skills
+
+## Search
+
+```bash
+memhouse search "connection refused"
+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.
+
+## Resume
+
+```bash
+memhouse resume claude-code:6b1f…
+#   cd /path/to/project && claude --resume 6b1f…
+```
+
+`resume` **prints** the command and does not run it. A resume from the wrong directory,
+or with a stale id, does not fail: it opens a **new** session, and the tool reports
+success while the transcript you wanted is still gone. Printing it lets you see the
+directory and the id first.
+
+| editor | resume |
+|---|---|
+| Claude Code, Codex, OpenCode | verified: prints the command |
+| Cursor, Zed, VS Code, Kiro, Copilot for JetBrains, Antigravity, Devin | no CLI that takes a session id; `resume` says so |
+| goose, Gemini CLI, Cursor Agent, Copilot CLI | refused as *unverified*: nobody has confirmed the flag from the tool's own `--help` yet |
+
+## Numbers
+
+```bash
+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:
+
+- cost by model, editor and project;
+- tool-call rankings;
+- activity over time;
+- which machine wrote what.
+
+**Some editors record no token usage.** Kiro, VS Code, Zed and one of Cursor's two
+storage paths extract none, so their cost shows as zero. Read that as *unknown*, not
+*free*.
+
+## Skills for your agents
+
+```bash
+memhouse plugins install claude     # every Claude Code config dir found; choose, or --yes for all
+memhouse plugins install claude --target ~/.claude
+memhouse plugins list
+memhouse plugins remove claude
+```
+
+The five skills:
+
+| skill | for |
+|---|---|
+| `/mem:recall` | answer a question from past sessions: search, read the transcripts, answer, cite |
+| `/mem:house` | is memory working, what does the house hold, which machines write, who can read it |
+| `/mem:sql` | read-only SQL for numbers: spend, models, tools, activity |
+| `/mem:access` | invite someone, share your house, list or revoke shares |
+| `/mem:admin` | operate the server as its administrator, without the password entering the conversation |
+
+`plugins install` acts on **every** Claude Code config directory on the machine:
+`~/.claude`, whatever `CLAUDE_CONFIG_DIR` points at, and each playbook under
+`~/.claude-playbooks/`. All are selected by default. Installing into the default config
+alone is how `/mem:recall` ends up missing from the playbook you actually work in, and a
+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.
+
+## Writing your own queries
+
+The rooms are documented column by column in
+[`memhouse/house/HOUSE.md`](../../memhouse/house/HOUSE.md). Two rules matter for every
+query:
+
+1. **Join on `(session_id, user_id)`**, never on `session_id` alone. Two members' editors
+   can produce the same local session id.
+2. **Filter to the current parse.** A session's rows can hold more than one parse (an
+   `epoch`; see [How memory is stored](storage.md)). Counts must keep only the newest:
+
+   ```sql
+   WHERE origin != 'ship'
+      OR (session_id, user_id, epoch) IN (
+           SELECT session_id, user_id, max(epoch) FROM mem.<you>_messages
+           WHERE origin = 'ship' GROUP BY session_id, user_id)
+   ```
+
+Read with `FINAL`, or the `final=1` setting, so that ReplacingMergeTree versions collapse.