memhouse 0.17.0 → 0.18.1

package/memhouse/delivery/INVITATION.md.tpl

@@ -0,0 +1,147 @@
+# You have been invited to a memhouse
+
+{{INVITER}} set up a **house** — a ClickHouse database where a team keeps its coding-agent
+memory — and made you a member of it. This page walks you from the file you were sent to a
+working install, and shows what you get.
+
+You received two things:
+
+| file | what it is |
+|---|---|
+| `{{FILE}}` | **your credential**, in this same folder. One-time: install consumes it and deletes it. Treat it like a password until then. |
+| this page | the steps. Nothing secret in here. |
+
+Do it yourself, or hand this page to your coding agent. From the directory holding both
+files:
+
+```
+claude "Read MEMHOUSE-INVITATION.md and follow it. Ask me before each step that changes this machine."
+```
+
+Any agent that can run shell commands works the same way; the rules it must keep are at
+the end of this page.
+
+## 0. Find your credential
+
+The install needs `{{FILE}}`, which was sent alongside this page. Confirm it is here first —
+run this from the same directory, and if it prints the filename you are ready:
+
+```
+ls invite-*.env
+```
+
+If it is missing, it did not travel with this page; get it from whoever invited you before
+going on. Do not print its contents — the last line of it is a password.
+
+## 1. Install memhouse
+
+{{INSTALL}}
+
+On most Linux distros the global install needs `sudo`; if `npm` says `EACCES`, that is why.
+`memhouse --version` should print `{{VERSION}}`.
+
+## 2. Join the house
+
+From the directory holding `{{FILE}}`, just run memhouse — it finds the invitation and asks:
+
+```
+memhouse
+```
+
+(or, without the question: `memhouse install --env {{FILE}}`)
+
+What that does, in order: connects to `{{URL}}` as `{{NAME}}`, **rotates your password to
+one only your machine knows**, creates your rooms, writes your config to `~/.memhouse/env`,
+deletes `{{FILE}}`, and starts shipping in the background. The password in the file stops
+working the moment install finishes, so a copy left in a chat is dead.
+
+## 3. Check it is working
+
+```
+memhouse status      # your rooms, how much is in them, the shipper's pulse
+memhouse doctor      # every line a check mark = healthy
+memhouse discover    # what this machine ships, and where each editor's sessions were found
+```
+
+`memhouse status` shows a session count that grows for a few minutes on a machine with
+history; the first pass ships everything you have. After that it ships new turns as they
+happen.
+
+## 4. What you own, and who can see it
+
+Your memory lives in five tables named for you inside `{{DB}}` — `{{DB}}.{{NAME}}_messages`,
+`{{DB}}.{{NAME}}_sessions`, `{{DB}}.{{NAME}}_tool_calls` and two bookkeeping tables — and you
+hold exactly one grant, on `{{DB}}.{{NAME}}_*`. Housemates cannot read your rooms, list
+them, or grant them to anyone; you cannot read theirs. `memhouse whoami --json` reads that
+grant back from the server. What can always see everything is the account that administers
+the ClickHouse, which is {{INVITER}}'s — the same as any database you use at work.
+
+Everything your editors write to disk ships verbatim: prompts, replies, tool calls and their
+arguments, including anything an agent ever pasted into a session. The house is as
+sensitive as your shell history. If some of your work should not go there, say so before
+shipping — see "which sessions ship" below.
+
+## 5. Things to try
+
+```
+memhouse search "the error you fixed last week"
+memhouse resume <session-id>          # prints the command that reopens that session
+memhouse plugins install claude       # /mem:recall, /mem:sql, /mem:house, /mem:access, /mem:admin
+```
+
+Then, inside Claude Code:
+
+```
+/mem:recall how did I set up the ClickHouse tunnel
+/mem:sql what did I spend on Opus this month
+/mem:house
+```
+
+Sharing is yours to give and take back, no operator involved:
+
+```
+memhouse share <housemate>                       everything you own
+memhouse share <housemate> --only project=<name> one project
+memhouse share --list
+memhouse share <housemate> --revoke
+```
+
+## Which sessions ship
+
+Everything memhouse finds on the machine — every supported editor, every Claude Code
+config directory. `memhouse discover` lists what it found and the variable that narrows
+each one. Two lines in `~/.memhouse/env` are the common case:
+
+```
+MEMHOUSE_EDITORS='claude'
+MEMHOUSE_CLAUDE_ROOTS='~/.claude-playbooks/<the one instance you mean>'
+```
+
+## If something refuses
+
+Every refusal says what to do next. The two you might meet: `EACCES` on install means
+`sudo`, and `needed rights this credential does not hold` means the grant on the server is
+narrower than the one memhouse issues — ask {{INVITER}} to run `memhouse install --print-sql
+--member {{NAME}}` and apply what it prints.
+
+## For an agent following this page
+
+You are installing memhouse for the person who handed you this file. Five rules; three of
+them exist because an agent broke them:
+
+0. **Your credential is `{{FILE}}` in the directory this page is in.** If `Read
+   MEMHOUSE-INVITATION.md` is all you were given, `ls invite-*.env` beside it is the file
+   the steps refer to; confirm it is there before step 1.
+1. **Never print `{{FILE}}` or any `MEMHOUSE_*` value.** No `cat`, no `echo $MEMHOUSE_PASSWORD`,
+   no `set -x`. This very session will be shipped into the house; a password printed here is
+   a password archived.
+2. **Run the commands as written, in order.** Do not substitute `CREATE USER`, `GRANT` or any
+   SQL of your own; there is nothing to fix on the server from this side.
+3. **Ask before `memhouse install --env`.** It rotates the credential, deletes `{{FILE}}`,
+   and starts shipping this machine's transcripts. The person decides when that happens.
+4. **A ✗ line is the end of that step, not an invitation to work around it.** Read the line
+   after it — every refusal names its remedy — do that or report it. `sudo` for `EACCES` is
+   the one you may apply yourself.
+5. **Report what `memhouse status` and `memhouse doctor` say**, verbatim, when you are done.
+   A green install is those two commands, not your summary of them.
+

