memhouse 0.0.1 → 0.3.1

package/mem-house/delivery/install.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# mem-house standalone installer.
+#
+# Checks node >= 20 and a reachable ClickHouse, writes ~/.memhouse/env
+# (MEMHOUSE_* vars), applies the house schema via the shipper
+# (`ship.js --ensure-schema`), runs a first ship, and prints how to start the
+# dashboard and set up continuous shipping (`--loop`).
+#
+# Usage:
+#   ./install.sh                                  # interactive (prompts for missing values)
+#   ./install.sh --url http://localhost:8123 --user memhouse_root --password 'pw' --db memhouse
+#   ./install.sh --yes                            # non-interactive, defaults / env / existing env file
+#
+# Flags:
+#   --url URL         ClickHouse HTTP(S) endpoint   (default http://localhost:8123)
+#   --user USER       ClickHouse user               (default memhouse_root; 'default' works for a local CH)
+#   --password PW     credential                    (default empty)
+#   --db DB           the house (database)          (default memhouse)
+#   --port PORT       dashboard/API port            (default 4640)
+#   --yes             never prompt; take flags > current env > ~/.memhouse/env > defaults
+#   --no-ship         stop after writing env + ensure-schema (skip the first ship)
+#
+# Defaults resolve in order: flag > MEMHOUSE_* already in the environment >
+# existing ~/.memhouse/env > built-in default. Runs from any cwd — the repo is
+# resolved from this script's own location (mem-house/delivery/ -> repo root).
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../.." && pwd)"
+SHIP="$REPO_ROOT/mem-house/shipper/ship.js"
+SERVER="$REPO_ROOT/mem-house/server/server.js"
+ENV_DIR="$HOME/.memhouse"
+ENV_FILE="$ENV_DIR/env"
+
+die() { echo "install.sh: $*" >&2; exit 1; }
+info() { echo "== $*"; }
+
+# ---------- 0. defaults: existing env file, then environment ----------------
+if [ -f "$ENV_FILE" ]; then
+  # shellcheck disable=SC1090
+  set -a; . "$ENV_FILE"; set +a
+fi
+CH_URL="${MEMHOUSE_URL:-http://localhost:8123}"
+CH_USER="${MEMHOUSE_USER:-memhouse_root}"
+CH_PASSWORD="${MEMHOUSE_PASSWORD:-}"
+CH_DB="${MEMHOUSE_DB:-memhouse}"
+DASH_PORT="${MEMHOUSE_PORT:-4640}"
+
+ASSUME_YES=0
+NO_SHIP=0
+URL_SET=0; USER_SET=0; PASS_SET=0; DB_SET=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --url)      CH_URL="${2:?--url needs a value}"; URL_SET=1; shift 2;;
+    --user)     CH_USER="${2:?--user needs a value}"; USER_SET=1; shift 2;;
+    --password) CH_PASSWORD="${2:?--password needs a value}"; PASS_SET=1; shift 2;;
+    --db)       CH_DB="${2:?--db needs a value}"; DB_SET=1; shift 2;;
+    --port)     DASH_PORT="${2:?--port needs a value}"; shift 2;;
+    --yes|-y)   ASSUME_YES=1; shift;;
+    --no-ship)  NO_SHIP=1; shift;;
+    -h|--help)  sed -n '2,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0;;
+    *) die "unknown flag: $1 (try --help)";;
+  esac
+done
+
+# ---------- 1. node >= 20 ---------------------------------------------------
+command -v node >/dev/null 2>&1 || die "node not found (need node >= 20; https://nodejs.org)"
+NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"
+[ "$NODE_MAJOR" -ge 20 ] 2>/dev/null || die "node >= 20 required (found $(node -v))"
+info "node $(node -v) ok"
+
+[ -f "$SHIP" ] || die "shipper not found at $SHIP (incomplete checkout?)"
+
+# ---------- 2. repo dependencies -------------------------------------------
+if [ ! -d "$REPO_ROOT/node_modules" ]; then
+  info "installing npm dependencies (first run)"
+  (cd "$REPO_ROOT" && npm install --no-audit --no-fund)
+fi
+
+# ---------- 3. gather connection values -------------------------------------
+prompt() { # prompt <question> <current> -> stdout
+  local ans
+  read -r -p "$1 [$2]: " ans
+  echo "${ans:-$2}"
+}
+if [ "$ASSUME_YES" -eq 0 ] && [ -t 0 ]; then
+  [ "$URL_SET"  -eq 1 ] || CH_URL="$(prompt "ClickHouse URL" "$CH_URL")"
+  [ "$USER_SET" -eq 1 ] || CH_USER="$(prompt "ClickHouse user" "$CH_USER")"
+  if [ "$PASS_SET" -eq 0 ]; then
+    read -r -s -p "ClickHouse password [keep current/empty]: " ans; echo
+    [ -n "$ans" ] && CH_PASSWORD="$ans"
+  fi
+  [ "$DB_SET" -eq 1 ] || CH_DB="$(prompt "House (database)" "$CH_DB")"
+fi
+
+# ---------- 4. ClickHouse reachable? ----------------------------------------
+info "checking ClickHouse at $CH_URL (user $CH_USER)"
+ONE="$(curl -sS --connect-timeout 5 --fail-with-body \
+        --user "$CH_USER:$CH_PASSWORD" \
+        --data-binary "SELECT 1" "$CH_URL")" \
+  || die "ClickHouse not reachable at $CH_URL with those credentials"
+[ "$ONE" = "1" ] || die "unexpected reply from $CH_URL: $ONE"
+info "ClickHouse ok"
+
+# Ensure the house exists before ensure-schema (schema.sql is unqualified and the
+# shipper binds to MEMHOUSE_DB — on a virgin standalone server the database must
+# be created first). On a kernel realm the house is already provisioned; if the
+# user lacks CREATE DATABASE but the house is reachable, that's fine too.
+case "$CH_DB" in
+  (*[!A-Za-z0-9_]*|'') die "invalid database name '$CH_DB' — use letters, digits, underscore" ;;
+esac
+if ! curl -fsS --max-time 20 --user "$CH_USER:$CH_PASSWORD" \
+      --data-binary "CREATE DATABASE IF NOT EXISTS $CH_DB" "$CH_URL" >/dev/null 2>&1; then
+  curl -fsS --max-time 20 --user "$CH_USER:$CH_PASSWORD" \
+      --data-binary "SELECT 1" "$CH_URL/?database=$CH_DB" >/dev/null 2>&1 \
+    || die "house '$CH_DB' does not exist and cannot be created as $CH_USER"
+fi
+info "house '$CH_DB' ready"
+
+# ---------- 5. write ~/.memhouse/env ----------------------------------------
+mkdir -p "$ENV_DIR"; chmod 700 "$ENV_DIR"
+# Values are single-quoted (embedded ' escaped) — this file is sourced by shells
+# (docs/skills use `. ~/.memhouse/env`), so unquoted metacharacters in a password
+# would corrupt the value or execute on source.
+shq() { printf "%s" "$1" | sed "s/'/'\\\\''/g"; }
+cat > "$ENV_FILE" <<EOF
+# mem-house connection (written by install.sh $(date +%Y-%m-%d-%H_%M)). NEVER commit.
+MEMHOUSE_URL='$(shq "$CH_URL")'
+MEMHOUSE_USER='$(shq "$CH_USER")'
+MEMHOUSE_PASSWORD='$(shq "$CH_PASSWORD")'
+MEMHOUSE_DB='$(shq "$CH_DB")'
+MEMHOUSE_PORT='$(shq "$DASH_PORT")'
+EOF
+chmod 600 "$ENV_FILE"
+info "wrote $ENV_FILE"
+
+export MEMHOUSE_URL="$CH_URL" MEMHOUSE_USER="$CH_USER" \
+       MEMHOUSE_PASSWORD="$CH_PASSWORD" MEMHOUSE_DB="$CH_DB" \
+       MEMHOUSE_PORT="$DASH_PORT"
+
+# ---------- 6. schema + first ship ------------------------------------------
+info "applying house schema (ship.js --ensure-schema)"
+node "$SHIP" --ensure-schema \
+  || die "ensure-schema failed. If $CH_USER cannot CREATE DATABASE, create '$CH_DB' first (or, on a kernel realm, provision the agency: see delivery/kernel-install.md), then re-run."
+
+if [ "$NO_SHIP" -eq 0 ]; then
+  info "first ship (this parses local editor sessions and may take a while)"
+  node "$SHIP"
+else
+  info "skipping first ship (--no-ship)"
+fi
+
+# ---------- 7. next steps ----------------------------------------------------
+cat <<EOF
+
+mem-house installed.
+
+  env file     $ENV_FILE
+  house        $CH_DB @ $CH_URL
+
+Next steps:
+
+  # dashboard (agentlytics UI over the house) -> http://localhost:$DASH_PORT
+  node "$SERVER"
+
+  # keep shipping continuously (re-ships incrementally; Ctrl-C to stop)
+  node "$SHIP" --loop
+  # background it:
+  nohup node "$SHIP" --loop >> "$ENV_DIR/ship.log" 2>&1 &
+
+  # agent skills (search/sessions/sql from inside Claude Code):
+  node "$REPO_ROOT/bin/memhouse.js" plugins install claude
+  # -> installs memhouse-search / memhouse-sessions / memhouse-sql into
+  #    \${CLAUDE_CONFIG_DIR:-\$HOME/.claude}/skills (loads next session)
+
+Verify anytime:
+  set -a; . "$ENV_FILE"; set +a
+  curl -sS --user "\$MEMHOUSE_USER:\$MEMHOUSE_PASSWORD" --data-binary \\
+    "SELECT count() FROM sessions" "\$MEMHOUSE_URL/?database=\$MEMHOUSE_DB&final=1"
+EOF

