memhouse 0.16.0 → 0.17.0

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

@@ -0,0 +1,154 @@
+# The house — connect, schema, and the three things that bite
+
+Read this before writing any query. Every `/mem:*` skill points here rather than
+repeating it, so there is one description of the store and it is either right everywhere
+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 **member** owns one house. An **administrator** owns the ClickHouse. `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
+rows, and *you* read them.
+
+---
+
+## Connect
+
+**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no
+`env | grep MEMHOUSE`, no `set -x`. Anything printed becomes part of a transcript
+memhouse ships back into the house — the archive is insert-only, so a leaked credential
+cannot be withdrawn.
+
+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
+variable.
+
+```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 [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
+  echo "no memhouse house configured — run: memhouse install" >&2; exit 1
+fi
+
+q() {  # read-only by construction; every read path should use this
+  curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+    --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&readonly=1"
+}
+q <<'SQL'
+SELECT 1 FORMAT PrettyCompact
+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.
+
+---
+
+## Schema
+
+**`messages`** — one row per turn.
+
+| column | meaning |
+|---|---|
+| `session_id` | `<source>:<adapter-local id>`, e.g. `claude-code:6b1f…` |
+| `seq` | position in the session, from 0 |
+| `source` | editor: `claude-code`, `codex`, `cursor`, … |
+| `host` | the machine, `<hostname>-<8 hex>` — random per install, not derived |
+| `ts` | when the turn happened (`DateTime64(3,'UTC')`) |
+| `role` | `user`, `assistant`, `system` |
+| `model`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens` | usage; **empty for several adapters** — see below |
+| `text` | the turn, **truncated at 50,000 chars** |
+| `text_ngram`, `text_word` | `MATERIALIZED lower(text)`, carrying the text indexes |
+| `project`, `folder` | where it happened; `folder` is what `resume` needs |
+| `user_id` | `MATERIALIZED currentUser()` — stamped by the server, unfakeable |
+| `origin` | `ship` or `import` |
+| `epoch` | which *parse* of the session this row belongs to |
+
+**`tool_calls`** — `session_id, seq, idx, source, host, tool_name, args, ts, project,
+folder, origin, epoch, user_id`. `args` is truncated at 20,000 chars. **There is no
+result column** — what a tool *returned* is not stored, and adapters truncate any preview
+of it to 300–500 chars inside `messages.text`.
+
+**`sessions`** — one metadata row per session: `name` (first user prompt, 120 chars),
+`source`, `host`, `project`, `folder`, `message_count`, timestamps, `extra`. Deliberately
+**not** epoch-keyed: latest write wins.
+
+`memhouse sessions-query` prints a self-contained per-session rollup (it carries its own
+`FINAL`) — prefer it over hand-joining.
+
+---
+
+## The three things that bite
+
+### 1. Epochs — a plain `SELECT` over-counts
+
+The shipper never overwrites a diverging parse. When a re-parse comes back shorter, or
+any overlapping turn hashes differently — which is what a **compaction** does to a long
+session — it writes the new parse under `epoch + 1` and keeps the old rows. So the same
+session can be present several times over.
+
+Reads must resolve to the current epoch. **Every counting or aggregating query needs
+this**, and the physical table name is the *raw* one, so nothing applies it for you:
+
+```sql
+WHERE origin != 'ship'
+   OR (session_id, user_id, epoch) IN (
+        SELECT session_id, user_id, max(epoch) FROM messages
+        WHERE origin = 'ship' GROUP BY session_id, user_id)
+```
+
+Measured on a real house: omitting it over-counted by **34%**. Drop it deliberately only
+when the question is about what a session said *before* it was compacted — superseded
+epochs are the one place that content still exists.
+
+### 2. Join on `(session_id, user_id)`, never `session_id` alone
+
+Two housemates can collide on an adapter-local session id. Every join, every `GROUP BY`
+that identifies a session, takes both columns.
+
+### 3. Escape before splicing, and lowercase the needle
+
+Search terms, session ids and user ids are arbitrary text going into single-quoted
+literals. Escape backslashes then single quotes (`\` → `\\`, `'` → `\'`) in **every**
+value. `O'Reilly` otherwise breaks the query, and crafted text could reshape it.
+
+The FTS columns are `lower(text)`, so lowercase what you look for:
+
+```sql
+WHERE text_ngram LIKE '%needle%'     -- substring, any length
+WHERE hasToken(text_word, 'needle')  -- whole word, faster on common terms
+```
+
+---
+
+## Known gaps — say these out loud rather than reporting a wrong number
+
+- **Cost is derived**, from `model` + tokens. Several adapters ship **no tokens at all**
+  (`kiro`, `vscode`, `zed`, and `cursor` on one of its two storage paths), so their cost
+  reads `$0` — which is *unknown*, not free. `memhouse doctor` names them.
+- **Per-message timestamps are interpolated** for most adapters — only the session bounds
+  are real. Hour-of-day and "peak time" charts inherit that.
+- **`text` stops at 50,000 chars**, tool `args` at 20,000. A missing tail is truncation,
+  not absence.
+- **Tool *results* are not stored at all.** If the question is "what did that command
+  print", the house cannot answer it.

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

@@ -0,0 +1,148 @@
+---
+name: access
+description: Bring someone onto this memhouse ClickHouse, or let them read your house — mint a new member with their own house and the env file their install needs, grant a housemate read-only access to yours, list who can currently read it, or revoke. Use when the user says "invite X", "add X to memhouse", "get my friend set up", "share my memory with X", "let X see my sessions", "who can read my memory", "stop sharing with X". Inviting comes BEFORE sharing — you can only grant a user who already exists. Read-only by construction on the sharing side: a share can never let anyone write to or delete your memory.
+user-invocable: true
+argument-hint: "invite <name> | share <name> | list | revoke <name>"
+allowed-tools: Bash
+---
+
+# /mem:access — who exists, and who may read
+
+Two things that look alike and are not:
+
+- **Invite** mints a ClickHouse *user* and their own *house*. Needs an administrator.
+- **Share** grants an existing user `SELECT` on *your* house. You can do this yourself.
+
+**Read `../reference/HOUSE.md` first** for the connection block. One rule dominates
+everything here: **a password must never enter this conversation.** memhouse ships this
+transcript into the house, and the archive is insert-only — a credential pasted here
+cannot be withdrawn.
+
+---
+
+## Invite — mint a member
+
+This runs the `memhouse invite` CLI and nothing else. **Do not hand-run `CREATE USER` /
+`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
+   `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_]*`;
+   refuse otherwise) and the **URL the invitee will reach the house at** — not localhost,
+   which is *their* machine. Do not ask about an admin credential yet; the next step
+   usually needs none. Default is their own house — omit `--db`.
+
+3. **Run it from the directory the file should land in** (step 4), bare first:
+
+   ```
+   memhouse invite <name> --url <url> [--db <shared-house>]
+   ```
+
+   `invite written: …` → go to step 4, and no secret touched this conversation.
+
+   Otherwise read WHICH refusal came back; they need different answers.
+
+   **"cannot reach `<url>` …"** — the address, not your privileges. A `deploy --local`
+   house is loopback-bound on purpose, so no LAN address reaches it and no invitee could
+   either. Ask 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 lacks. Ask which case
+   applies rather than assuming:
+
+   - *They run the ClickHouse.* Hand them the line to run THEMSELVES, with
+     `--admin-password` left OFF so it is prompted for — out of the process list and out
+     of shell history:
+
+     ```
+     memhouse invite <name> --url <url> --admin-user <admin>
+     ```
+
+     **You cannot run that yourself:** the prompt needs a TTY your Bash tool lacks, so it
+     refuses with "no TTY to prompt on" — and the fix is NOT `--admin-password`, which
+     would put the credential in this transcript.
+
+   - *Someone else runs it.* They cannot invite, and no flag changes that. Print the
+     statements for whoever administers the server — this contacts nothing:
+
+     ```
+     memhouse invite <name> --url <url> --print-sql
+     ```
+
+   **"house `<db>` already exists and holds N messages"** — STOP. That house is somebody's
+   memory. Report the row and writer counts and let the user choose: a different handle,
+   a different `--db`, or `--adopt` if sharing that house is genuinely the intent. Never
+   pass `--adopt` on your own initiative.
+
+4. **Put the file where they can attach it.** The CLI writes `invite-<name>.env` into the
+   current directory and the user sends it by hand — so run from their downloads
+   directory, or move it there. **Never leave it in a git repo.** Confirm it is present
+   and mode `600`, state the full path, and **never print its contents**.
+
+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`.
+
+   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
+   not follow them.
+
+---
+
+## Share — let someone read your house
+
+Sharing runs the `memhouse share` CLI. **Do not hand-write `GRANT` or `CREATE ROW POLICY`
+for this** — partial sharing has four ways to go wrong quietly, and the command handles
+each one:
+
+```
+memhouse share <user>                          the whole house
+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
+memhouse share <user> --revoke                 withdraw
+```
+
+Scopes: `session=`, `project=`, `folder=`, `host=`, `source=`, `since=`, `until=`, and
+they combine — `--only project=memhouse,since=2026-08-01`. Report back the counts it
+prints (`2121 of 22488 rows`), because that is what the person will actually see.
+
+**Say what a full share exposes** before running one: every session in the house, from
+every machine, project and editor, including anything ever pasted into one. If that is
+more than the user meant, `--only` is the answer, not a warning.
+
+**Never widen without being asked.** Re-running `memhouse share <user>` with no `--only`
+on someone currently scoped turns their partial share into a full one — the command says
+so, and you should surface that line rather than let it pass.
+
+### Why the CLI and not SQL
+
+- A permissive catch-all policy for everyone else is the obvious design and it **fails
+  open**: measured, a second scoped user saw all 22,500 rows instead of their 1,860.
+- Partial sharing depends on `users_without_row_policies_can_read_rows`, which is server
+  config, not a query setting, and whose default has moved between versions. The command
+  measures the behaviour before creating the first policy and refuses on a server that
+  would blindfold your existing readers.
+- Revoking the grant alone leaves the policies behind, and a later re-share silently
+  reinherits the old scope.
+- A policy on `messages` but not `tool_calls` leaks. All three rooms move together.
+
+If the command refuses because the server hides rows from unpolicied readers, relay its
+message — a full share still works there; only `--only` is unavailable until an admin
+sets that config.
+
+## Never
+
+Never accept a password typed into the conversation, and never print one. Never invent an
+admin credential. Never suggest storing one on disk. Never grant beyond `SELECT` — write
+access to your rooms is not a thing to hand out, and `ALL` would let the other side delete
+your memory. If the binary is absent, stop and say so rather than improvising the SQL.

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