package/memhouse/delivery/PROMPT.md

@@ -36,11 +36,12 @@ FIRST. Only say you don't know after a search comes back empty.
 
 Without skills, query directly.
 
-**Table names.** The house's rooms are three plain, shared tables — `messages`,
-`sessions`, `tool_calls` — in the connection's database. Everyone in the house writes
-into the same tables; `user_id` (server-stamped) says whose row it is and `host` says
-which machine. Query the whole house by default; add `WHERE user_id = '<name>'` for one
-person. **There is no `sessions_v` object** — the rollup is a saved query, and
+**Table names.** The rooms are `messages`, `sessions`, `tool_calls` in the connection's
+database — unless this is a shared house, where they carry the member's own prefix
+(`alice_messages`). `memhouse rooms` prints what yours are actually called; a bare
+`FROM messages` is not a table you have in a shared house. `user_id` (server-stamped)
+says whose row it is and `host` says which machine. To read across several members, UNION ALL over the rooms you hold — naming a room
+you do not hold is an error rather than a silent omission. **There is no `sessions_v` object** — the rollup is a saved query, and
 `memhouse sessions-query` prints it ready to drop into a `FROM (...) AS c`.
 
 **One session can be stored more than once.** The shipper never deletes: when an editor

package/memhouse/delivery/kernel-install.md

@@ -80,8 +80,10 @@ user so the stamp cannot be skipped). Her machines are told apart by `host`.
 **A house is shared by its housemates.** The tables are common; `user_id` and `host` say
 who wrote what, and `WHERE user_id = 'alice'` is one person. The boundary is the
 DATABASE: a member of `mem` holds nothing on any other database, so two agencies on one
-kernel ClickHouse cannot read each other. The model is collaborative — housemates trust
-each other with the house; a separate house is the isolation mechanism.
+kernel ClickHouse cannot read each other. WITHIN a house, members hold their own rooms
+and nothing else — housemates are isolated from each other by grant, not by trust, and
+each can verify it with `SHOW GRANTS`. A separate house remains the boundary between
+groups that should not know of each other at all.
 
 Row policies are still the only way to share a *subset* of rows, which is owner-mediated
 and documented in `SHARING.md` — they are not how isolation works.

package/memhouse/delivery/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mem",
   "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: recall past sessions and answer from them, run analytics, check the house, bring people in, and administer the server. Skills install as /mem:recall, /mem:sql, /mem:house, /mem:access, and /mem:admin.",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "author": {
     "name": "Ramazan Polat"
   },

package/memhouse/delivery/plugin/reference/HOUSE.md

@@ -8,13 +8,20 @@ or wrong everywhere.
 
 ## What this is
 