package/mem-house/delivery/kernel-install.md

@@ -0,0 +1,83 @@
+# mem-house — install as a kernel agency
+
+How to run mem-house as an **agency** on an ultimagent kernel — a ClickHouse server
+(a **town**) promoted into a realm — instead of a plain ClickHouse. Same flow proven
+for the agentlytics agency (`agency/AGENCY.md`); the agency/house name here is
+**`memhouse`** (CH identifiers can't carry a dash). What lands is a **house** (the
+`memhouse` database) with a **resident** (the shipper — `kind = "worker"`,
+`on = "loop"`) — that pairing is the agency. Residents write; routines read, and the
+`sessions_v` view is a routine. Terms: `../../TERMINOLOGY.md`.
+
+This is an operator runbook, so it speaks machine vocabulary throughout — ClickHouse,
+`GRANT`, row policies. That is correct for this audience.
+
+## 1. Provision (operator, one-time — from the kernel checkout)
+
+```bash
+python3 executor/executor.py provision memhouse
+```
+
+Submits `install-agency{name:'memhouse'}`; the mayor — the human owner — approves;
+the executor (running as the ego, the `kernel` user) creates database `memhouse`
+(the house), owner `memhouse_root`
+(`realm_user` profile), and owner grants. It returns a one-time **credential** —
+rotate on first connect (`issue-credential{user:'memhouse_root'}`).
+
+## 2. Owner sets up the house
+
+```bash
+npm install -g memhouse --allow-scripts=better-sqlite3
+memhouse install --yes \
+  --url https://<kernel-host>:8443 \
+  --user memhouse_root \
+  --password <credential-from-provision> \
+  --db memhouse
+```
+
+That writes `~/.memhouse/env`, applies the schema, and runs the first ship.
+`memhouse start` then keeps it fresh on a 300s loop.
+
+Keep `--allow-scripts=better-sqlite3`: without it npm 12 leaves `better-sqlite3`
+with no native binding and the five SQLite-backed adapters ship nothing, silently.
+`memhouse discover` names any adapter it had to skip.
+
+The kernel never runs or reads any of this — it is content-blind; the shipper is
+the agency's own resident, a deterministic `worker` on a loop (no LLM, not an
+injection surface). It is the only thing here that writes without being asked.
+
+## 3. Members (multi-user)
+
+For each person joining, split across the two authorities:
+
+```bash
+# The EGO (the `kernel` user) mints the identity; the mayor approves:
+python3 executor/executor.py submit register-member '{"handle":"alice"}'
+python3 executor/executor.py approve <call_id> && python3 executor/executor.py drain
+
+# OWNER grants house access (memhouse_root has grant-option on memhouse.*):
+#   GRANT INSERT, SELECT ON memhouse.* TO alice
+```
+
+Each member then runs the shipper with **their own** credential
+(`MEMHOUSE_USER=alice`) — the house stamps `user_id='alice'` on their rows,
+un-spoofably (`MATERIALIZED currentUser()`, `async_insert=0`).
+
+## 4. Visibility: own-only vs team pool
+
+- **Own-only** (memory-house's model — each member sees only their own rows): the
+  **ego (the `kernel` user) or the mayor** applies `mem-house/rls.sql` (three row
+  policies bound to the `member` role). The owner cannot — `CREATE ROW POLICY` needs
+  ACCESS MANAGEMENT, which the kernel withholds from agency owners by design.
+- **Team pool** (everyone sees everything): apply no policy; the owner GRANTs from
+  step 3 are the whole model.
+
+Pick one; do not mix on the same role.
+
+## 5. Verify
+
+```bash
+memhouse stats                              # per-source counts as the owner
+# as a member (own-only): counts reflect only that member's rows
+curl -s -u "alice:<pw>" "$MEMHOUSE_URL/?database=memhouse" \
+  --data-binary "SELECT count() FROM sessions_v SETTINGS final=1"
+```

package/mem-house/delivery/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "memhouse",
+  "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: search, browse, and analyze every past session across all 17 supported editors and machines. Skills install as /memhouse:search, /memhouse:sessions, and /memhouse:sql.",
+  "version": "0.3.0",
+  "author": { "name": "Ramazan Polat" },
+  "homepage": "https://github.com/agent-realm/memhouse",
+  "keywords": ["memory", "clickhouse", "search", "sessions", "analytics", "agentlytics"]
+}