@@ -12,6 +12,9 @@ A member owns one database. An **administrator** owns the ClickHouse: every hous
 account, every grant. This skill is the second one, and it is the only skill allowed to
 act outside the caller's own house.
 
+**Read `../reference/HOUSE.md` first** — connection, schema, and the traps every query
+here inherits.
+
 **An admin password must never enter this conversation.** memhouse ships this transcript
 into the house you are administering, so a password pasted here is a password published
 to the archive — and unlike a file you can delete, the archive is insert-only. Resolve
@@ -82,6 +85,32 @@ Reads worth knowing — reach for these before inventing SQL:
 | running queries | `SELECT query_id, user, elapsed, formatReadableSize(memory_usage) AS mem, substring(query,1,120) AS q FROM system.processes` |
 | unfinished mutations | `SELECT database, table, mutation_id, command, parts_to_do, latest_fail_reason FROM system.mutations WHERE NOT is_done` |
 
+### Sharing on someone else's behalf
+
+A member runs `memhouse share` against their own house. An administrator can do it for
+any house — useful when someone asks you to open theirs, or to audit what is open:
+
+```bash
+# what every house has opened up, server-wide
+adm "SELECT database, short_name, table, select_filter FROM system.row_policies ORDER BY database, short_name FORMAT PrettyCompact" "?readonly=1"
+adm "SHOW GRANTS FOR <user>"
+```
+
+To change a share, prefer running the member's own command with their credential over
+hand-writing SQL — the CLI handles the four traps (a permissive catch-all failing open,
+the server setting that decides whether unpolicied readers see anything, revoke leaving
+policies behind, and the three rooms drifting out of step). When you must do it as
+admin, mirror exactly what the CLI does: a policy on **all three rooms** or none, and
+`DROP ROW POLICY` on every room when withdrawing.
+
+**Dropping a house does not drop its row policies.** They persist as orphans, and a house
+later recreated under the same name silently inherits them. After any `DROP DATABASE`:
+
+```bash
+adm "SELECT short_name, table FROM system.row_policies WHERE database = '<db>'"
+# then DROP ROW POLICY <name> ON <db>.<table> for each
+```
+
 **Prefer a CLI verb over raw SQL wherever one exists.** `memhouse invite <name> --url …`
 provisions a member correctly — right grants, right pin, refuses a house that already
 holds someone's messages — and it takes `--admin-user`/`--admin-password`, so it works

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

