memhouse 0.18.9 → 0.18.11

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.

package/docs/guides/share.md

@@ -0,0 +1,102 @@
+# Share and revoke
+
+A share lets another member of the same server read your rooms. 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.
+
+```bash
+memhouse share bob                          # full: everything in mem.<you>_*
+memhouse share bob --only project=billing   # scoped: three rooms, filtered
+memhouse share --list                       # what memhouse has recorded
+memhouse share bob --revoke                 # take it back
+```
+
+## Full or scoped
+
+| | 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.
+
+## Scopes
+
+`--only key=value[,key=value…]`. All the keys must hold (AND):
+
+| 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
+use in `MEMHOUSE_EDITORS`. Claude Code rows, for example, say `claude-code`, not `claude`.
+The values:
+
+| 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`.
+
+An empty scope (`--only ""`, or `--only "$SCOPE"` with the variable unset) is refused.
+It never falls back to a full share.
+
+## How the server must be configured
+
+Row policies in ClickHouse have one sharp edge. On some server configurations, the first
+policy on a table hides every row from readers who have no policy of their own: you, and
+your full-share grantees. Before it creates the first policy, `share` measures how this
+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.
+
+## 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.
+- **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.
+
+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>`.
+
+## 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
+refused, and a scope you are under returns only its rows.

package/docs/guides/storage.md