package/mem-house/delivery/skills/memhouse-search/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: memhouse-search
+description: Full-text search across ALL shipped agent conversations — every session from all 17 supported editors (Claude Code, Codex, Cursor, VS Code, Zed, OpenCode, Gemini CLI, …), every project, every machine — stored in the memhouse ClickHouse. Use whenever the user refers to something from the past that isn't in the current context, e.g. "what did I say about X", "find that conversation about Y", "when did I work on Z", "did I ever try W", "the chat where we discussed it", "remind me how I did it". Reach for this before saying you don't know about prior work.
+user-invocable: true
+argument-hint: "<search terms> [in <project>] [last <N> days] [from <editor>]"
+allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
+---
+
+# memhouse-search — search conversation memory
+
+Search the full message history in the memhouse house (`messages` + `sessions`
+tables on ClickHouse).
+
+## Connection
+
+Credentials come from `~/.memhouse/env` (or already-exported `MEMHOUSE_*` vars).
+Every query runs over ClickHouse HTTP with `final=1` (ReplacingMergeTree keeps
+stale row versions until merges; `final=1` collapses to latest-wins — always
+include it on reads):
+
+```bash
+set -a; [ -f ~/.memhouse/env ] && . ~/.memhouse/env; set +a
+curl -sS --fail-with-body --user "${MEMHOUSE_USER:-memhouse_root}:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-memhouse}&final=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+`FORMAT PrettyCompact` for display; `FORMAT JSONEachRow` when you want to parse
+the rows yourself.
+
+## How to search (the FTS columns)
+
+`messages` carries two MATERIALIZED lowercase copies of `text`, each with a
+text index — search those, display `text`:
+
+- `text_ngram` (ngram index) → substring match: `text_ngram LIKE '%term%'`
+- `text_word` (word index) → whole-token match: `hasToken(text_word, 'term')`
+
+**Search terms MUST be lowercased** (the columns are `lower(text)`); escape
+single quotes in user terms as `\'`. Multiple words → AND of clauses; a quoted
+phrase → one `LIKE` clause for the whole phrase.
+
+### Example 1 — substring search with session names
+
+```sql
+SELECT m.ts, m.source, m.project, m.role, m.session_id,
+       s.name AS session,
+       substring(m.text, 1, 300) AS snippet
+FROM messages AS m
+LEFT JOIN sessions AS s USING (session_id)
+WHERE m.text_ngram LIKE '%postgres%' AND m.text_ngram LIKE '%migration%'
+ORDER BY m.ts DESC
+LIMIT 30
+FORMAT PrettyCompact
+```
+
+### Example 2 — word match, scoped by editor and time
+
+```sql
+SELECT ts, project, session_id, substring(text, 1, 200) AS snippet
+FROM messages
+WHERE hasToken(text_word, 'rls')
+  AND source = 'claude-code'
+  AND ts > now() - INTERVAL 14 DAY
+ORDER BY ts DESC
+LIMIT 20
+FORMAT PrettyCompact
+```
+
+### Example 3 — which sessions mention it most (then drill in)
+
+```sql
+SELECT m.session_id, any(s.name) AS session, any(m.project) AS project,
+       count() AS hits, max(m.ts) AS last_hit
+FROM messages AS m
+LEFT JOIN sessions AS s USING (session_id)
+WHERE m.text_ngram LIKE '%clickhouse cache%'
+GROUP BY m.session_id
+ORDER BY hits DESC
+LIMIT 10
+FORMAT PrettyCompact
+```
+
+## Qualifiers
+
+- `in <project>` → `AND m.project ILIKE '%<project>%'`
+- `last N days` → `AND m.ts > now() - INTERVAL N DAY`
+- `from <editor>` → `AND m.source = '<id>'` (ids: `claude-code`, `codex`,
+  `cursor`, `cursor-agent`, `vscode`, `zed`, `opencode`, `gemini-cli`,
+  `windsurf`, `antigravity`, `copilot-cli`, `goose`, `kiro`, …)
+- Skip subagent noise → `AND NOT m.is_subagent`
+- Only user/assistant text lives in `messages`; tool invocations are in
+  `tool_calls` (`tool_name`, `args`) — search `args ILIKE '%term%'` there only
+  if the user explicitly wants tool calls searched.
+
+## Output
+
+Summarize hits grouped by session (name, source, project, date, 1–2 best
+snippets each) and give the total hit count. Offer to pull the full transcript
+of the best session (`SELECT role, text FROM messages WHERE session_id = '…'
+ORDER BY seq`). If zero hits, retry with broader/fewer terms and report the
+corpus size (`SELECT count() FROM messages`).

