memhouse 0.15.0 → 0.17.0

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

@@ -1,130 +0,0 @@
----
-name: share
-description: Share your conversation memory with another user on the same ClickHouse — grant them read-only access to your house, list who can currently read it, or revoke a share. Use when the user says "share my memory with X", "let X see my sessions", "who can read my memory", "stop sharing with X". Read-only by construction — a share can never let anyone write to or delete your memory.
-user-invocable: true
-argument-hint: "[<user> | revoke <user> | (nothing: list current shares)]"
-allowed-tools: Bash
----
-
-# /mem:share — a read-only window into your memory
-
-Three forms, decided by the arguments:
-
-- `/mem:share yigit` — let `yigit` read this house
-- `/mem:share revoke yigit` — close that window
-- `/mem:share` — who can read this house right now
-
-Sharing is a ClickHouse GRANT and nothing else — memhouse adds no layer on top, so what
-you grant is exactly what they get: `SELECT`, never write, never delete. Your own grant
-carries `WITH GRANT OPTION` on SELECT only (installs from 0.10.0 on), so you can open
-this window yourself and can hand on nothing more.
-
-## Connection
-
-**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
-MEMHOUSE`, no `set -x` around these commands.
-
-```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 — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
-  echo "Run: memhouse install" >&2
-  exit 1
-fi
-
-# NO readonly=1 on this skill's grant/revoke calls — GRANT is refused under readonly.
-# The list query below still pins it.
-curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
-  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}" <<'SQL'
-<the statement>
-SQL
-```
-
-## Grant — `/mem:share <user>`
-
-The user name goes into SQL unquoted: **refuse anything not matching
-`[A-Za-z][A-Za-z0-9_]*`** rather than quoting it — a name you cannot type bare is a name
-that will be gotten wrong everywhere else too.
-
-**Validate `<user>` FIRST, once, and use only the validated token — in the GRANT, the
-REVOKE, and the house_meta record alike.** The record INSERT is a quoted literal;
-anything that has not passed the name check must never reach it.
-
-**`<db>` below is the LIVE value of `$MEMHOUSE_DB` — print it with the connection
-(`echo "house: $MEMHOUSE_DB"`) and use THAT in every statement and every piece of
-advice.** Driven live, a model filled `<db>` in the admin advice with the literal
-fallback `mem` while the real house was named differently — advice the admin would have
-run against the wrong database.
-
-```sql
-GRANT SELECT ON <db>.* TO <user>
-```
-
-(`<db>` is `$MEMHOUSE_DB`.) Then RECORD it in the house's own memory — a member cannot
-read `system.grants` (measured: `Not enough privileges … SELECT ON system.grants`), so
-this record is what the list form reads back:
-
-```sql
-INSERT INTO house_meta (key, value) VALUES ('share:<user>', 'granted <today, YYYY-MM-DD>')
-```
-
-Verify the grant took by USING it if you can, or simply report the server accepted it —
-do not call `SHOW GRANTS FOR <user>` (it needs privileges a member does not hold).
-
-Two failure shapes, both to report exactly:
-
-- `There is no user ... in user directories` — the person has no ClickHouse user on this
-  server yet. Joining comes first: they run `memhouse install` against this server (or
-  the admin runs `memhouse install --print-sql --member <user> --db <their-house>`).
-  A share cannot create a user, by design.
-- `Not enough privileges` — either this house predates 0.10.0 (your own grant carries
-  no grant option), or **the configured house is not yours to share** (a team house, or
-  someone else's). Only suggest the admin remedy when the house is the user's OWN — the
-  grant-option statement hands them standing power to share it, which is the owner's
-  decision, not a fix. For their own pre-0.10 house, print for the ADMIN:
-  `GRANT SELECT ON <db>.* TO <user>` — and to make future shares self-serve:
-  `GRANT SELECT ON <db>.* TO <your-user> WITH GRANT OPTION`.
-  For a house that is not theirs, say so and stop: the owner shares it, not you.
-
-Tell the user how their friend actually reads it: qualified names —
-`SELECT … FROM <db>.messages …` — from /mem:ask, /mem:search or /mem:sql on the friend's
-side, with the same epoch filter those skills already carry.
-
-## Revoke — `/mem:share revoke <user>`
-
-```sql
-REVOKE SELECT ON <db>.* FROM <user>
-```
-```sql
-INSERT INTO house_meta (key, value) VALUES ('share:<user>', 'revoked <today, YYYY-MM-DD>')
-```
-
-Revoking a share that never existed is a no-op, not an error — say which it was (the
-`share:<user>` record answers that).
-
-## List — `/mem:share` (no arguments)
-
-From the house's own record (append `&readonly=1` to the URL for this one):
-
-```sql
-SELECT substring(key, 7) AS user, value AS state,
-       formatDateTime(updated_at, '%Y-%m-%d %H:%i') AS at
-FROM house_meta FINAL WHERE key LIKE 'share:%' ORDER BY key
-```
-
-Latest-wins per user: `granted …` rows are live shares, `revoked …` rows are closed
-ones. Be honest about the record's edge: it shows shares made THROUGH THIS SKILL — a
-grant the admin issued directly will not appear. The authoritative list is the admin's
-one query: `SELECT user_name, access_type FROM system.grants WHERE database = '<db>'`
-(members cannot run it; `system.grants` needs privileges a member does not hold).
-
-## What this never does
-
-No `GRANT ALL`, no write grants, no `WITH GRANT OPTION` onward, no user creation, no
-grants on any database but your own. If the user asks for more than read access, that is
-the shared-house model (both members in ONE database) — a decision, not a grant; point
-them at `memhouse install --db <shared>` and stop.

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

@@ -1,139 +0,0 @@
----
-name: status
-description: Show the state of the memory system — what the house holds (sessions, messages, tokens per editor), how fresh it is, its schema generation and migration state, and every machine writing into it. Use when the user asks "is my memory working", "how much is stored", "when did it last ship", "what's in the house", "which machines are shipping", or before debugging why a search found nothing.
-user-invocable: true
-argument-hint: ""
-allowed-tools: Bash
----
-
-# /mem:status — the state of the memory system
-
-**Invoking this skill IS the request. Run the report immediately — connect, run the four
-sections below, and present the summary. There are no arguments and nothing to clarify;
-do not describe this skill or ask what to check.** (Driven live, a model did exactly
-that: it summarized the file and asked "is there something specific?" — a status command
-that answers with a question has failed.)
-
-One report, four sections: what the house holds, how fresh it is, what generation it is
-at, and who writes into it. Read-only; nothing here changes anything.
-
-## 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.
-
-```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 — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
-  echo "Run: memhouse install" >&2
-  exit 1
-fi
-
-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
-```
-
-## The report — run these, then summarize
-
-**1. What the house holds** — per editor, CURRENT parses only (the rooms retain
-superseded parses; an unfiltered count over-reports on any compacted session):
-
-```sql
-SELECT source,
-       uniqExact(session_id) AS sessions,
-       count() AS messages,
-       sum(input_tokens + output_tokens + cache_read_tokens + cache_write_tokens) AS tokens
-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 sessions DESC
-```
-
-**2. Freshness and coverage** — when the archive starts, ends, and last received:
-
-```sql
-SELECT formatDateTime(min(ts), '%Y-%m-%d') AS oldest,
-       formatDateTime(max(ts), '%Y-%m-%d %H:%i') AS newest,
-       formatDateTime(max(ingested_at), '%Y-%m-%d %H:%i') AS last_ingest
-FROM messages
-```
-
-A `last_ingest` hours old with the user actively working means the shipper is not
-running — say so and point at `memhouse status` / `memhouse start` on that machine.
-
-**3. Generation and migration state** — the house's record of itself (absent on a
-pre-0.10 house; that absence is itself the answer: say the house predates the record):
-
-```sql
-SELECT key, value FROM house_meta FINAL
-WHERE key IN ('schema_version', 'min_writer_schema') ORDER BY key
-```
-```sql
-SELECT id, argMax(status, event_at) AS status,
-       formatDateTime(max(event_at), '%Y-%m-%d %H:%i') AS at
-FROM house_events WHERE kind = 'migration' GROUP BY id ORDER BY at DESC LIMIT 3
-```
-
-A `pending` here with nothing running means an interrupted migration — name
-`memhouse migrate` (it refuses stale leftovers legibly rather than clobbering them).
-
-**4. The fleet** — every machine writing into this house, from the DATA (a pre-0.10
-writer records nothing about itself, so rows-without-record is the finding):
-
-```sql
-SELECT user_id, host, 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
-```
-```sql
-SELECT key, value FROM house_meta FINAL
-WHERE key LIKE 'client_version:%' OR key LIKE 'client_schema:%' OR key LIKE 'last_ship:%'
-```
-
-Match `client_*:<member>@<host>` against the data rows. A `(user_id, host)` pair with
-rows but NO `client_*` record is a **pre-0.10 memhouse still writing** — flag it: its
-re-ships delete retained parses, and the fixes are upgrade it or (as admin)
-`REVOKE ALTER DELETE, ALTER UPDATE ON <db>.* FROM <member>`.
-
-**5. Client freshness** — is the installed memhouse behind the published release? This is a
-shell check, not SQL (it reads the local binary and the npm registry, no house involved):
-
-```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}"
-```
-
-Compare the two as `MAJOR.MINOR.PATCH`. Report freshness, and size the nudge to the gap:
-
-- **up to date** (installed ≥ latest) — one line: "client 0.X.Y, current."
-- **small gap** (same major+minor, a patch or two behind) — a gentle note: "a newer patch
-  0.X.Z is out; `memhouse update` when convenient."
-- **big gap** (latest MAJOR or MINOR is ahead, or many patches) — surface it prominently and
-  **offer to update**: "your memhouse is 0.A.B but 0.C.D is released — run **`memhouse
-  update`** to upgrade; it also refreshes the `/mem:*` plugin, then `/reload-plugins`."
-- either side **unknown** (no binary on PATH, or the registry did not answer) — say which,
-  don't guess. A plugin-only install with no CLI can't self-update; point at
-  `npm i -g memhouse`.
-
-Never run `memhouse update` yourself — it restarts daemons and may migrate the house.
-Offer the command; the pilot runs it.
-
-## Presenting it
-
-Lead with one line of verdict ("healthy: N sessions across M editors, last ingest X
-minutes ago" — or the one thing wrong). Then the per-editor table, then anything from
-sections 3–5 that needs action. A **big version gap (section 5) is an action** — put the
-`memhouse update` offer near the top, not buried. Skip empty sections; do not pad. If the
-house is unreachable, say which URL refused and stop — never guess another endpoint.

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

@@ -1,97 +0,0 @@
----
-name: users
-description: Show the people around your memory — who writes into your house and from which machines, which other houses on this ClickHouse you can read, and who can read yours. Use when the user asks "who can see my memory", "whose memory can I see", "which houses are on this server", "who else ships here", or before/after sharing with /mem:share.
-user-invocable: true
-argument-hint: ""
-allowed-tools: Bash
----
-
-# /mem:users — who is around your memory
-
-**Invoking this skill IS the request. Run the report immediately and present it; there
-are no arguments and nothing to clarify.** Read-only throughout.
-
-Throughout, `<your-db>` is the live `$MEMHOUSE_DB` and `<your-user>` the live
-`$MEMHOUSE_USER` — take both from the connection environment, never from the
-conversation or from examples.
-
-Answers three questions, best-effort by design: ClickHouse shows a credential only what
-it may see, so on someone else's server some sections legitimately come back thin — say
-what could not be seen rather than guessing.
-
-## Connection
-
-**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
-MEMHOUSE`, no `set -x` around these commands.
-
-```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 — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
-  echo "Run: memhouse install" >&2
-  exit 1
-fi
-
-curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
-  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&readonly=1" <<'SQL'
-<the query>
-FORMAT PrettyCompact
-SQL
-```
-
-## The report
-
-**1. Who writes into YOUR house** — members × machines, from the data (same ground truth
-as /mem:status's fleet):
-
-```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
-```
-
-**2. Whose memory YOU can read** — every database your credential reaches is one someone
-gave you (or your own):
-
-```sql
-SHOW DATABASES
-```
-
-Drop `system`, `information_schema`, `INFORMATION_SCHEMA`, `default` unless they hold
-rooms. For each OTHER house listed, it is readable because of a grant — one line each:
-`house 'polat' — readable (shared with you); query it as polat.messages`.
-
-**3. Who can read YOURS** — from the house's own share record (`system.grants` needs
-privileges a member does not hold, so the record /mem:share keeps is the readable
-source; an admin-issued grant will not appear in it, and the report should say so):
-
-```sql
-SELECT substring(key, 7) AS user, value AS state
-FROM house_meta FINAL WHERE key LIKE 'share:%' ORDER BY key
-```
-
-`granted …` = a live read window (`/mem:share`); `revoked …` = closed. If the caller IS
-privileged, prefer the authoritative form:
-`SELECT user_name, groupUniqArray(access_type) FROM system.grants WHERE database = '<your-db>' AND user_name != '<your-user>' GROUP BY user_name`
-— try it first, fall back to the record on refusal.
-
-**4. Every user on the server** — usually admin-only; try it, and if refused say
-"(full user list needs admin — showing only what this credential can see)":
-
-```sql
-SELECT name FROM system.users ORDER BY name
-```
-
-## Presenting it
-
-Four short sections in that order, each with its one-line meaning ("2 machines ship into
-your house", "you can read polat's memory", "yigit can read yours — read-only", …).
-Empty section three means "no shares made through /mem:share" — and ONLY that. The
-record cannot see an admin-issued grant, so never promise "nobody can read your memory"
-from an empty ledger; say "no shares recorded through this skill — the authoritative
-check is the admin's system.grants query" and print it. Point at `/mem:share <user>` /
-`/mem:share revoke <user>` for changes.