memhouse 0.15.0 → 0.17.0

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

@@ -1,121 +0,0 @@
----
-name: hello
-description: Introduce memhouse — what it is, what it remembers, and how to use it from here. Use when the user asks "what is memhouse", "what can my memory do", "how do I use this", invokes /mem:hello, or seems new to the memory system. Also the right first answer when another /mem skill fails because nothing is configured yet.
-user-invocable: true
-argument-hint: ""
-allowed-tools: Bash
----
-
-# /mem:hello — welcome to your memory
-
-**Invoking this skill IS the request. Give the introduction immediately — grounded in
-this machine's actual state, not hypotheticals. Nothing to clarify first.**
-
-## First: find out what state this machine is in
-
-RUN this yourself with the Bash tool — do not print it for the user to run, and do not
-show the env values it sources. Read its output, then write the introduction using the
-ACTUAL numbers it returns (interpolate them; never emit the literal "N sessions").
-
-```bash
-MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
-_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
-set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
-[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
-[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
-if [ -n "${MEMHOUSE_URL:-}" ] && [ -n "${MEMHOUSE_USER:-}" ]; then
-  curl -sS -m 5 --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
-    --data-binary "SELECT uniqExact(session_id), count(), formatDateTime(min(ts),'%Y-%m-%d') FROM messages" \
-    "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&final=1&readonly=1" 2>&1
-else
-  echo "NOT_CONFIGURED"
-fi
-```
-
-(Do not print the env values, and do not narrate that you are withholding them — just use them.)
-
-## What memhouse is — the overview (give this in every state, before the tour)
-
-One paragraph, grounded not sold: **memhouse is your personal, permanent archive of every
-AI coding session.** A background shipper reads the session files your editors write —
-Claude Code, Codex, Cursor, VS Code, Zed, OpenCode, Gemini CLI and 10 more, 17 in all —
-and ships them into a ClickHouse database you own, called a **house**. YOU choose that
-ClickHouse: a local one on your laptop, one on your own VM, or any ClickHouse server you
-control — managed or remote. memhouse itself is not a hosted service and phones nothing
-home; your sessions go only to the house you point it at, and it runs no LLM in its write
-or read path — it stores rows, the agent reading them (this chat) does the thinking. It
-outlives the transcripts on disk: editors compact and delete their local session files
-after weeks, so for anything older than ~30 days the house is the only place it still
-exists. One archive spans every editor, every project, every machine you ship from.
-
-What it gives you, in one breath: **ask** your own history a question and get a cited
-answer, **search** for the session you half-remember, **query** the raw data for numbers,
-browse a **dashboard**, and **invite** other people onto your ClickHouse so memories can be
-**shared** read-only. The tour below names each.
-
-## Then introduce it — three states, three openings
-
-**Configured and answering** — open with the numbers: "Your memory holds N sessions
-(M messages) going back to <date> — every conversation you've had with coding agents
-(Claude Code, Codex, Cursor, Gemini CLI and 13 more), across all your machines. It
-outlives the transcripts on disk: editors delete their session files after weeks; this
-doesn't." Then the tour below.
-
-**Not configured** — say what memhouse IS (one paragraph: a personal, permanent archive
-of every AI coding session, stored in a ClickHouse "house" you own), then how to start:
-`memhouse onboard` (wizard) or `memhouse install --env <file>` if someone invited them
-(the file came from `/mem:invite` on the inviter's side).
-
-**Configured but unreachable** — say which URL refused, point at `memhouse doctor`,
-stop. Never guess another endpoint.
-
-## The tour (keep it to one screen)
-
-What you can DO from this chat:
-
-- `/mem:ask <question>` — answer from your past work, with citations ("how did I fix X
-  last time?")
-- `/mem:search <terms>` — find the session ("that conversation about Y")
-- `/mem:sessions` — browse and filter what's stored
-- `/mem:sql <question or SQL>` — ad-hoc analytics (tokens, costs, rankings)
-- `/mem:status` — is it healthy, how much is stored, which machines ship into it
-
-The first three overlap — same words work in each — so give the reader the rule that
-separates them: **want a session → search. Want an answer → ask. Want a number → sql.**
-`ask` runs a `search` first, then reads the turns it finds and writes you a cited answer;
-`search` stops at the ranked list of sessions; `sql` counts and aggregates the columns
-rather than hunting text.
-
-And around other people — **inviting comes before sharing**:
-
-- `/mem:invite <name>` — mint a friend's account + their own house on your ClickHouse,
-  hand them one env file; they install with it and have their own memory
-- `/mem:share <name>` — once they exist, open a read-only window into YOUR memory
-  (`/mem:share revoke <name>` closes it); `/mem:users` shows who's around
-- **Read a friend's shared memory** — once they've shared theirs with you, name their
-  house right in the question: `/mem:ask <question> in <their-house>`, or
-  `/mem:search <terms> in <their-house>` / `/mem:sql … on <their-house>`. It reads THEIR
-  house read-only, with your own credentials; `/mem:users` lists the houses shared with
-  you. (A house is a whole ClickHouse database — sharing grants read on it, not on single
-  sessions.)
-
-Also worth naming: `memhouse start` serves a dashboard at http://localhost:4640 for
-browsing and analytics outside the chat, and everything here is read-only for agents —
-only the shipper writes.
-
-**Freshness check** — quietly compare the installed client to the latest release; mention
-it ONLY if there's a real gap (don't clutter the welcome otherwise):
-
-```bash
-INSTALLED=$(memhouse version 2>/dev/null | head -1 | tr -d '[:space:]')
-LATEST=$(curl -sS -m 5 https://registry.npmjs.org/memhouse/latest 2>/dev/null | sed -n 's/.*"version":"\([^"]*\)".*/\1/p')
-echo "installed=${INSTALLED:-unknown} latest=${LATEST:-unknown}"
-```
-
-If the installed version is a MINOR or MAJOR behind (or many patches), add one line:
-"heads-up — you're on 0.A.B, 0.C.D is out; `memhouse update` upgrades it and refreshes
-these `/mem:*` skills." A patch or two behind isn't worth mentioning here. Never run the
-update yourself.
-
-End by offering one concrete action: a search for something they mentioned recently, or
-`/mem:status` if they seem unsure it's working. One offer, not a menu.

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

@@ -1,130 +0,0 @@
----
-name: invite
-description: Invite another person onto this memhouse ClickHouse — mint their user and their own house (database) with the right grants, producing the one env file their install needs. Use when the user says "invite X", "add X to memhouse", "get my friend set up". Inviting comes BEFORE sharing — /mem:share can only grant a user who exists.
-user-invocable: true
-argument-hint: "<name> [into <db>]"
-allowed-tools: Bash
----
-
-# /mem:invite — mint a member and hand them one file
-
-This runs the `memhouse invite` CLI and nothing else. Inviting mints a ClickHouse user
-and a house, which takes an ADMIN credential — and an admin password must never enter
-this conversation, because memhouse ships the transcript into the house it just
-provisioned. The CLI is the only safe path: the admin password is passed to one process
-and never echoed. **Do not hand-run `CREATE USER` / `GRANT` with an admin password
-substituted into a command — that burns the credential into the transcript on disk.**
-
-## Do this
-
-1. Confirm the `memhouse` binary is present: `command -v memhouse`. If it is not, tell
-   the user to install it first (`npm install -g memhouse`) — there is no in-skill
-   fallback, on purpose (see above).
-
-2. Gather ONLY two things by asking:
-   - the invitee's **name** (validate `[A-Za-z][A-Za-z0-9_]*`; refuse otherwise)
-   - the **URL the invitee will reach the house at** — NOT localhost (that is the
-     invitee's own machine). A LAN IP, hostname, or tunnel.
-
-   Do NOT ask for an admin user or password yet — the next step usually needs neither.
-   Only ask about a **shared house** if the user brings one up; default is the invitee's
-   own house (omit --db; never pass `--db default` for "the default house").
-
-3. TRY IT BARE FIRST — run this via the Bash tool, from the directory the file should
-   land in (step 4). `memhouse invite` uses the caller's OWN configured credential when
-   it can manage users, which is the common case for whoever set the house up, so no
-   admin is needed:
-
-   ```
-   memhouse invite <name> --url <url> [--db <shared-house>]
-   ```
-
-   If it prints `invite written: …`, go to step 4 — you are done, and no admin secret
-   ever touched this conversation.
-
-   Otherwise read WHICH refusal came back; they need different answers.
-
-   **"cannot reach `<url>` …"** — nothing to do with privileges. The address is wrong,
-   or the house is bound to loopback (`memhouse deploy --local` binds to 127.0.0.1 on
-   purpose, so no LAN address reaches it and no invitee could either). Ask the user for
-   the address the invitee will actually use; do not retry with a guess.
-
-   **"`<user>` is a MEMBER of this ClickHouse, not an administrator"** — inviting needs
-   CREATE USER and CREATE DATABASE, which a member deliberately does not hold. Two cases,
-   and you must ask which one applies rather than assuming:
-
-   - **They run the ClickHouse.** They have the admin credential; memhouse never stores
-     it. Do NOT take that password in chat — memhouse archives this transcript. Hand them
-     the line to run THEMSELVES, and leave `--admin-password` OFF so it is prompted for,
-     keeping it out of both the process list and shell history:
-
-     ```
-     memhouse invite <name> --url <url> [--db <shared-house>] --admin-user <admin>
-     ```
-
-     **You cannot run that line yourself.** The prompt needs a TTY and your Bash tool has
-     none, so it refuses with "no TTY to prompt on" — and the fix is NOT to add
-     `--admin-password`, which would put the credential in this transcript. The user runs
-     it in their own terminal; you wait for them to say it is done.
-
-   - **Somebody else runs it.** They cannot invite, and no flag changes that. Print the
-     statements for whoever administers the server — this contacts nothing and needs no
-     credential:
-
-     ```
-     memhouse invite <name> --url <url> [--db <shared-house>] --print-sql
-     ```
-
-     The output ends with the four `MEMHOUSE_*` lines the invitee needs. Those lines are
-     a credential: tell the user to send them over a trusted channel, and **never print
-     them into the conversation yourself**.
-
-   **If it refuses with "house `<db>` already exists and holds N messages", STOP.** That
-   house is somebody's memory, and inviting into it would hand the invitee someone else's
-   sessions. Do not pass `--adopt` on your own initiative — report the row count and the
-   writer count to the user and let them choose: a different handle, a different `--db`,
-   or `--adopt` if sharing that house is genuinely what they want.
-
-4. **Put the file where the user can attach it.** The CLI writes `invite-<name>.env`
-   into the CURRENT directory, and the user has to send it by hand — so run the command
-   from their downloads directory (on macOS and most Linux desktops `~/Downloads`), or
-   move it there afterwards. Never leave it in a git repo: it is a password, and
-   `invite-*.env` is only gitignored in this repo, not in whatever checkout the user
-   happened to be standing in.
-
-   Confirm it is there and still mode `600`, and say the full path. **Never print the
-   file's contents** — the password inside would land in a transcript memhouse ships.
-
-5. **Say whether the house was fresh.** Run
-   `memhouse stats` or query `SELECT count() FROM <db>.messages` and tell the user
-   plainly: a brand-new house reads 0. This is a second line of defence behind step 3's
-   refusal, and it is how the user learns the invitee is starting clean.
-
-6. **Write the message the user will send.** They are about to hand over a file plus an
-   explanation, so compose it for them rather than making them write it. Put it in a
-   fenced block they can copy whole, and cover:
-   - what memhouse is, in a sentence or two — the invitee may never have heard of it
-   - that the attached `invite-<name>.env` IS a password: don't forward it, don't paste
-     it into chat
-   - `npm install -g memhouse` (Node 24+, no flags, nothing compiles), then
-     `memhouse install --env invite-<name>.env`
-   - that install OFFERS to change the password to one only they know, then deletes the
-     file — so they should say yes, because the inviter knows the current one
-   - `memhouse onboard` to start shipping, `memhouse status` to check it worked
-   - that their house is theirs alone; the inviter cannot read it unless they run
-     `/mem:share <inviter>`
-
-   If the invitee is REPLACING an existing setup (they were shipping under another
-   credential), add `memhouse ship --full` after the install — a plain incremental pass
-   skips sessions the new house has no record of, so their history would not follow them.
-
-   Then: once installed, sharing works both ways — `/mem:share <name>`.
-
-## Never
-
-Never create a ClickHouse user by running raw SQL with an admin password you were given
-in chat. Never invent an admin credential. Never suggest granting beyond what `memhouse
-invite` does. If the binary is absent, stop and say so — do not improvise the SQL.
-
-Never print the invite file's contents, and never pass `--adopt` unless the user asked
-for it after being told what is already in that house.

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

@@ -1,186 +0,0 @@
----
-name: 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". Searches your own house by default, or a friend's house shared with you when they name it ("find X in yigit's memory"). 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
----
-
-# /mem:search — search conversation memory
-
-Search the full message history in the memhouse house. Every room is named for your
-ClickHouse user — `messages`, `sessions` — see **Room names** below.
-
-## Connection
-
-**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
-MEMHOUSE`, no `set -x` around these commands. Anything you print becomes part of a
-transcript that memhouse itself ships into the house.
-
-Credentials resolve as **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`**
-(default `~/.memhouse/env`) — the same order the `memhouse` CLI uses. Every query
-runs over ClickHouse HTTP with `final=1` and `join_use_nulls=1` (ReplacingMergeTree
-keeps stale row versions until merges; `final=1` collapses to latest-wins — always
-include it on reads):
-
-```bash
-# Config lives at $MEMHOUSE_HOME/env (default ~/.memhouse/env). Exported MEMHOUSE_*
-# vars WIN over the file — snapshot them, source, then put them back. Sourcing alone
-# lets a stale file silently override the house you were pointed at.
-MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
-_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
-set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
-[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
-[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
-# No default URL. localhost:8123 as memhouse_root is a REAL house on many machines,
-# usually the pilot's own — guessing it reads someone else's memory and looks like it
-# worked. If there is no config, say so and stop.
-if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
-  # An explicit test, not ${VAR:?msg}: zsh does not expand the message, so under the
-  # shell Claude Code actually uses the refusal read "nothing in $MH_ENV" literally.
-  echo "no memhouse house configured — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
-  echo "Run: memhouse install" >&2
-  exit 1
-fi
-
-# --user, not a -K config file. The config-file parser treats `"` and `\` specially, so a
-# password containing either authenticates fine from the CLI and fails from every skill
-# with "password is incorrect" — measured. The argv exposure -K was meant to avoid is not
-# observable here either: curl blanks the --user argument before `ps` can read it (0 hits
-# in 50 samples). What actually leaks a credential is PRINTING it, which the rule above
-# covers.
-curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
-  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
-<the query>
-FORMAT PrettyCompact
-SQL
-```
-
-`FORMAT PrettyCompact` for display; `FORMAT JSONEachRow` when you want to parse
-the rows yourself.
-
-## Room names — plain, shared tables
-
-The house's rooms are three plain tables: `messages`, `sessions`, `tool_calls` — resolved
-by the connection's database (`MEMHOUSE_DB`), not by who is asking. Everyone in the house
-writes into the same tables; `user_id` (stamped by the server) says whose row it is and
-`host` says which machine shipped it. Search the whole house by default; add
-`AND user_id = '<name>'` only when the user asks for one person's sessions.
-
-**Keep the SQL heredoc quoted (`<<'SQL'`).** This skill once told the agent to substitute
-a shell variable into the table names, which cannot expand inside a quoted heredoc — so
-the agent unquotes it, and then the SEARCH TERMS expand too. Both instances driving this
-skill did exactly that, unprompted, on the first attempt. Measured consequences, from
-`system.query_log`:
-
-- a term containing `$home` became the empty string, so `LIKE '%%'` matched **every row**
-  and reported hits with exit 0 — silently wrong, not an error;
-- a term containing a backtick **executed the command inside it**.
-
-A user's search term is arbitrary text. With the heredoc quoted, neither can happen.
-
-**There is no `sessions_v` object.** The session rollup is a saved query over those same
-rooms — `memhouse sessions-query` prints it for whoever you are connected as, ready to
-paste into a `FROM (...) AS c` position.
-
-**The rollup is self-contained.** As of 0.4.5 the printed text carries its own `FINAL` on
-both rooms and a trailing `SETTINGS join_use_nulls = 1`, so it is correct wherever you
-paste it. `final=1` on the connection still matters for reads of the rooms THEMSELVES,
-which carry no FINAL of their own.
-
-
-## 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, user_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, m.user_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, user_id)
-WHERE m.text_ngram LIKE '%clickhouse cache%'
-GROUP BY m.session_id, m.user_id
-ORDER BY hits DESC
-LIMIT 10
-FORMAT PrettyCompact
-```
-
-## Reading another person's house (shared with you)
-
-Every house is its own ClickHouse database on the same server; a share is a read-only
-GRANT on that database. To read a friend's memory you keep YOUR credentials and point the
-connection at THEIR house — the rooms (`messages`, `sessions`, `tool_calls`) resolve by
-the connection's `database`, so one change redirects every query in this skill.
-
-1. **Resolve the target house.** `SHOW DATABASES` lists what your credential may read; the
-   names that are not `system` / `information_schema` / `default` and not your own
-   `$MEMHOUSE_DB` are houses shared with you. If the user names one — "yigit's memory",
-   "in yigit", "house yigit", "from yigit" — set `HOUSE=yigit`; otherwise leave
-   `HOUSE=$MEMHOUSE_DB`.
-2. **Point the connection at it:** in the recipe above, replace
-   `database=${MEMHOUSE_DB:-$MEMHOUSE_USER}` with `database=<HOUSE>`. Leave the table names bare —
-   they resolve to that house. Nothing else in the query changes.
-3. **A house wins over `in <project>`.** A name that matches a readable house is a HOUSE,
-   not a project filter — otherwise "in yigit" silently filters YOUR house's project
-   column and returns nothing. If a real project in your own house shares the name, keep
-   the possessive ("<name>'s memory") or say "project <name>" to force the project reading.
-4. **Read-only, thin by design.** If the SELECT is refused, that house was not shared with
-   you (or the share was revoked) — say so; never guess another database.
-
-## Qualifiers
-
-- `in <project>` → `AND m.project ILIKE '%<project>%'` — but a name matching a readable
-  house is a HOUSE (see above), not a 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/memhouse/delivery/plugin/skills/sessions/SKILL.md

@@ -1,164 +0,0 @@
----
-name: 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
----
-
-# /mem:sessions — browse session history
-
-List/filter sessions from the session rollup — a saved query over your own rooms, not an
-object; `memhouse sessions-query` prints it (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
-
-**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
-MEMHOUSE`, no `set -x` around these commands. Anything you print becomes part of a
-transcript that memhouse itself ships into the house.
-
-Credentials resolve as **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`**
-(default `~/.memhouse/env`) — the same order the `memhouse` CLI uses. Every query
-runs over ClickHouse HTTP with `final=1` and `join_use_nulls=1` (ReplacingMergeTree
-keeps stale row versions until merges; `final=1` collapses to latest-wins — always
-include it on reads):
-
-```bash
-# Config lives at $MEMHOUSE_HOME/env (default ~/.memhouse/env). Exported MEMHOUSE_*
-# vars WIN over the file — snapshot them, source, then put them back. Sourcing alone
-# lets a stale file silently override the house you were pointed at.
-MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
-_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
-set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
-[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
-[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
-# No default URL. localhost:8123 as memhouse_root is a REAL house on many machines,
-# usually the pilot's own — guessing it reads someone else's memory and looks like it
-# worked. If there is no config, say so and stop.
-if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
-  # An explicit test, not ${VAR:?msg}: zsh does not expand the message, so under the
-  # shell Claude Code actually uses the refusal read "nothing in $MH_ENV" literally.
-  echo "no memhouse house configured — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
-  echo "Run: memhouse install" >&2
-  exit 1
-fi
-
-# --user, not a -K config file. The config-file parser treats `"` and `\` specially, so a
-# password containing either authenticates fine from the CLI and fails from every skill
-# with "password is incorrect" — measured. The argv exposure -K was meant to avoid is not
-# observable here either: curl blanks the --user argument before `ps` can read it (0 hits
-# in 50 samples). What actually leaks a credential is PRINTING it, which the rule above
-# covers.
-curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
-  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
-<the query>
-FORMAT PrettyCompact
-SQL
-```
-
-## Room names — plain, shared tables
-
-The house's rooms are three plain tables: `messages`, `sessions`, `tool_calls` — resolved
-by the connection's database (`MEMHOUSE_DB`), not by who is asking. Everyone in the house
-writes into the same tables; `user_id` (stamped by the server) says whose row it is and
-`host` says which machine shipped it. Search the whole house by default; add
-`AND user_id = '<name>'` only when the user asks for one person's sessions.
-
-**Keep the SQL heredoc quoted (`<<'SQL'`).** This skill once told the agent to substitute
-a shell variable into the table names, which cannot expand inside a quoted heredoc — so
-the agent unquotes it, and then the SEARCH TERMS expand too. Both instances driving this
-skill did exactly that, unprompted, on the first attempt. Measured consequences, from
-`system.query_log`:
-
-- a term containing `$home` became the empty string, so `LIKE '%%'` matched **every row**
-  and reported hits with exit 0 — silently wrong, not an error;
-- a term containing a backtick **executed the command inside it**.
-
-A user's search term is arbitrary text. With the heredoc quoted, neither can happen.
-
-**There is no `sessions_v` object.** The session rollup is a saved query over those same
-rooms — `memhouse sessions-query` prints it for whoever you are connected as, ready to
-paste into a `FROM (...) AS c` position.
-
-**The rollup is self-contained.** As of 0.4.5 the printed text carries its own `FINAL` on
-both rooms and a trailing `SETTINGS join_use_nulls = 1`, so it is correct wherever you
-paste it. Both matter: without `FINAL` every message is counted once per undeleted
-ReplacingMergeTree version (2x right after a ship, 3x a few ships later — measured, and it
-grows); without `join_use_nulls` a session with no messages reports `total_msgs = 1`
-rather than 0.
-
-**If the `memhouse` binary is not on PATH**, you cannot print the rollup — the skills are
-installable on their own. Query the rooms directly instead: `sessions` for metadata
-and `messages` for counts, each read `FINAL`, joined on `session_id` and `user_id`.
-Prefer the binary when it is there; a rollup you assemble by hand and one printed by a
-DIFFERENT memhouse version are the two ways this goes quietly wrong.
-
-
-## 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 (the rollup from `memhouse sessions-query`)
-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 (the rollup from `memhouse sessions-query`)
-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 (the rollup from `memhouse sessions-query`)
-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 /mem: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 /mem:search for a specific quote.