package/mem-house/delivery/skills/memhouse-sessions/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: memhouse-sessions
+description: List recent agent sessions from memhouse conversation memory — names, projects, editors, hosts, times, message and token counts across all 17 supported editors. Use for "what was I working on", "show my recent sessions", "sessions from last week", "what did I do in project X", "list my cursor sessions", or to orient before drilling into one session.
+user-invocable: true
+argument-hint: "[N] [project <name>] [from <editor>] [today|week|month]"
+allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
+---
+
+# memhouse-sessions — browse session history
+
+List/filter sessions from the `sessions_v` rollup view (session metadata +
+message aggregates) in the memhouse house.
+
+## When to use
+
+- The user wants an overview of recent activity rather than a specific quote.
+- As a first step before digging into one session, when they don't have an
+  id/name yet.
+
+## Connection
+
+Credentials from `~/.memhouse/env` (or exported `MEMHOUSE_*`). Always read with
+`final=1` (collapses ReplacingMergeTree duplicates to latest-wins):
+
+```bash
+set -a; [ -f ~/.memhouse/env ] && . ~/.memhouse/env; set +a
+curl -sS --fail-with-body --user "${MEMHOUSE_USER:-memhouse_root}:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-memhouse}&final=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+## Default listing
+
+```sql
+SELECT session_id, name, source, host, project,
+       started, ended, total_msgs, user_msgs, assistant_msgs,
+       output_tokens,
+       substring(first_prompt, 1, 80) AS first_prompt
+FROM sessions_v
+ORDER BY ended DESC
+LIMIT 20
+FORMAT PrettyCompact
+```
+
+- Default `LIMIT 20`; `[N]` overrides.
+- `today` / `week` / `month` → `WHERE ended > now() - INTERVAL 1 DAY`
+  (`7 DAY` / `30 DAY`).
+- `project <name>` → `WHERE project ILIKE '%<name>%'`.
+- `from <editor>` → `WHERE source = '<id>'` (`claude-code`, `codex`, `cursor`,
+  `vscode`, `zed`, `opencode`, `gemini-cli`, `windsurf`, …).
+- Unnamed sessions (`name = ''`): fall back to `first_prompt` as the label.
+
+## More cuts
+
+Per-editor rollup ("where has my work been happening?"):
+
+```sql
+SELECT source, count() AS sessions, sum(total_msgs) AS msgs,
+       sum(output_tokens) AS out_tokens, max(ended) AS last_activity
+FROM sessions_v
+GROUP BY source
+ORDER BY sessions DESC
+FORMAT PrettyCompact
+```
+
+Busiest projects this month:
+
+```sql
+SELECT project, count() AS sessions, sum(assistant_msgs) AS assistant_msgs
+FROM sessions_v
+WHERE ended > now() - INTERVAL 30 DAY AND project != ''
+GROUP BY project
+ORDER BY sessions DESC
+LIMIT 15
+FORMAT PrettyCompact
+```
+
+## Examples
+
+| User says | What you do |
+|---|---|
+| "what was I working on yesterday?" | `WHERE ended > now() - INTERVAL 1 DAY` |
+| "show my last 10 sessions in agentlytics" | `LIMIT 10 … WHERE project ILIKE '%agentlytics%'` |
+| "list my cursor sessions this month" | `WHERE source = 'cursor' AND ended > now() - INTERVAL 30 DAY` |
+| "which machine did I do the schema work on?" | search via memhouse-search, or filter `host` here |
+
+## Output
+
+A compact table: when, name (or first prompt), source, host, project, msgs,
+tokens. Offer to pull a full transcript next
+(`SELECT role, text FROM messages WHERE session_id = '…' ORDER BY seq`) or to
+run memhouse-search for a specific quote.

package/mem-house/delivery/skills/memhouse-sql/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: memhouse-sql
+description: Run free-form read-only SQL against memhouse conversation memory (typed sessions/messages/tool_calls tables + the sessions_v view on ClickHouse). Use for ad-hoc analytics the other memhouse skills don't cover — token spend, model/editor usage, tool rankings, activity heatmaps, busiest days/projects, cache-hit ratios, or any custom question over conversation data.
+user-invocable: true
+argument-hint: "<question or SQL>"
+allowed-tools: Bash(set -a*), Bash(. *), Bash(curl*)
+---
+
+# memhouse-sql — ad-hoc analytics
+
+If the user gives SQL, run it (append `FORMAT PrettyCompact` if no FORMAT
+given). If they give a question, write the SQL yourself from the schema below.
+
+**Read-only rule:** the shipper (`ship.js`) is the only writer. Never INSERT/
+ALTER/DROP from here — member credentials typically hold only
+`INSERT, SELECT ON memhouse.*`, and on shared instances own-only row policies
+scope reads to your rows.
+
+## Connection
+
+Credentials from `~/.memhouse/env` (or exported `MEMHOUSE_*`). Always read with
+`final=1` — every table is `ReplacingMergeTree(ingested_at)`, so without it you
+can double-count stale row versions:
+
+```bash
+set -a; [ -f ~/.memhouse/env ] && . ~/.memhouse/env; set +a
+curl -sS --fail-with-body --user "${MEMHOUSE_USER:-memhouse_root}:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "${MEMHOUSE_URL:-http://localhost:8123}/?database=${MEMHOUSE_DB:-memhouse}&final=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+`FORMAT PrettyCompact` for display, `FORMAT JSONEachRow` to parse.
+
+## Schema (the house)
+
+| Object | Kind | Columns |
+|---|---|---|
+| `sessions` | table, 1 row/session | `session_id, source, host, name, mode, folder, project, git_branch, created_at, last_updated_at, message_count, path, extra JSON, user_id, ingested_at` |
+| `messages` | table, 1 row/message | `session_id, seq, source, host, ts, role, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, text, project, folder, is_subagent, extra JSON, line_hash, user_id, ingested_at` + FTS columns `text_ngram`/`text_word` (lowercased; see memhouse-search) |
+| `tool_calls` | table, 1 row/tool call | `session_id, seq, idx, source, host, tool_name, args, ts, project, folder, user_id, ingested_at` |
+| `sessions_v` | view, rollup | `session_id, source, host, name, mode, folder, project, git_branch, user_id, created_at, last_updated_at, started, ended, duration_sec, total_msgs, user_msgs, assistant_msgs, subagent_msgs, models, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, user_chars, assistant_chars, first_prompt` |
+
+Notes: `source` = editor id (`claude-code`, `codex`, `cursor`, `cursor-agent`,
+`vscode`, `zed`, `opencode`, `gemini-cli`, `windsurf`, `antigravity`, …);
+`seq` = message index within its session (0-based); `tool_calls.idx` = call
+index within the session; `user_id` is server-stamped (`currentUser()`);
+`models` in `sessions_v` is an `Array(String)`. Exclude `''` and
+`'<synthetic>'` from model aggregates.
+
+## Examples
+
+Token spend by model:
+
+```sql
+SELECT model, sum(input_tokens) AS in_tok, sum(output_tokens) AS out_tok,
+       sum(cache_read_tokens) AS cache_read
+FROM messages
+WHERE model NOT IN ('', '<synthetic>')
+GROUP BY model
+ORDER BY out_tok DESC
+FORMAT PrettyCompact
+```
+
+Which tools do I use most (memhouse exclusive — memory-house has no tool table):
+
+```sql
+SELECT tool_name, count() AS calls, uniqExact(session_id) AS sessions
+FROM tool_calls
+GROUP BY tool_name
+ORDER BY calls DESC
+LIMIT 20
+FORMAT PrettyCompact
+```
+
+Busiest days, last two weeks:
+
+```sql
+SELECT toDate(ts) AS day, uniqExact(session_id) AS sessions, count() AS msgs
+FROM messages
+WHERE ts > now() - INTERVAL 14 DAY
+GROUP BY day
+ORDER BY day DESC
+FORMAT PrettyCompact
+```
+
+Activity by editor this week / subagent share:
+
+```sql
+SELECT source, count() AS msgs, countIf(is_subagent) AS subagent_msgs
+FROM messages
+WHERE ts > now() - INTERVAL 7 DAY
+GROUP BY source
+ORDER BY msgs DESC
+FORMAT PrettyCompact
+```
+
+Longest sessions by wall-clock:
+
+```sql
+SELECT name, project, source, duration_sec, total_msgs, output_tokens
+FROM sessions_v
+ORDER BY duration_sec DESC
+LIMIT 10
+FORMAT PrettyCompact
+```
+
+## Output
+
+Run the query, present the result as a compact table, and add one or two lines
+of interpretation. Offer a natural follow-up cut (by source, by project, by
+host, by token volume) when relevant. Dollar costs are computed by the
+dashboard server from pricing.js — token sums here are the raw material, not
+dollars.

package/mem-house/rls.sql

@@ -0,0 +1,17 @@
+-- mem-house — own-only row-level security (the sharing model's isolation half).
+--
+-- Applied by the KERNEL (or the mayor, who has ACCESS MANAGEMENT) — the agency owner
+-- cannot CREATE ROW POLICY by design. Binds to the kernel's `member` role, so every
+-- registered member sees only their own rows; the owner (not a member) sees the whole
+-- house. For a shared team pool instead, apply NO policy — just the owner's GRANTs.
+--
+-- Substitute `memhouse` if the operator named the house differently. Policies bind to
+-- physical tables; views (sessions_v) inherit the querying user's policy via messages/
+-- sessions.
+
+CREATE ROW POLICY IF NOT EXISTS own_sessions ON memhouse.sessions
+    FOR SELECT USING user_id = currentUser() TO member;
+CREATE ROW POLICY IF NOT EXISTS own_messages ON memhouse.messages
+    FOR SELECT USING user_id = currentUser() TO member;
+CREATE ROW POLICY IF NOT EXISTS own_tool_calls ON memhouse.tool_calls
+    FOR SELECT USING user_id = currentUser() TO member;