-A **house** is a ClickHouse **database**. Its **rooms** are three shared tables:
-`sessions`, `messages`, `tool_calls`. Everyone granted on the database writes into the
-same tables; the server stamps who. There is no per-user table and no cloud — the
-database *is* the boundary, and a house's grants reach nothing outside it.
+A **house** is a ClickHouse **database** — on the user's machine, their server, or a
+hosted ClickHouse; memhouse runs no service of its own. Its **rooms** are tables —
+`sessions`, `messages`, `tool_calls` — and the server stamps who wrote every row. A
+house's grants reach nothing outside it.
 
-A **member** owns one house. An **administrator** owns the ClickHouse. `memhouse whoami`
-says which you are holding.
+Every member's rooms are named for them — `mem.alice_messages`, `mem.alice_sessions`,
+`mem.alice_tool_calls` — and one grant covers exactly those: `ON mem.alice_*`. Housemates
+keep their own rooms beside yours and cannot read them, list them, or grant them onward;
+you cannot read theirs. `SHOW GRANTS` shows you the one line you hold. **A bare
+`FROM messages` names nothing you have** — the `q()` below prefixes room names with your
+member name for you, and `memhouse rooms` prints what yours are called.
+
+An **operator** owns the ClickHouse itself; an **admin credential** is what proves it.
+`memhouse whoami` says which you are holding.
 
 Rows arrive from a **shipper** that parses local transcripts from 17 editors. It only
 ever inserts. Nothing in memhouse runs an LLM over your data — these skills retrieve
@@ -29,6 +36,13 @@ rows, and *you* read them.
 memhouse ships back into the house — the archive is insert-only, so a leaked credential
 cannot be withdrawn.
 
+**Which memhouse.** `plugins install` stamps two variables into this config directory's
+`settings.json`, so every session here carries them: `MEMHOUSE_HOME` is the instance whose
+house these skills read, and `MEMHOUSE_BIN` is that instance's binary. **Every `memhouse …`
+command in these skills means `"${MEMHOUSE_BIN:-memhouse}"`.** A machine can run two
+instances on two channels; the bare name would be whichever the shell found first. Do not
+override either variable.
+
 Credentials resolve **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`** (default
 `~/.memhouse/env`) — the same order the CLI uses. The dance below snapshots the
 environment first, because sourcing the file would otherwise clobber an already-exported
@@ -45,7 +59,8 @@ if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
 fi
 
 q() {  # read-only by construction; every read path should use this
-  curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  sed -E "s/([[:space:](]|^)(FROM|JOIN)[[:space:]]+(sessions|messages|tool_calls|meta|events)([[:space:];,)]|\$)/\1\2 ${MEMHOUSE_USER}_\3\4/g" \
+  | curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
     --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&readonly=1"
 }
 q <<'SQL'
@@ -56,11 +71,22 @@ SQL
 `readonly=1` is a ClickHouse-side setting: even a mis-generated `DROP` is refused by the
 server, not by discipline.
 
-**Reading someone else's house.** A share is a read-only `GRANT SELECT` on their
-database. `SHOW DATABASES` lists what your credential may read; anything that is not
-`system`, `information_schema`, `default` or your own `$MEMHOUSE_DB` was shared with you.
-To read it, change `database=` in the URL and leave the table names bare. Say whose house
-an answer came from.
+**The `sed` is what makes every query below work in both layouts** — write room names
+bare and it supplies the prefix when there is one. It rewrites only after `FROM`/`JOIN`,
+so a needle like `LIKE '%messages%'` is untouched, and `FROM yigit_messages` is left
+alone — the room name must follow whitespace, and there is none inside `yigit_messages`.
+With no prefix set it expands to nothing and the query passes through verbatim.
+
+It is spelled with `[[:space:]]` classes rather than `\b` because **BSD `sed` does not
+support `\b`**: on macOS the `\b` form matched nothing and sent the query through
+unprefixed. That fails loudly as `UNKNOWN_TABLE` rather than quietly reading wrong rows,
+which is the right way round — but it fails.
+
+**Reading a housemate's memory.** A share is `GRANT SELECT ON mem.<them>_*` — their
+rooms, not the database. `SHOW TABLES` lists exactly what you may read: your own rooms plus
+any shared with you. Name a housemate's rooms in full (`FROM yigit_messages`); the `q()`
+rewrite leaves an already-prefixed name alone, since applying yours would point at the
+wrong rooms. Say whose memory an answer came from.
 
 ---
 

package/memhouse/delivery/plugin/skills/access/SKILL.md

@@ -26,7 +26,7 @@ This runs the `memhouse invite` CLI and nothing else. **Do not hand-run `CREATE
 `GRANT` with an admin password substituted into a command** — that burns the credential
 into a transcript on disk. The CLI passes it to one process and never echoes it.
 