@@ -0,0 +1,93 @@
+# How memory is stored
+
+## A house, rooms, and members
+
+- **A house is a ClickHouse database,** normally `mem`.
+- **A member is a ClickHouse user** who ships into it.
+- **Each member's rooms are tables named for them:**
+
+| room | holds |
+|---|---|
+| `<member>_sessions` | one row per session: editor, project, folder, branch, timestamps, title |
+| `<member>_messages` | every turn: role, text, model, tokens, timestamp, position |
+| `<member>_tool_calls` | every tool call: name, arguments, which message made it |
+| `<member>_session_stats`, `_session_model_stats`, `_session_tool_stats` | precomputed rollups for the dashboard, refreshed after each pass |
+| `<member>_meta` | memhouse's own records: schema version, writers, shares |
+| `<member>_events` | an append-only log: migrations, version changes |
+
+**A member holds one grant: `ON mem.<member>_*`.** That covers their own rooms, present and
+future, and nothing else in the database. Nobody is granted the database itself:
+`ALL ON mem.*` would also reach rooms created later, which is how two people in one
+database once leaked into each other. A member can read their isolation back with
+`SHOW GRANTS`.
+
+| | rooms | each member holds |
+|---|---|---|
+| alone on a laptop | `mem.polat_*` | one grant on `mem.polat_*` |
+| a team on one server | `mem.polat_*`, `mem.alice_*`, … | one grant each, on their own |
+
+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
+
+- **`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
+  person.
+- **`host`** is the machine. Every row carries `<hostname>-<8 hex>`, where the 8 hex come
+  from a fingerprint of the OS's own machine id (IOPlatformUUID on macOS,
+  `/etc/machine-id` on Linux), hashed so the raw id never leaves the machine. It is kept in
+  `$MEMHOUSE_HOME/host.json`. It is not taken from the hostname:
+  - two laptops that both answer to `MacBook-Pro` still get different ids;
+  - a renamed machine keeps its id, and `status` reports the new name beside it;
+  - reinstalling, even after `uninstall --full-removal`, brings the same machine back
+    under the same id. Where no machine id can be read, it falls back to a random one.
+
+  `memhouse status` shows this machine's id. `memhouse doctor` names every host in your
+  rooms.
+- **`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 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.
+
+That has a cost. ReplacingMergeTree deduplicates but does not diff: a re-parse that yields
+*fewer* messages leaves the old, higher-positioned rows in place. A shorter re-parse has
+three possible causes:
+
+- an adapter bug was fixed, and the extra rows were junk;
+- Claude Code **compacted** the transcript;
+- the editor's retention window removed it.
+
+In the last two cases the house holds the only surviving copy. So rows carry an `epoch`,
+which says which parse of the session they belong to:
+
+- **Nothing changed**, or the session just grew: the same epoch. Rows deduplicate exactly,
+  and no extra storage is used.
+- **Shorter, or rewritten at a position the house already holds:** the new parse goes to
+  `epoch + 1`. The old parse stays complete and readable.
+
+Reads show one parse per session, the newest, so counts, tokens and cost are not
+inflated. The skills, the dashboard and `memhouse search` all filter this way; hand-written
+queries should too ([the clause](search-and-resume.md#writing-your-own-queries)).
+
+**Imported history is protected the same way.** `origin` is in the sorting key of
+`messages` and `tool_calls`, so a shipped row can never collapse an imported one. Anything
+imported from an older house, another product, or a machine that no longer exists survives
+every re-ship. `sessions` is the deliberate exception: it holds one row per session, with
+no `origin` or `epoch` in its key. A session's metadata has a single current version, and
+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
+
+- 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.
+- No LLM runs anywhere in memhouse's write or read path. The skills are read by your agent,
+  which does the reading and reasoning.
+- The local transcript files stay where the editor put them. memhouse reads them and never
+  modifies them.

package/docs/guides/troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting
+
+Start with the two diagnostics. Both are read-only.
+
+```bash
+memhouse doctor      # the whole pipeline, one line per check
+memhouse discover    # what each editor adapter sees on this machine
+```
+
+## An editor ships nothing
+
+`discover` lists every adapter. Each one is in one of three states:
+
+- it has sessions, with a count;
+- it has none, because the editor is not used on this machine;
+- it was **skipped**, with the reason.
+
+A skipped adapter and an editor you do not have both contribute zero sessions, so
+memhouse always says which one it is. Common causes, one store at a time:
+
+- **A SQLite store locked by the running editor:** `state.vscdb` for Cursor and VS Code.
+  The next pass retries.
+- **A store the editor moved or changed** in a new release.
+- **A scope that excludes it:** `MEMHOUSE_EDITORS` or a `MEMHOUSE_<EDITOR>_ROOTS` in the
+  env file. See [Configuration](configuration.md#which-sessions-ship).
+
+SQLite comes from Node itself (`node:sqlite`), so there is no native module to rebuild.
+
+## Status says the shipper runs, but nothing new arrives
+
+`memhouse status` reads the shipper's last pass from its log, and shows a failing pass
+as a failure.
+
+- **`Authentication failed`:** the password in `~/.memhouse/env` is no longer the
+  member's. This happens after a `passwd` on another machine, or a reset by the admin. Put
+  the current password into `MEMHOUSE_PASSWORD` in `~/.memhouse/env` (or run
+  `memhouse setup`, which asks), then restart the shipper.
+- **A pass that keeps withholding a session:** an adapter returned nothing for a session
+  the house already holds. The shipper refuses to replace a transcript with an empty one,
+  and says so on every pass, until the store is readable again.
+- **Nothing to ship:** sessions are only shipped once the editor has written them.
+
+## Daemons don't survive a reboot
+
+`memhouse start` uses pidfiles. Its daemons outlive the shell but not a restart. Use
+`memhouse service install` ([Daemons](daemons.md)). On Linux, also enable lingering, or
+user services stop at logout. A rootless podman house from `deploy --local` has the same
+exposure, and `deploy` prints the fix.
+
+## The dashboard is empty, or stale
+
+- **It reads the house, not the machine.** Check `memhouse status` for the connection
+  first.
+- **It reads precomputed stats,** refreshed at the end of each pass that shipped
+  something. On a house where nothing has shipped for a day, the stats age out, and a
+  running dashboard keeps reading them. Restart it (`memhouse stop && memhouse start`). It
+  then reads the rooms directly, until the next pass that ships refreshes the stats.
+  A fix is planned.
+- **After an upgrade it shows the old version:** restart it (`memhouse update` does this).
+
+## `EACCES` during `npm install -g`
+
+See [Install](install.md#eacces-on-install). `sudo` is right only when the npm prefix is
+owned by root.
+
+## `refused`, `ACCESS_DENIED`, `Not enough privileges`
+
+- For a member, these are expected outside `mem.<you>_*` and the rooms shared with you.
+  `memhouse whoami` shows what your credential may do.
+- For `invite`, `members` or `convert`: you need the admin credential. See
+  [Admin password](admin-password.md).
+- A room that should be yours but is refused usually means the house is older than this
+  version. Run `memhouse doctor`, then `memhouse migrate` if it says so.
+
+## Still stuck
+
+Run `memhouse doctor` and `memhouse status --json`, and open an issue with both outputs.
+Check them before posting, and remove anything private, such as a host name.

package/docs/guides/uninstall.md

@@ -0,0 +1,37 @@
+# Uninstall
+
+Three tiers. **None of them touches the memory in the house.**
+
+```bash
+memhouse uninstall                   # stop everything; KEEP the config and this machine's identity
+memhouse uninstall --credentials     # also forget the house and its password
+memhouse uninstall --full-removal    # all of ~/.memhouse, identity included
+npm uninstall -g memhouse            # then remove the package
+```
+
+- **The default is the conservative one.** Stopping the shipper is routine: before an
+  upgrade, while debugging, or when a laptop should go quiet for a week. It should not
+  also mean "forget which house I use and who this machine is".
+- **`--full-removal` asks first.** It deletes `host.json`. A later reinstall derives the
+  same identity again from the machine's own id, so your history stays one machine, unless
+  the machine was renamed in between or has no readable machine id. Then it comes back as
+  a new host.
+- **Your memory stays.** The rooms in ClickHouse are untouched by every tier. What the
+  shipper wrote can be rebuilt from the local session stores with `memhouse ship --full`,
+  for as long as the editors keep them.
+
+## Removing the house itself
+
+- **A local house** from `deploy --local`: `memhouse deploy --down` removes the container
+  **and its data volume**. That deletes the memory, and there is no undo.
+- **A shared server:** an administrator drops your rooms and user. See
+  [Operate a house](operate.md).
+
+## Removing the skills
+
+```bash
+memhouse plugins remove claude
+```
+
+This removes the `/mem:*` skills, and the instance binding, from the Claude Code config
+directories they were installed into.

package/docs/guides/update.md

@@ -0,0 +1,68 @@
+# Update
+
+```bash
+memhouse update            # upgrade along this install's channel, restart the daemons, check the house
+memhouse update --check    # compare versions, change nothing
+```
+
+`update` does three things that a bare `npm install -g memhouse@latest` does not:
+
+1. **It restarts the daemons.** A running shipper keeps parsing with the code it booted
+   with. One once ran for 1 day 16 hours out of a directory that had since been moved.
+2. **It checks whether the house needs a migration** for the new version, and offers to run
+   it. `--migrate` runs it without asking.
+3. **It stays on your channel** (`MEMHOUSE_CHANNEL`). See
+   [Configuration](configuration.md#channels).
+
+Upgraded by hand already? Finish the job without reinstalling:
+
+```bash
+npm install -g memhouse@latest
+memhouse update --no-install
+```
+
+The daemons also notice on their own. Each one compares the installed version with the
+version it booted with, and hands over when they differ: under systemd or launchd it
+exits so the supervisor restarts it; with nothing supervising, it re-executes itself.
+`update` just makes the switch immediate.
+
+## Several machines on one house
+
+Every machine of every member runs its own shipper. Upgrade them all.
+
+- The release notes for each version say whether the order matters and whether mixed
+  versions can ship side by side. See [`docs/releases/`](../releases/).
+- `memhouse status` lists every machine writing to your rooms, with the version each
+  last reported and when it last shipped. A machine that is behind is named there.
+- Machines that stopped writing long ago are folded into one line. That is history, not
+  a fault. `memhouse status --all` lists them.
+
+## When the house itself must change
+
+Some releases need the rooms rebuilt, for example when a sorting key changes. The shipper
+checks the rooms' keys before it writes, and **refuses** to write into a house it does not
+match, so an old house cannot be corrupted by a new shipper. To bring the house up to
+date:
+
+```bash
+memhouse migrate --dry-run   # what would run
+memhouse migrate             # copy, atomic swap; nothing is deleted
+memhouse doctor              # every line a check mark
+```
+
+A migration copies each room, swaps it in atomically, and keeps the old one as
+`<room>_pre_<migration>` for you to drop when you are satisfied. The house records the move
+in its `events` room, and `doctor` reads it back.
+
+## Upgrading from 0.9.x
+
+0.9.x predates migrations, and `update` runs the **old** version's code (it replaces itself
+mid-run), so it cannot prompt. After the upgrade, the first ship refuses (nothing is lost)
+and names the one command to run by hand: `memhouse migrate`.
+
+## Upgrading a pre-0.18 house (a database per member)
+
+0.18 moved every member's rooms into one database, as `mem.<member>_*`. An operator moves
+an old house once with `memhouse convert`; see [Operate a house](operate.md#convert). After
+that, members upgrade with `memhouse update`, and the shipper adopts the moved rooms
+itself.

package/docs/releases/README.md

@@ -0,0 +1,11 @@
+# Release notes
+
+One document per release, from 0.18.10 onward. Each says what changed, what you need to
+do, how to upgrade, what is deprecated and when it goes, and what was deferred.
+
+| version | date | headline |
+|---|---|---|
+| [0.18.11](v0.18.11.md) | 2026-10-10 | sessions with subagents stop re-shipping; security: no stored credential sent to `invite --url` |
+| [0.18.10](v0.18.10.md) | 2026-10-08 | security: the admin password never on argv; no member password printed; a scoped share reaches only its scope |
+
+Earlier versions: [`CHANGELOG.md`](../../CHANGELOG.md).