@@ -0,0 +1,99 @@
+---
+name: house
+description: The state of your memory and who is around it — what memhouse is and how to use it, whether shipping is working, what the house holds (sessions, messages, tokens per editor), how fresh it is, which machines write into it, which houses you can read, and who can read yours. Use for "what is memhouse", "how do I use this", "is my memory working", "how much is stored", "when did it last ship", "which machines are shipping", "who can see my memory", "whose memory can I see", "who else is on this server" — and as the first answer when another /mem skill fails because nothing is configured yet, or before debugging why a search found nothing.
+user-invocable: true
+argument-hint: ""
+allowed-tools: Bash
+---
+
+# /mem:house — what this is, whether it works, and who is around it
+
+**Invoking this IS the request. Run the report and present it; there is nothing to
+clarify.** Read-only throughout.
+
+**Read `../reference/HOUSE.md` first** — connection, schema, and the epoch filter every
+count below depends on.
+
+## Nothing configured yet? Answer that instead
+
+If the connection block finds no house, do not report an error — explain the product and
+stop:
+
+> **memhouse** gives your coding agents a memory. A local shipper parses your sessions
+> from 17 editors — Claude Code, Codex, Cursor, Zed, Gemini CLI and more — and writes
+> them as typed rows into a ClickHouse database **you own**. Nothing is embedded or
+> summarised; the transcripts are kept verbatim, and the house outlives the local files,
+> which most editors delete after about 30 days.
+>
+> Then any agent can read it: `/mem:recall` answers from your own history instead of
+> starting from zero.
+>
+> To set it up: `npm install -g memhouse` then `memhouse onboard`. No ClickHouse yet?
+> `memhouse deploy --local` stands one up bound to loopback. Someone invited you?
+> `memhouse install --env invite-<you>.env`.
+
+## The report
+
+Lead with the one-line verdict — *working and current*, *working but stale*, or *not
+shipping* — then the detail.
+
+**1. Identity and reach.** `memhouse whoami` — who this credential is and what it may do.
+`memhouse status --json` — daemons, connection, counts, freshness. Prefer these over
+hand-rolled queries; they already know the schema.
+
+**2. What the house holds**, per editor. Epoch filter required or every number is inflated:
+
+```sql
+SELECT source,
+       uniqExact(session_id) AS sessions,
+       count() AS messages,
+       sum(input_tokens + output_tokens + cache_read_tokens + cache_write_tokens) AS tokens,
+       formatDateTime(max(ts), '%Y-%m-%d %H:%i') AS newest
+FROM messages
+WHERE origin != 'ship'
+   OR (session_id, user_id, epoch) IN (
+        SELECT session_id, user_id, max(epoch) FROM messages
+        WHERE origin = 'ship' GROUP BY session_id, user_id)
+GROUP BY source ORDER BY messages DESC
+```
+
+**A source shipping zero tokens is not free — it is unmeasured.** `kiro`, `vscode`, `zed`
+and one of `cursor`'s two storage paths extract no usage, so their cost reads `$0`. Say
+"unknown", never "$0", and point at `memhouse doctor`.
+
+**3. Which machines write here**, and whether this one is among them:
+
+```sql
+SELECT user_id AS member, host AS machine, count() AS rows,
+       formatDateTime(max(ingested_at), '%Y-%m-%d %H:%i') AS last_write
+FROM messages GROUP BY user_id, host ORDER BY last_write DESC
+```
+
+A machine silent for days is the usual reason a search finds nothing. Note that the
+*fleet heartbeat* records that a pass CONNECTED, not that rows landed — so treat
+`last_write` from the data above as the truth, and be sceptical of a healthy-looking
+heartbeat beside a stale `last_write`.
+
+**4. Who can read your house, and whose you can read.** Best-effort by design — ClickHouse
+shows a credential only what it may see, so on someone else's server sections come back
+thin. Say what could not be seen rather than guessing.
+
+```sql
+-- houses your credential can reach; anything that is not yours was shared with you
+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
+-- 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 —
+a member cannot read `system.grants`. Present it as "what memhouse recorded", and say
+that a grant made by hand would not appear.
+
+## Closing
+
+End with the one useful next step, not a menu: reopen a session (`memhouse resume <id>`),
+fix a stale machine (`memhouse update` there), start shipping (`memhouse onboard`), or
+bring someone in (`/mem:access`). If everything is healthy, say so in one line and stop.

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

@@ -0,0 +1,119 @@
+---
+name: recall
+description: Retrieve from past agent conversations and answer from them — search every session ever shipped from all 17 editors (Claude Code, Codex, Cursor, VS Code, Zed, Gemini CLI, …) across every project and machine, read the actual transcripts, and answer with citations. Use whenever the user refers to something not in the current context - "how did I fix X last time", "what approach did we settle on", "why did we choose Z", "find that conversation about Y", "did I ever try W", "what was I working on", "show my recent sessions", "sessions from last week", "remind me how I did it". Reach for this BEFORE saying you do not know about prior work. Also reads a housemate's memory when they name it ("how did yigit fix X"). For numbers rather than transcripts — spend, model mix, tool rankings — use /mem:sql.
+user-invocable: true
+argument-hint: "<question, terms, or 'recent sessions'>"
+allowed-tools: Bash
+---
+
+# /mem:recall — find it, read it, answer from it
+
+The house is the archive that OUTLIVES the transcripts on disk. Claude Code compacts and
+deletes local sessions, so for anything older than ~30 days this is the only place the
+answer still exists.
+
+**The synthesis is yours; the store is not.** memhouse runs no LLM in its write or read
+path — this skill retrieves rows and YOU read them. Never present a guess as a retrieval:
+if the house has nothing, say so.
+
+**Read `../reference/HOUSE.md` first** — connection, schema, and the three traps
+(epoch filtering, `(session_id, user_id)` joins, escaping). Every query below assumes it.
+
+## Which shape is being asked for
+
+One skill, three depths. Pick by what the user wants back, not by which words they used.
+
+- **A question** ("how did I fix X") → retrieve, read the turns, answer with citations.
+- **A conversation** ("find the chat about Y") → locate sessions, describe them, offer
+  to read one.
+- **An orientation** ("what was I working on") → list recent sessions and stop.
+
+When it is ambiguous, do the deepest one that fits — an answer with citations also tells
+them which session it was, whereas a bare list does not answer anything.
+
+## Answering a question
+
+**1. Extract terms that would appear in the ANSWER, not the question.** "How did I fix
+the ClickHouse auth error?" → `ClickHouse auth`, `Authentication failed`, `ACCESS_DENIED`.
+Error strings beat paraphrases; identifiers beat prose. Run 2–3 variants — and search
+each term SEPARATELY, because the columns hold text, not concepts: a needle of
+`clickhouse ttl` matches only that exact adjacency. On a real house `%clickhouse ttl%`
+found 8 messages where `%clickhouse%` AND `%ttl%` found 1,461.
+
+```sql
+SELECT session_id, user_id, any(folder) AS folder,
+       formatDateTime(max(ts), '%Y-%m-%d') AS day, count() AS hits,
+       substring(anyIf(text, positionCaseInsensitive(text, 'NEEDLE') > 0), 1, 300) AS sample
+FROM messages
+WHERE text_ngram LIKE '%needle%'
+  AND (origin != 'ship'
+       OR (session_id, user_id, epoch) IN (
+            SELECT session_id, user_id, max(epoch) FROM messages
+            WHERE origin = 'ship' GROUP BY session_id, user_id))
+GROUP BY session_id, user_id
+ORDER BY hits DESC, max(ts) DESC
+LIMIT 8
+```
+
+`anyIf(...)` so the sample is a line that actually matched — `any(text)` returns an
+arbitrary message from the session and misled two readers in three. **Order by `hits`,
+not just recency**: a session mentioning the term 197 times outranks yesterday's passing
+reference.
+
+**2. Read the strongest sessions — the turns, not the hit line.** Pull a window around
+the match so you see the resolution, not the complaint:
+
+```sql
+SELECT seq, role, substring(text, 1, 2000) AS text
+FROM messages
+WHERE session_id = '<sid>' AND user_id = '<uid>'
+  AND seq BETWEEN <hit_seq - 3> AND <hit_seq + 12>
+ORDER BY seq
+```
+
+Apply the epoch filter here too — an unfiltered read of a compacted session interleaves
+two parses of the same conversation.
+
+**3. Answer, then cite.** Lead with the answer. Under it list the sessions it came from —
+`session_id`, date, project — so the user can reopen one (`memhouse resume <session_id>`
+prints the command). Quote decisive lines verbatim where exact wording matters: an error
+string, a command, a config value.
+
+**4. Nothing found is an answer.** Say what you searched and where coverage ends
+(`SELECT min(ts), max(ts), count() FROM messages`) rather than padding. Check the obvious
+causes first: wrong case (the columns are lowercased), a phrase that never occurred
+adjacently, or a house that simply has not shipped that project.
+
+## Finding a conversation
+
+Same first query, then describe what you found — project, editor, date, how many hits,
+one representative line each. Offer to read the strongest. Do not dump ten rows and stop.
+
+## Listing recent sessions
+
+`memhouse sessions-query` prints a self-contained rollup (it carries its own `FINAL`);
+prefer it over hand-joining. For a plain list:
+
+```sql
+SELECT session_id, name, source, host, project,
+       formatDateTime(started_at, '%Y-%m-%d %H:%i') AS started, message_count
+FROM sessions
+ORDER BY started_at DESC
+LIMIT 20
+```
+
+Narrow with `WHERE project = '…'`, `source = 'cursor'`, `host = '…'`, or a date range as
+asked. In a shared house every member's sessions are here — add `AND user_id = '<name>'`
+only when the user asks for one person's.
+
+## What can bite
+
+Beyond the three in the reference:
+
+- **Ranking is yours.** There is no relevance score in the store. `hits` plus recency is
+  the whole of it — say so rather than implying the top row is "the best match".
+- **Tool *results* are not stored.** "What did that command print" is unanswerable from
+  the house; only the invocation and its arguments survive.
+- **`memhouse search`** exists as a CLI, but it joins your terms into ONE literal phrase
+  and orders by date alone. Prefer the SQL above; reach for the CLI only for a quick
+  one-word look.