memhouse 0.17.0 → 0.18.0

package/editors/antigravity.js

@@ -1,5 +1,6 @@
 const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
+const scope = require('./scope');
 const path = require('path');
 const os = require('os');
 const { openReadOnly, textOf } = require('./sqlite');
@@ -10,6 +11,7 @@ const HOME = os.homedir();
 const ANTIGRAVITY_USER_DIR = path.join(getAppDataPath('Antigravity'), 'User');
 const ANTIGRAVITY_GLOBAL_STORAGE_DB = path.join(ANTIGRAVITY_USER_DIR, 'globalStorage', 'state.vscdb');
 const ANTIGRAVITY_BRAIN_DIR = path.join(HOME, '.gemini', 'antigravity', 'brain');
+scope.fixed('antigravity', [ANTIGRAVITY_USER_DIR, ANTIGRAVITY_BRAIN_DIR]);
 const OFFLINE_TRAJECTORY_SUMMARIES_KEYS = [
   'antigravityUnifiedStateSync.trajectorySummaries',
   'unifiedStateSync.trajectorySummaries',

package/editors/claude.js

@@ -36,7 +36,9 @@ function discoverClaudeRoots() {
     seen.add(rp);
     roots.push(d);
   }
-  return roots;
+  // MEMHOUSE_CLAUDE_ROOTS replaces discovery with an explicit list — one Claude Code
+  // instance out of several on a machine. Each path is checked the same way as above.
+  return require('./scope').roots('claude', roots, process.env.MEMHOUSE_CLAUDE_ROOTS);
 }
 
 // ============================================================

package/editors/codebuff.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
@@ -29,6 +30,7 @@ function getProjectRoots() {
   }
   return roots;
 }