-1. **Check the binary:** `command -v memhouse`. Absent → tell the user to
+1. **Check the binary:** `command -v "${MEMHOUSE_BIN:-memhouse}"`. Absent → tell the user to
    `npm install -g memhouse`. There is no in-skill fallback, on purpose.
 
 2. **Gather only two things:** the invitee's **name** (validate `[A-Za-z][A-Za-z0-9_]*`;
@@ -84,13 +84,13 @@ into a transcript on disk. The CLI passes it to one process and never echoes it.
 5. **Say whether the house was fresh** — `SELECT count() FROM <db>.messages` reads 0 for a
    new one. Second line of defence behind step 3's refusal.
 
-6. **Write the message the user will send.** They are handing over a file plus an
-   explanation; compose it rather than making them. Cover: what memhouse is in a sentence
-   or two; that the attached file IS a password (do not forward, do not paste in chat);
-   `npm install -g memhouse` (Node 24+) then `memhouse install --env invite-<name>.env`;
-   that install offers to change the password to one only they know and then deletes the
-   file, so they should say yes; `memhouse onboard` to start shipping and `memhouse status`
-   to check; and that their house is theirs alone unless they run `/mem:access share`.
+6. **Write the message the user will send.** `invite` wrote TWO files beside each other:
+   `invite-<name>.env` (the credential, one-time) and `MEMHOUSE-INVITATION.md` (the steps,
+   nothing secret — install, verify, what they own, things to try). The guide does the
+   explaining, so the message is short: what memhouse is in a sentence; that the `.env` IS a
+   password (do not forward, do not paste in chat); open `MEMHOUSE-INVITATION.md` and follow
+   it. If `memhouse --version` shows a pre-release (a `-` in it), the invitee also needs the
+   tarball this build came from (`memhouse nightly --out …`); the guide says so and names it.
 
    If they are REPLACING an existing credential, add `memhouse ship --full` — a plain
    incremental pass skips sessions the new house has no record of, so their history would
@@ -105,7 +105,7 @@ for this** — partial sharing has four ways to go wrong quietly, and the comman
 each one:
 
 ```
-memhouse share <user>                          the whole house
+memhouse share <user>                          everything you own
 memhouse share <user> --only project=memhouse  just one project
 memhouse share <user> --only session=<id>      just one conversation
 memhouse share --list                          who can read it, and how much

package/memhouse/delivery/plugin/skills/admin/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash
 
 # /mem:admin — operate the house as its administrator
 
-A member owns one database. An **administrator** owns the ClickHouse: every house, every
+A member owns a house, or rooms in one. An **administrator** owns the ClickHouse: every house, every
 account, every grant. This skill is the second one, and it is the only skill allowed to
 act outside the caller's own house.
 

package/memhouse/delivery/plugin/skills/house/SKILL.md

@@ -32,6 +32,22 @@ stop:
 > `memhouse deploy --local` stands one up bound to loopback. Someone invited you?
 > `memhouse install --env invite-<you>.env`.
 
+## First: which memhouse this is
+
+Before anything else, run and show verbatim:
+
+```
+"${MEMHOUSE_BIN:-memhouse}" instance
+```
+
+One screen: the instance's name and home, the binary and channel, the house (server,
+database, member, whether an admin credential is present), the five rooms with row counts,
+what this machine ships, the host identity, the daemons, and which playbooks are bound to
+this instance. A machine can run several instances on different channels; this is how the
+user tells them apart, and how you know which house every answer below comes from. If the
+instance shown is not the one the user meant, stop and say so — the fix is launching
+under the right playbook, not overriding variables.
+
 ## The report
 
 Lead with the one-line verdict — *working and current*, *working but stale*, or *not
@@ -83,12 +99,12 @@ thin. Say what could not be seen rather than guessing.
 SHOW DATABASES
 -- who you have granted (memhouse's own record of it)
 SELECT substring(key, 7) AS user, value AS state
-FROM house_meta FINAL WHERE key LIKE 'share:%' ORDER BY key
+FROM meta FINAL WHERE key LIKE 'share:%' ORDER BY key
 -- everyone on the server (names only — every member holds SHOW USERS)
 SELECT name FROM system.users ORDER BY name
 ```
 
-That `house_meta` list is memhouse's own note-keeping, not ClickHouse's grant table —
+That `meta` list is memhouse's own note-keeping, not ClickHouse's grant table —
 a member cannot read `system.grants`. Present it as "what memhouse recorded", and say
 that a grant made by hand would not appear.
 