+scope.fixed('codebuff', getProjectRoots().map((r) => r.projectsDir));
 
 function safeReadJson(filePath) {
   try { return JSON.parse(fs.readFileSync(filePath, 'utf-8')); } catch { return null; }

package/editors/codex.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
@@ -33,11 +34,13 @@ function getMessages(chat) {
   return parseSessionMessages(filePath);
 }
 
-function getCodexHome() {
+function getCodexHomeDefault() {
   return process.env.CODEX_HOME && process.env.CODEX_HOME.trim()
     ? path.resolve(process.env.CODEX_HOME.trim())
     : DEFAULT_CODEX_HOME;
 }
+// CODEX_HOME is Codex's own variable; MEMHOUSE_CODEX_ROOTS is memhouse's, and wins.
+function getCodexHome() { return scope.root('codex', getCodexHomeDefault()); }
 
 function getSessionsDir() {
   return path.join(getCodexHome(), SESSION_SUBDIR);

package/editors/commandcode.js

@@ -1,8 +1,9 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
-const COMMANDCODE_DIR = path.join(os.homedir(), '.commandcode');
+const COMMANDCODE_DIR = scope.root('commandcode', path.join(os.homedir(), '.commandcode'));
 const PROJECTS_DIR = path.join(COMMANDCODE_DIR, 'projects');
 
 // ============================================================

package/editors/copilot-jetbrains.js

@@ -1,8 +1,9 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
-const JB_DIR = path.join(os.homedir(), '.copilot', 'jb');
+const JB_DIR = scope.root('copilot-jetbrains', path.join(os.homedir(), '.copilot', 'jb'));
 
 // ============================================================
 // Adapter interface

package/editors/copilot.js

@@ -1,8 +1,9 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
-const COPILOT_DIR = path.join(os.homedir(), '.copilot');
+const COPILOT_DIR = scope.root('copilot-cli', path.join(os.homedir(), '.copilot'));
 const SESSION_STATE_DIR = path.join(COPILOT_DIR, 'session-state');
 
 // ============================================================

package/editors/cursor-agent.js

@@ -1,8 +1,9 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
-const CURSOR_PROJECTS_DIR = path.join(os.homedir(), '.cursor', 'projects');
+const CURSOR_PROJECTS_DIR = scope.root('cursor-agent', path.join(os.homedir(), '.cursor', 'projects'));
 
 // ============================================================
 // Adapter interface

package/editors/cursor.js

@@ -1,5 +1,6 @@
 const { openReadOnly, textOf, bytesOf } = require('./sqlite');
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 const { getAppDataPath } = require('./base');
@@ -10,6 +11,7 @@ const CURSOR_CHATS_DIR = path.join(HOME, '.cursor', 'chats');
 const CURSOR_USER_DIR = path.join(getAppDataPath('Cursor'), 'User');
 const WORKSPACE_STORAGE_DIR = path.join(CURSOR_USER_DIR, 'workspaceStorage');
 const GLOBAL_STORAGE_DB = path.join(CURSOR_USER_DIR, 'globalStorage', 'state.vscdb');
+scope.fixed('cursor', [CURSOR_USER_DIR, CURSOR_CHATS_DIR]);
 
 // ============================================================
 // Source 1: ~/.cursor/chats/<hash>/<chatId>/store.db (agent KV)

package/editors/gemini.js

@@ -1,8 +1,9 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
-const GEMINI_DIR = path.join(os.homedir(), '.gemini');
+const GEMINI_DIR = scope.root('gemini-cli', path.join(os.homedir(), '.gemini'));
 const TMP_DIR = path.join(GEMINI_DIR, 'tmp');
 const PROJECTS_JSON = path.join(GEMINI_DIR, 'projects.json');
 

package/editors/goose.js

@@ -1,11 +1,12 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
 const { openReadOnly, textOf } = require('./sqlite');
 const adapterErrors = require('./adapter-errors');
 
-const GOOSE_DIR = path.join(os.homedir(), '.local', 'share', 'goose', 'sessions');
+const GOOSE_DIR = scope.root('goose', path.join(os.homedir(), '.local', 'share', 'goose', 'sessions'));
 const DB_PATH = path.join(GOOSE_DIR, 'sessions.db');
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'goose', 'config.yaml');
 

package/editors/index.js

@@ -15,6 +15,7 @@ const goose = require('./goose');
 const kiro = require('./kiro');
 const codebuff = require('./codebuff');
 const adapterErrorSink = require('./adapter-errors');
+const scope = require('./scope');
 
 const editors = [cursor, devin, antigravity, claude, vscode, zed, opencode, codex, gemini, copilot, copilotJetbrains, cursorAgent, commandcode, goose, kiro, codebuff];
 
@@ -47,7 +48,13 @@ function getAllChats() {
   const chats = [];
   adapterErrors = [];
   adapterErrorSink.reset();
-  for (const editor of editors) {
+  // MEMHOUSE_EDITORS narrows which adapters run; an unknown name throws rather than
+  // shipping nothing (or everything) behind a typo. See scope.js.
+  for (const editor of scope.selectEditors(editors, process.env.MEMHOUSE_EDITORS)) {
+    // A refused MEMHOUSE_<EDITOR>_ROOTS is recorded at load; surface it here as this
+    // adapter's error and skip it, rather than letting it scan nowhere and report zero.
+    const w = scope.watching().find((x) => x.name === editor.name);
+    if (w && w.error) { adapterErrors.push({ source: editor.name, message: w.error }); continue; }
     try {
       const editorChats = editor.getChats();
       chats.push(...editorChats);

package/editors/kiro.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 const { getAppDataPath } = require('./base');
@@ -9,9 +10,9 @@ const { getAppDataPath } = require('./base');
 
 const name = 'kiro';
 
-const KIRO_AGENT_DIR = path.join(
+const KIRO_AGENT_DIR = scope.root('kiro', path.join(
   getAppDataPath('Kiro'), 'User', 'globalStorage', 'kiro.kiroagent'
-);
+));
 const WORKSPACE_SESSIONS_DIR = path.join(KIRO_AGENT_DIR, 'workspace-sessions');
 
 function getChats() {

package/editors/opencode.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 const { openReadOnly, textOf } = require('./sqlite');
@@ -6,7 +7,7 @@ const adapterErrors = require('./adapter-errors');
 
 // OpenCode stores data in XDG-style paths across all platforms
 function getOpenCodeStoragePath() {
-  return path.join(os.homedir(), '.local', 'share', 'opencode', 'storage');
+  return scope.root('opencode', path.join(os.homedir(), '.local', 'share', 'opencode', 'storage'));
 }
 
 const STORAGE_DIR = getOpenCodeStoragePath();

package/editors/scope.js

@@ -0,0 +1,126 @@
+// Which of this machine's sessions ship — the scope.
+//
+// By default every adapter runs and the Claude adapter reads every config directory it
+// can find (~/.claude and each ~/.claude-playbooks/<name>). A machine that keeps several
+// Claude Code instances, or an operator who wants one instance's memory in a team house
+// and the rest of their work elsewhere, needs to say which. Two knobs, both plain text in
+// the env file so a person can read what a house will receive:
+//
+//   MEMHOUSE_EDITORS          comma-separated adapter names: `claude`, `codex`, …  Empty = all.
+//   MEMHOUSE_<EDITOR>_ROOTS   the directory that adapter reads instead of its default —
+//                             MEMHOUSE_CODEX_ROOTS='~/work/.codex'. The name is the adapter's,
+//                             upper-cased, dashes to underscores: MEMHOUSE_GEMINI_CLI_ROOTS.
+//                             Claude is the one adapter with MANY roots (each Claude Code
+//                             config dir); every other adapter has one store, so one path.
+//
+// `memhouse discover` prints, per adapter, what it is watching and the variable that
+// changes it. Adapters register here at load, so the list is what actually ran.
+//
+// Both FAIL LOUDLY on a name or path that does not exist. A typo that silently shipped
+// nothing would look like a working install with an empty house; one that silently
+// shipped everything would defeat the point of setting it.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function parseList(value) {
+  return String(value || '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/** The adapters that should run, in the order given. */
+function selectEditors(editors, value) {
+  const wanted = parseList(value);
+  if (!wanted.length) return editors;
+  const byName = new Map(editors.map((e) => [e.name, e]));
+  const unknown = wanted.filter((n) => !byName.has(n));
+  if (unknown.length) {
+    throw new Error(`MEMHOUSE_EDITORS names an adapter that does not exist: ${unknown.join(', ')}. `
+      + `Known: ${editors.map((e) => e.name).join(', ')}`);
+  }
+  return wanted.map((n) => byName.get(n));
+}
+
+function expandHome(p) {
+  return p === '~' ? os.homedir() : p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+/**
+ * The Claude roots to read. With nothing set, the discovered list as-is. With a list set,
+ * exactly those directories — each must exist and hold a `projects/` dir or a
+ * `history.jsonl`, the same test discovery applies, so a path that is real but not a
+ * Claude config dir is refused rather than silently contributing nothing.
+ */
+function selectClaudeRoots(discovered, value, { exists = fs.existsSync, isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } } } = {}) {
+  const wanted = parseList(value).map(expandHome);
+  if (!wanted.length) return discovered;
+  const bad = [];
+  for (const r of wanted) {
+    if (!isDir(r)) { bad.push(`${r} (not a directory)`); continue; }
+    if (!isDir(path.join(r, 'projects')) && !exists(path.join(r, 'history.jsonl'))) bad.push(`${r} (no projects/ and no history.jsonl — not a Claude Code config dir)`);
+  }
+  if (bad.length) throw new Error(`MEMHOUSE_CLAUDE_ROOTS: ${bad.join('; ')}`);
+  return wanted;
+}
+
+/** One line for status/discover: what this install ships, or 'everything'. */
+function describe(env = process.env) {
+  const parts = [];
+  if (parseList(env.MEMHOUSE_EDITORS).length) parts.push(`editors: ${parseList(env.MEMHOUSE_EDITORS).join(', ')}`);
+  for (const k of Object.keys(env).filter((k) => /^MEMHOUSE_[A-Z_]+_ROOTS$/.test(k)).sort()) {
+    if (parseList(env[k]).length) parts.push(`${k.slice(9, -6).toLowerCase().replace(/_/g, '-')} roots: ${parseList(env[k]).join(', ')}`);
+  }
+  return parts.length ? parts.join('; ') : 'everything this machine has';
+}
+
+/** The env variable that overrides an adapter's root(s). */
+function keyFor(name) { return `MEMHOUSE_${String(name).toUpperCase().replace(/-/g, '_')}_ROOTS`; }
+
+const isDirFs = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+/**
+ * Pure core for a single-store adapter: the override if one is set, else the default.
+ * An override must be exactly one existing directory. Errors are RETURNED, not thrown, so
+ * a bad value for one adapter skips that adapter with its reason and never takes the other
+ * sixteen down with it at module load.
+ */
+function selectRoot(dflt, value, { isDir = isDirFs } = {}) {
+  const wanted = parseList(value).map(expandHome);
+  if (!wanted.length) return { root: dflt, error: null };
+  if (wanted.length > 1) return { root: null, error: `reads one directory, ${wanted.length} given` };
+  if (!isDir(wanted[0])) return { root: null, error: `${wanted[0]} is not a directory` };
+  return { root: wanted[0], error: null };
+}
+
+// What each adapter is watching, recorded as adapters load. `key` is null for an adapter
+// whose location is not overridable yet; `error` is why an override was refused.
+const watched = new Map();
+const NOWHERE = path.join(os.tmpdir(), 'memhouse-scope-refused-' + process.pid);
+
+function root(name, dflt, env = process.env) {
+  const key = keyFor(name);
+  const { root: r, error } = selectRoot(dflt, env[key]);
+  watched.set(name, { roots: [error ? null : r].filter(Boolean), key, error: error ? `${key}: ${error}` : null });
+  return error ? NOWHERE : r;
+}
+
+function roots(name, defaults, value, opts) {
+  const key = keyFor(name);
+  try {
+    const r = selectClaudeRoots(defaults, value, opts);
+    watched.set(name, { roots: r, key, error: null });
+    return r;
+  } catch (e) {
+    watched.set(name, { roots: [], key, error: String(e.message || e) });
+    throw e;
+  }
+}
+
+/** Register an adapter whose location is built in and not (yet) overridable. */
+function fixed(name, dirs) { watched.set(name, { roots: dirs.filter(Boolean), key: null, error: null }); }
+
+function watching() {
+  return [...watched.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, w]) => ({ name, ...w }));
+}
+
+module.exports = { parseList, selectEditors, selectClaudeRoots, selectRoot, expandHome, describe, keyFor, root, roots, fixed, watching };

package/editors/vscode.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 const { getAppDataPath } = require('./base');
@@ -14,6 +15,7 @@ const VARIANTS = [
     appSupport: getAppDataPath('Code - Insiders'),
   },
 ];
+scope.fixed('vscode', VARIANTS.map((v) => v.appSupport));
 
 // ============================================================
 // JSONL reconstruction: kind:0 = init, kind:1 = patch at key path

package/editors/zed.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const scope = require('./scope');
 const fs = require('fs');
 const os = require('os');
 
@@ -21,7 +22,7 @@ function getZedDataPath() {
   }
 }
 
-const THREADS_DB = path.join(getZedDataPath(), 'threads', 'threads.db');
+const THREADS_DB = path.join(scope.root('zed', getZedDataPath()), 'threads', 'threads.db');
 
 // ============================================================
 // Decompress zstd blob via CLI (with cross-platform support)

package/memhouse/DESIGN.md

@@ -5,12 +5,35 @@ on your machines — across **all 17 editors** agentlytics supports — parsed l
 shipped to a typed ClickHouse store, shareable with a team, installable on the
 ultimagent kernel as an **agency**, and visible through the agentlytics dashboard.
 
-**A house is a database; its rooms are three shared tables** — `sessions`, `messages`,
-`tool_calls`. Everyone in the house writes into the same tables with their own
-credential; the server-stamped `user_id` says who, the install fingerprint `host` says
-which machine. Sharing IS the house; the boundary between groups is the database. (The
-layout has moved twice: shared-tables-with-row-policies fell in 0.4.0, per-member
-suffixed rooms fell in 0.8.0 — see `house/HOUSE.md` for why.)
+**A house is a database; its rooms are tables** — `sessions`, `messages`, `tool_calls`.
+The server-stamped `user_id` says who wrote a row, the install fingerprint `host` says
+which machine.
+
+**What a member owns inside a house is the layout's whole question, and it has three
+answers, two of them retired.** Shared tables with row policies fell in 0.4.0 (policies
+are permissive and OR'd — a catch-all fails OPEN). Per-member suffixed rooms fell in
+0.8.0, on the argument that isolation between housemates solved an adversarial problem
+the product did not have. That argument was wrong, and the counter-example is measured:
+with everyone holding `ALL ON db.* WITH GRANT OPTION`, one member ran
+`GRANT SELECT ON db.* TO <outsider>` and handed over a housemate's transcripts — no
+admin, no notification.
+
+So the layout today is per-member rooms again, prefixed rather than suffixed, and this
+time there is only one of it: **every member's rooms are named for them, and one wildcard
+grant — `ON mem.<name>_*` — is the whole of what they hold.** Nobody is granted the
+database. A house with one member is a house of one, not a different layout; standalone,
+team and kernel are the same statements. `roomNames()` in `house/house.js` is the only
+place a table name is produced and `provision.js` the only description of the grant.
+
+The two objections that retired the 0.8.0 layout were real and are paid again here:
+clients must resolve names before querying (`memhouse rooms`, and the `q()` helper the
+skills route through), and reading across members needs a `UNION ALL` rather than one
+table. Both are cheaper than the leak.
+
+**Why grants and not policies.** A grant is something a colleague can verify for
+themselves — `SHOW GRANTS` lists their rooms, and `SHOW TABLES` does not show them what
+they were not granted. "Trust the row policy protecting your rows" is a sentence you
+cannot ask a teammate to accept when "here are your grants, check them" is available.
 
 **Agency, precisely.** In constellation terms (`../TERMINOLOGY.md`) memhouse is a
 **house** — the `mem` database — **plus a resident**: the shipper. That pairing
@@ -60,7 +83,7 @@ them free and further along; **bet 3 is the one nobody else attempts.**
    write axis this bet is precisely *moving work from routine to resident*:
    memory-house parses when you query, memhouse parses before anyone asks and
    writes the result down.
-2. **Typed common schema** (`house/schema.sql.tpl` — three shared tables per house).
+2. **Typed common schema** (`house/schema.sql.tpl` — the rooms, rendered per member).
    Physical typed columns (what memory-house derives in views) + `tool_calls`
    (memory-house has no tool table) + one `extra JSON` escape hatch per room so
    unnormalized adapter fields are never lost. `ReplacingMergeTree(ingested_at)`;
@@ -84,7 +107,7 @@ them free and further along; **bet 3 is the one nobody else attempts.**
 | Path | What | Notes |
 |---|---|---|
 | `house/house.js` | room names + the session rollup + the user pin | one rule for both transports |
-| `house/schema.sql.tpl` | the house's three shared tables (typed) | applied by each member's own shipper |
+| `house/schema.sql.tpl` | the rooms (typed) | applied by the member's shipper, or by the operator at invite in a shared house |
 | `house/HOUSE.md` | the model, and what it replaced | |
 | `shipper/ship.js` | parse-on-client shipper CLI — the resident (`worker`) | reuses `../../editors`; incremental; idempotent |
 | `server/server.js` | REST API + dashboard | same API contract as agentlytics; serves `../../public` |

package/memhouse/channel.js

@@ -0,0 +1,50 @@
+// Which npm channel this install follows, and what `memhouse update` may move it to.
+//
+// `update` used to install `memhouse@latest`, full stop. That is right for a house that
+// tracks the published release and wrong for every other kind of install: a build
+// published under another dist-tag (`memhouse@team`, so a team on a newer layout does not
+// drag every other house along) would be DOWNGRADED to latest on its next update, and a
+// tarball install has no tag at all and would be replaced by whatever latest is.
+//
+// So the channel is resolved, in this order:
+//   1. pinned — MEMHOUSE_CHANNEL in the env file, or --channel on the command line
+//   2. inferred — the dist-tag whose version equals the one installed (latest preferred)
+//   3. a pre-release version matching no tag is a tarball: no automatic update at all
+//   4. otherwise latest
+// Pure, so the decision is unit-tested against every shape of registry answer.
+
+function isPrerelease(version) { return /-/.test(String(version || '')); }
+
+/**
+ * @param {{version:string, pinned?:string|null, tags:Record<string,string>|null}} p
+ * @returns {{channel:string|null, target:string|null, reason:string}}
+ */
+function pickChannel({ version, pinned = null, tags = null }) {
+  const t = tags || {};
+  if (pinned) {
+    return t[pinned]
+      ? { channel: pinned, target: t[pinned], reason: `pinned by MEMHOUSE_CHANNEL` }
+      : { channel: pinned, target: null, reason: `pinned to '${pinned}', which is not a tag on the registry${tags ? '' : ' (or the registry did not answer)'}` };
+  }
+  const matching = Object.entries(t).filter(([, v]) => v === version).map(([k]) => k);
+  if (matching.includes('latest')) return { channel: 'latest', target: t.latest, reason: 'installed version is latest' };
+  if (matching.length) return { channel: matching[0], target: t[matching[0]], reason: `installed version is published as '${matching[0]}'` };
+  if (isPrerelease(version)) {
+    return { channel: null, target: null, reason: `${version} is on no registry tag — a tarball or checkout build; update it by installing a newer tarball, or pin a channel: memhouse update --channel <tag>` };
+  }
+  return { channel: 'latest', target: t.latest || null, reason: tags ? 'following latest' : 'following latest (registry did not answer)' };
+}
+
+/** The registry's dist-tags, or null when it cannot be reached. Abbreviated document, small. */
+async function fetchTags(fetchImpl = globalThis.fetch) {
+  try {
+    const res = await fetchImpl('https://registry.npmjs.org/memhouse', {
+      headers: { accept: 'application/vnd.npm.install-v1+json' }, signal: AbortSignal.timeout(8000),
+    });
+    if (!res.ok) return null;
+    const j = await res.json();
+    return j && j['dist-tags'] ? j['dist-tags'] : null;
+  } catch { return null; }
+}
+
+module.exports = { pickChannel, fetchTags, isPrerelease };

package/memhouse/delivery/AGENT-INSTALL-PROMPT.md

@@ -43,7 +43,8 @@ already exist.
 - If a command fails, read what it printed before retrying. memhouse's failures name the
   cause and usually name the fix — it is not a generic tool that fails generically.
 - The house's rooms are three PLAIN, SHARED tables — `sessions`, `messages`,
-  `tool_calls` — in the connection's database. No suffixes, no per-member tables.
+  `tool_calls` — in the connection's database, carrying your own prefix if this is a
+  shared house (`alice_messages`). `memhouse rooms` prints what yours are called.
   Direct reads of `messages`/`tool_calls` must filter to the current parse (the shipper
   retains superseded parses under an `epoch` column); the installed skills carry the
   filter, so prefer them for queries.

package/memhouse/delivery/AGENT-INSTALL.md

@@ -87,7 +87,7 @@ no longer exists, so anything named here is a single editor's own store (locked
 running editor, corrupt, or on a schema this parser does not know).
 
 `stats` should show one row per source (claude-code, codex, gemini-cli, …) with
-non-zero sessions/messages. Or verify by SQL — the rooms are plain shared tables
+non-zero sessions/messages. Or verify by SQL — the rooms are the ones `memhouse rooms` names
 (`sessions`, `messages`, `tool_calls`) and the session rollup is a saved query rather
 than an object, so `memhouse sessions-query` prints it (it also applies the
 current-parse filter that any hand-written read of `messages` needs — the shipper

package/memhouse/delivery/INVITATION.md.tpl

@@ -0,0 +1,130 @@
+# 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.** 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.
+
+## 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}}`:
+
+```
+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:
+
+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.
+