package/memhouse/flags.js

@@ -16,16 +16,17 @@ const COMMAND_FLAGS = {
   null: [], help: [], version: [],
   whoami: ['admin'],
   share: ['only', 'revoke', 'list'],
-  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [],
+  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], instance: [], members: ['db','admin-user','admin-password'],
   status: [], start: [],
   onboard: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'target', 'house-port', 'tag', 'local'],
   install: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'env', 'print-sql', 'member',
-    'member-password', 'admin-user', 'admin-password', 'ensure-schema', 'rotate-password', 'force'],
-  setup: ['url', 'user', 'password', 'db', 'port'],
+    'member-password', 'admin-user', 'admin-password', 'ensure-schema', 'rotate-password', 'force',
+    'editors', 'claude-roots', 'channel'],
+  setup: ['url', 'user', 'password', 'db', 'port', 'admin-user', 'admin-password', 'editors', 'claude-roots', 'channel'],
   ship: ['full', 'loop', 'ensure-schema'],
   search: ['limit'],
   resume: [],
-  update: ['check', 'migrate', 'no-install'],
+  update: ['check', 'migrate', 'no-install', 'channel'],
   reset: ['all-origins'],
   invite: ['url', 'db', 'out', 'admin-user', 'admin-password', 'adopt', 'print-sql',
     'allow-local', 'member-password'],

package/memhouse/house/HOUSE.md

@@ -1,12 +1,18 @@
-# The house — a database, three shared rooms
+# The house — a database, and the rooms in it
 
 **A house is a ClickHouse database.** Any database, named whatever its people name it —
-`polat`, `team_a`, even `default`. Its rooms are three plain tables: `sessions`,
-`messages`, `tool_calls`. There is nothing else to provision: no per-member tables, no
-Merge rooms, no views, no settings profile.
+`polat`, `team_a`, even `default`. Its rooms are tables: `sessions`, `messages`,
+`tool_calls`. No views, no Merge rooms, no settings profile.
 
-**Everyone in the house writes into the same tables**, each with their own credential,
-and two columns say where every row came from:
+**Every member's rooms are named for them, and one grant covers them.** `mem.polat_*`
+for polat, `mem.alice_*` for alice, in the same database — `mem` unless somebody has a
+reason. The grant is `GRANT … ON mem.polat_* TO polat WITH GRANT OPTION`: it lets the
+member create and rebuild their own rooms, share them, and reach nothing else. Nobody is
+granted the database itself. A house with one member is a house of one, not a different
+kind of house — a colleague joins as one more member and nothing about the first changes.
+`roomNames()` in `house.js` is the only place a table name is produced.
+
+Two columns say where every row came from:
 
 | Column | Meaning | Comes from |
 |---|---|---|
@@ -31,9 +37,17 @@ shipper create and evolve the rooms (`ship.js --ensure-schema`) — no admin has
 memhouse code. Joining a ClickHouse that happens to run a kernel is the same three
 statements: a database and a credential, nothing else.
 
-The model is **collaborative**: housemates trust each other with the house. Narrower
-grants can be layered on later if a team wants them; the isolation mechanism between
-groups that do NOT trust each other is a separate house.
+**Housemates do not have to trust each other with the house.** They used to: everyone
+held `ALL` on the database, and the isolation mechanism between parties who should not
+see each other was a separate house. That shape leaked — one member could `GRANT SELECT
+ON db.* TO <outsider>` and hand over a housemate's transcripts, with no admin and no
+notification.
+
+In a shared house each member is granted their own rooms and nothing else, so isolation
+lives INSIDE one house and is checkable: `SHOW GRANTS` lists what you hold, and `SHOW
+TABLES` does not list what you do not. A separate house is still the boundary between
+groups that should not even know of each other — names leak across a shared house even
+when content does not.
 
 ## One user on two machines, same session id
 
@@ -91,9 +105,9 @@ for writes and DDL.
 
 Two tables that are not rooms:
 
-- `house_meta` — house-wide key/value, latest-wins: `schema_version`, and the memhouse
+- `meta` — house-wide key/value, latest-wins: `schema_version`, and the memhouse
   version each member last shipped with.
-- `house_events` — append-only: migrations (`pending` → `applied` | `failed`), version
+- `events` — append-only: migrations (`pending` → `applied` | `failed`), version
   changes, schema observations, each with actor, host and row counts. Nothing is updated
   in place, so a migration that failed and was retried reads as exactly that.