memhouse 0.18.8 → 0.18.10

package/README.md

@@ -1,452 +1,83 @@
 # memhouse
 
-**Claude Code deletes your transcripts after 30 days.** (`cleanupPeriodDays`,
-default 30 — session files are removed at startup.) Measured on the machine this
-was built on: months of daily use, and the oldest surviving local transcript was
-nine days old. Every problem you solved before that exists nowhere — unless
-something durable was keeping it.
+**Your coding agents forget. Their transcripts get deleted too.** Claude Code removes
+session files after 30 days (`cleanupPeriodDays`); on the machine this was built on, the
+oldest surviving local transcript was nine days old. Every problem solved before that
+exists nowhere, unless something durable kept it.
 
-memhouse is that something. It reads the session transcripts your editors already
-write to disk — **17 of them**: Claude Code, Codex, Cursor, Zed, Copilot, Gemini
-CLI and the rest — parses them locally, and ships typed rows into a ClickHouse
-**you choose**: a container on this laptop, a box you run, your company's cluster,
-or ClickHouse Cloud. memhouse runs no service of its own — there is no memhouse
-cloud to sign up for and nothing is proxied through anyone — so the account is
-yours and the data is wherever you decided to put it. Then you can search every
-past session, see what it cost, resume the conversation that solved this before,
-and let an agent query its own history.
+memhouse keeps it. It reads the session transcripts your editors already write to disk
+(16 adapters covering 18 apps: Claude Code, Codex, Cursor, Zed, Copilot, Gemini CLI and
+the rest), parses them locally, and ships typed rows into a ClickHouse **you choose**. That
+can be a container on this laptop, a box you run, your company's cluster, or ClickHouse
+Cloud. memhouse runs no service of its own and proxies nothing. Then you, and your agents,
+can search every past session, see what it cost, and reopen the one that solved this
+before.
 
-And every row says where it came from, in a way no client can fake: `user_id` is
-stamped **by the server** (`MATERIALIZED currentUser()`, async inserts pinned off
-so the stamp cannot be skipped) and `host` is a fingerprint minted once per
-install. A team pointed at one house is a team memory with real attribution — not
-a label somebody's client claimed.
+Every row says where it came from, in a way no client can fake. `user_id` is stamped by
+the server (`MATERIALIZED currentUser()`), and `host` is a fingerprint minted once per
+install. A team pointed at one house gets a shared memory with real attribution.
 
-```bash
-npm install -g memhouse
-memhouse onboard
-```
-
-That is the whole install — no flags, nothing to compile. `onboard` finds your
-editors, sets up a house, ships, and starts the dashboard.
-
-**On most Linux distros that first line needs `sudo`.** A distro-packaged Node puts
-its global prefix under `/usr`, which you do not own, so npm stops with `EACCES`.
-That is the single most likely place a first install stalls — measured on a clean
-Ubuntu machine:
-
-```bash
-ls -ld "$(npm prefix -g)"     # root-owned? use sudo. Owned by you? do NOT — see EACCES below
-sudo npm install -g memhouse
-```
-
-If the prefix is yours (Homebrew, fnm, nvm, volta), `sudo` is the wrong fix and
-makes it worse — [EACCES on install](#eacces-on-install) tells them apart.
-
-## No ClickHouse yet?
-
-`onboard` offers to run one for you if docker or podman is present:
-
-```bash
-memhouse deploy --local      # a loopback-bound ClickHouse, then install and ship
-```
-
-The house it stands up is **yours by name**: its superuser defaults to your OS
-username (`polat`, not `memhouse_root` — override with `--user`), and the house
-database defaults to the same name, so your memory lives at `polat.messages` and
-`WHERE user_id = 'polat'` reads like it should. The name
-and password are fixed when the data volume is first initialised, like any ClickHouse
-container, and reused on every redeploy after that.
-
-Otherwise point at one you already run, or hand the SQL to whoever administers it:
-
-```bash
-memhouse install --url https://… --user … --password …   # one you have
-memhouse install --admin-user … --admin-password …       # let memhouse build it
-memhouse install --print-sql                             # print the SQL, run it yourself
-```
-
-memhouse does not embed a database. If you have neither a ClickHouse nor a
-container engine, install one of the two.
-
-## Commands
-
-```text
-memhouse onboard | install | setup | discover | doctor | uninstall | reset
-memhouse ship [--full|--loop N] | search <terms> | stats | status
-memhouse resume <session-id>               print the command that reopens a session
-memhouse update [--check] [--channel TAG]  upgrade along the channel this install follows,
-                                           restart daemons, check the schema
-memhouse start | stop                      dashboard + shipper as daemons
-memhouse service install | uninstall       survive a reboot
-memhouse deploy --local | --down           stand up (or remove) a local house
-memhouse invite <name>                     mint a member + house, hand them one env file
-memhouse members [--db X]                  who is in a house, and what each can reach
-memhouse whoami [--admin]                  which credential is in play, and what it may do
-memhouse instance                          which memhouse this is: home, binary, house, rooms, scope, bindings
-memhouse rooms                             what your rooms are actually called
-memhouse share <user> [--only …|--revoke|--list]
-                                           let a housemate read yours, in whole or in part
-memhouse sessions-query                    print the session rollup SQL
-memhouse passwd                            rotate this member's password
-memhouse migrate | migrate-rooms [--dry-run] [--yes]
-                                           run whatever this house still needs
-memhouse relocate --to <url>               copy this house to a new ClickHouse, then repoint
-memhouse nightly [--out DIR]               build an installable tarball from this checkout
-memhouse plugins install claude            5 skills — house, recall, sql, access,
-                                           admin — into every Claude Code config
-                                           dir found
-memhouse prompt                            memory snippet for an agent's system prompt
-memhouse prompt --install                  an install prompt, rendered for this machine
-```
-
-Any command's own usage: `memhouse <command> --help` (or `-h`) — always prints usage,
-never runs the command.
-
-Every command works both ways: interactive for you, `--yes` / flags / `--json` for
-an agent — so an agent can install its own memory unattended.
-
-`onboard` offers the skills at the end, and `plugins` works across **every Claude Code
-config directory on the machine** — `~/.claude`, whatever `CLAUDE_CONFIG_DIR` points
-at, and each Kommander-style playbook under `~/.claude-playbooks/`. All are selected by
-default; answer with numbers to narrow it, or pass `--target DIR` for exactly one.
-Installing into just the default config is how `/mem:recall` ends up missing from
-the instance you actually work in, silently, since a missing skill never announces
-itself.
-
-Config resolves: flags → `MEMHOUSE_*` env → `$MEMHOUSE_HOME/env` (default
-`~/.memhouse/env`). There is no house-shaped default: with nothing configured, the
-commands that read or write memory refuse and say so rather than guessing
-`localhost:8123`, which on a lot of machines is a real house belonging to someone else.
-
-## Which sessions ship
-
-Everything on the machine, by default: every adapter, from wherever that editor keeps its
-sessions. `memhouse discover` prints what each adapter is watching and the variable that
-moves it:
-
-```
-Watched directories (override with the variable shown, in the env file):
-    claude       ~/.claude, ~/.claude-playbooks/kommander, …   [MEMHOUSE_CLAUDE_ROOTS]
-    codex        ~/.codex                                      [MEMHOUSE_CODEX_ROOTS]
-    gemini-cli   ~/.gemini                                     [MEMHOUSE_GEMINI_CLI_ROOTS]
-    cursor       ~/Library/Application Support/Cursor/User, …  [built-in]
-```
-
-Two kinds of line in the env file narrow it, or `--editors` / `--claude-roots` at install:
-
-```
-MEMHOUSE_EDITORS='claude'
-MEMHOUSE_CLAUDE_ROOTS='~/.claude-playbooks/kommander-chaos'
-```
-
-`MEMHOUSE_EDITORS` names the adapters to run. `MEMHOUSE_<EDITOR>_ROOTS` replaces one
-adapter's location: the adapter's name upper-cased, dashes to underscores. Claude is the
-one adapter with many roots (every Claude Code config directory), so its list may hold
-several; every other adapter has one store, so one path. Adapters marked `[built-in]`
-resolve a platform app-data directory and cannot be moved yet.
-
-An adapter name or a directory that does not exist is refused and reported against that
-adapter, never shipped from the default instead: a typo that quietly shipped nothing would
-look like a working install with an empty house, and one that quietly shipped the wrong
-store would be worse.
-
-## Channels
-
-`memhouse update` follows the npm dist-tag the install came from, not `latest` by
-reflex. A house published under another tag — `npm publish --tag team`, so one team can
-run a newer layout without every other house being dragged along — installs with
-`npm install -g memhouse@team`, and `update` keeps it there. The channel is inferred from
-the installed version; pin it with `MEMHOUSE_CHANNEL='team'` in the env file or
-`memhouse update --channel team`, which writes the same line. A tarball or checkout
-build sits on no tag and is never auto-updated; `update --check` says so and names the
-way forward. An invite from a house on a channel carries it, so the invitee follows it
-too.
-
-## Instances
-
-An instance is a home: an env file naming a house, the daemons shipping to it, and the
-playbooks whose sessions it ships (`MEMHOUSE_CLAUDE_ROOTS`). A machine can run several,
-each under its own `MEMHOUSE_HOME`, on different channels. `plugins install claude` from an
-instance installs into exactly the playbooks that instance ships and **binds** them: it
-writes `MEMHOUSE_HOME` and `MEMHOUSE_BIN` into each playbook's `settings.json` `env`, which
-Claude Code applies to every session there. So the `/mem:*` skills in a bound playbook read
-that instance's house and run that instance's binary, whatever the shell they were started
-from had. `plugins list` shows the binding; `plugins remove` takes it out. Everything else
-in `settings.json` is left as it was.
-
-## Going back into a session
-
-`search` finds the conversation; `resume` hands you back into it.
-
-```bash
-memhouse resume claude:6b1f…            # prints:  cd /path/to/project && claude --resume 6b1f…
-```
-
-It **prints** the command instead of running it. A resume run from the wrong directory
-or with a stale id does not fail — it opens a *new* session, and the transcript you
-wanted is still gone while the tool reports success. You paste it, so you see it first.
-
-Verified for **claude, codex and opencode**. Cursor, Zed, VS Code, Kiro, Copilot for
-JetBrains, Antigravity and Devin/Windsurf have no CLI that takes a session id, so
-there is nothing to resume into and `resume` says exactly that, rather than opening a
-folder and calling it the same thing. Everything else — goose, gemini-cli,
-cursor-agent, copilot-cli — is refused as *unverified*, which is a different sentence
-on purpose: nobody has read the flag out of its own `--help` yet, and guessing is how
-you print a command that quietly does the wrong thing. See `memhouse/resume.js`.
-
-## Which machine is which
-
-All of *your* machines ship into *your* rooms, and the `host` column is what tells them
-apart. So each install writes `~/.memhouse/host.json` — a random fingerprint, minted once
-— and every row that machine ships carries `<hostname>-<8 hex>` built from it.
-
-Random, not derived, because deriving it fails in both directions: two laptops that both
-answer to the default `MacBook-Pro` on the same platform hash to the **same** id and merge
-into one apparent machine, and renaming a machine **moves** a derived id so its own history
-appears to stop and a stranger's to begin. A stored fingerprint cannot collide and does not
-move — rename the machine and `status` says so while the id stays put.
-
-```bash
-memhouse status     # ✓ host: macminim-4127a95b
-memhouse doctor     # names every host in your rooms, and whether this one is among them
-```
-
-Then query one machine with `WHERE host = 'macminim-4127a95b'`.
-
-## Uninstalling, in three tiers
-
-```bash
-memhouse uninstall                   # stop everything; KEEP the config and this host's identity
-memhouse uninstall --credentials     # also forget the house and its password
-memhouse uninstall --full-removal    # all of ~/.memhouse, identity included
-```
-
-The default is deliberately the conservative one. Stopping the shipper is routine — before
-an upgrade, while debugging, when a laptop should go quiet for a week — and it should not
-also mean "forget which house I use and who this machine is". `--full-removal` asks first,
-because a later reinstall mints a **new** identity and this machine then reads as two
-machines in your history.
-
-**No tier touches your memory.** Transcripts live in ClickHouse, and everything the shipper
-wrote rebuilds from the local session stores with `ship --full`.
-
-## Staying current
+## Install
 
 ```bash
-memhouse update            # upgrade, restart the daemons, check the house schema
-memhouse update --check    # compare versions, change nothing
-```
-
-A bare `npm i -g memhouse@latest` does half the job. It does not restart the daemons,
-which keep parsing with the code they booted with (a shipper here once ran 1d16h out of
-a directory that had been *moved*); and it does not check whether your house predates a
-room the new shipper needs. `update` does both, and from a checkout it rebuilds
-`public/` — otherwise `git pull` serves you the previous release's dashboard forever.
-
-The daemons also notice on their own: each one compares the installed version against
-what it booted with and hands over — exiting under systemd/launchd so the supervisor
-restarts it, re-execing itself when nothing is supervising. `update` just makes it
-immediate.
-
-## How your memory is stored
-
-**A house is a database; its rooms are tables.** `sessions`, `messages` and `tool_calls`
-hold your turns. Every row says where it came from: `user_id`, stamped by the server
-(`MATERIALIZED currentUser()`, with async inserts pinned off so the stamp cannot be
-skipped), and `host`, the machine's install fingerprint. `WHERE user_id = 'alice'` is one
-person; `WHERE host = '…'` is one machine. Neither is forgeable from the client.
-
-**Your rooms are named for you, and one grant covers them.** Every member of a house holds
-`GRANT … ON mem.<name>_* TO <name>`: their own rooms, present and future, and nothing else
-in the database. That is the whole access model, and it is the same on a laptop, a team's
-server, or a kernel:
-
-| | rooms | the member holds |
-|---|---|---|
-| alone on your laptop | `mem.polat_*` | one grant on `mem.polat_*` |
-| a team on one server | `mem.polat_*`, `mem.alice_*`, … | each their own |
-
-A colleague can read their isolation back with `SHOW GRANTS` in one line, which is the
-property this rests on. There is no row policy to trust and no database-wide grant to
-worry about: `ALL ON mem.*` would cover rooms created later, which is how two people in one
-database once became a leak, so memhouse never issues it — not to a member, not to you.
-
-Standalone is a team of one. `memhouse deploy --local` creates the house with an admin
-credential (`memhouse_root`) and a member named after your OS user, keeps both in the env
-file, and ships as the member. Inviting a colleague later is `memhouse invite <name>`; the
-admin credential is already there.
-
-Reading across everyone is a `UNION ALL` over the rooms you hold:
-
-```sql
-SELECT user_id, count() FROM mem.polat_messages GROUP BY user_id
-UNION ALL
-SELECT user_id, count() FROM mem.alice_messages GROUP BY user_id
+npm install -g memhouse      # Node 24+; on a distro-packaged Node this needs sudo
+memhouse onboard             # finds your editors, sets up a house, ships, starts the dashboard
 ```
 
-An operator with an admin credential reads every room; a member reads the ones they own
-plus whatever was shared with them, and naming a room they do not hold is an error rather
-than a silent omission.
-
-### The house never destroys what it cannot rebuild
-
-**The shipper is insert-only.** It runs no `DELETE`, no `TRUNCATE`, no mutation of any
-kind, so no privilege it holds can lose you a row.
-
-That is not free, because ReplacingMergeTree is a dedupe engine, not a diff engine: a
-re-parse yielding *fewer* messages leaves the old higher-`seq` rows with nothing written
-over them. The shipper used to delete the session's rows first to clear that tail — and
-a shorter re-parse has two indistinguishable causes. Either an adapter bug was fixed and
-the extra rows are junk, or Claude Code **compacted** the transcript, or the retention
-window (`cleanupPeriodDays`, 30 days by default) took it. In the last two cases the house
-holds the only surviving copy, and the delete destroyed it.
-
-So rows carry an `epoch`: which parse of the session they belong to.
-
-- **Nothing changed** (the common case, including ordinary growth): same epoch, rows
-  dedupe exactly as before, no extra storage.
-- **Shorter, or rewritten at a position the house already holds**: the new parse goes to
-  `epoch + 1`. The old one stays complete and readable. You pay storage only when the old
-  rows are irreplaceable.
-
-Reads show one parse per session — the newest — so counts, tokens and cost are unchanged.
-`/mem:sql` and any hand-written query should filter the same way; the skill carries
-the clause.
-
-**Imported history is protected the same way.** `origin` says who wrote a row, and it is
-in the sorting key of `messages` and `tool_calls`, so ReplacingMergeTree cannot collapse
-an imported row against a shipped one. Anything you imported from an older house, another
-product, or a machine that no longer exists survives every re-ship. `sessions` is the
-deliberate exception — one row per session, no `origin` and no `epoch` in its key, because
-a session's metadata has a single current version and a second row makes every rollup
-count its messages twice.
-
-The shipper verifies the sorting keys before it writes and refuses if they are wrong, so
-an old house cannot be corrupted by a new shipper. `memhouse migrate-rooms` rebuilds it:
-copy, atomic swap, and the old room kept as `<room>_pre_epoch` for you to drop. The house
-records the move in `events`, and `memhouse doctor` reads it back.
-
-## Upgrading
-
-`memhouse update` upgrades the code, restarts the daemons, and — from 0.10.0 onward —
-detects a schema migration the house needs and prompts to run it.
+No ClickHouse yet? `memhouse deploy --local` runs one in docker or podman, bound to
+loopback, and installs against it. Already have one, or an invite from someone who does?
+See [install and onboard](docs/guides/install.md).
 
-**One exception: upgrading from 0.9.x.** That release predates migrations, and `update`
-runs the *old* version's code (it replaces itself mid-run), so it cannot prompt. After
-the upgrade the first ship refuses (nothing is lost) and tells you the one command to
-run by hand:
+## What you get
 
 ```bash
-memhouse update      # installs the new version, refuses to ship the old-schema house
-memhouse migrate     # the one-time rebuild it named — copy + atomic swap, nothing deleted
-memhouse doctor      # every line a check mark
+memhouse status                  # is it shipping, and how fresh
+memhouse search "auth error"     # full-text across every session, every machine
+memhouse resume claude-code:6b1f… # prints the command that reopens that session
+memhouse plugins install claude  # /mem:recall and four more skills for your agents
 ```
 
-If other machines ship into the same house as the same member, upgrade them too — a
-pre-0.10 shipper still deletes-before-reinsert; `memhouse doctor` flags any that are
-behind, and prints the `REVOKE ALTER DELETE, ALTER UPDATE` fallback that stops them
-destructively until you can.
+The dashboard is at `http://localhost:4640`, showing sessions, cost, models, tools and
+machines. From any Claude Code session, `/mem:recall how did I fix the ClickHouse auth
+error` answers from your own history.
 
-## Troubleshooting
+## Documentation
 
-### An editor reads zero sessions
-
-Five adapters — **cursor, zed, opencode, goose, antigravity** — read sessions out of
-SQLite files. That used to mean `better-sqlite3`, whose native binding is built by
-an npm install script; npm 12 blocks install scripts by default, so a plain install left
-all five reading nothing and the fix was a flag
-(`--allow-scripts=better-sqlite3`) you had to re-type on every upgrade. SQLite is
-`node:sqlite` now — part of Node — so that failure class is gone along with the flag.
-
-What can still go wrong is one store at a time: a `state.vscdb` locked by a running
-editor, a corrupt file, a schema a new editor release changed. None of it is silent —
-`memhouse discover` and `memhouse doctor` both name the skipped adapter and say why,
-and the other sixteen keep working.
-
-```bash
-npx -y memhouse discover      # no flags here either
-```
-
-### `EACCES` on install
-
-`sudo` is right for only one of the two causes, and what tells them apart is **who
-owns the prefix root** — not the path, and not the file npm named.
-
-```bash
-ls -ld "$(npm prefix -g)"
-```
-
-- **Owned by `root`** — a system-managed Node (distro packages under `/usr`).
-  Re-run with `sudo`.
-- **Owned by you** — the prefix is yours (Homebrew, fnm, nvm, volta), so the
-  root-owned file npm tripped on is a stray from an earlier `sudo npm`. Another
-  `sudo` adds more. Repair just that path:
-  `sudo chown -R "$(id -u):$(id -g)" <the path npm named>`. Same for `~/.npm`.
-
-The path proves nothing on its own: Homebrew's prefix is `/usr/local` on Intel and
-`/opt/homebrew` on Apple Silicon, and is yours in both cases.
+| | |
+|---|---|
+| [Tutorials](docs/README.md#tutorials) | your first house, joining a team's house, sharing memory |
+| [Guides](docs/README.md#guides) | install, update, invite, share, admin credentials, daemons, search, troubleshooting |
+| [Examples](examples/README.md) | runnable setups, from one machine up to a self-hosted team house |
+| [Release notes](docs/releases/) | what changed in each version, and how to upgrade |
+| [`AGENTS.md`](AGENTS.md) | installing memhouse as an agent, and working on this repository |
 
-### Daemons don't survive a reboot
+Any command's own usage: `memhouse <command> --help`. Every command works both ways:
+interactive for you, and `--yes` / flags / `--json` for an agent.
 
-`memhouse start` detaches with pidfiles — they outlive the shell, not a restart.
-`memhouse service install` writes a real user service instead (systemd `--user`,
-or a launchd LaunchAgent) and takes over. On Linux a `--user` unit stops at logout
-unless lingering is on; install detects that and prints the `loginctl` command.
+## What's supported
 
-A rootless podman house has the same problem for the same reason, and
-`deploy --local` says so.
+| Surface | Status |
+|---|---|
+| macOS | primary; developed and driven here daily |
+| Linux | installs, ships, `service install` (systemd `--user`), rootless podman `deploy --local`; exercised on Debian and Ubuntu |
+| Windows | **untested**; the adapters declare Windows paths, but no one has run an install |
+| ClickHouse | 25.11 and 26.x, both in CI |
+| Node | **24 or newer**. SQLite comes from `node:sqlite`; no native dependency, no build step |
 
 ## Working from a checkout
 
 ```bash
-npm install            # two runtime deps, no build step
+npm install            # two runtime dependencies, no build step
 node bin/memhouse.js …
 npm test               # syntax gate + unit checks
 ```
 
-`misc/origin-matrix.sh <label> <url> <user> <pass>` checks the import-protection
-guarantees against a real ClickHouse. `misc/tier-matrix-test.sh` walks the
-tier/ownership matrix against a real container engine on Linux. Both take minutes
-and are not part of `npm test`.
-
-## Layout
-
-| Path | What |
-|---|---|
-| `memhouse/` | the product — `DESIGN.md`, `per-member/`, `shipper/`, `server/`, `delivery/` |
-| `editors/` | the 17 editor adapters (inherited from agentlytics; the crown jewels) |
-| `pricing.js` + `pricing.json` | the cost engine |
-| `ui/` | the dashboard SPA (built to `public/`, served by the memhouse server) |
-| `agency/` | the earlier agentlytics-agency wrap — prior art, not how memhouse works |
-| `TERMINOLOGY.md` | the constellation terminology canon |
-
-Deeper reading: `memhouse/DESIGN.md` (the bets, and why the room layout has moved three
-times), `memhouse/house/HOUSE.md` (the layout and the schema), `SECURITY.md` (what
-holds, and what does not), `memhouse/delivery/kernel-install.md`, `memhouse/COMPETITION.md`.
-
-Deferred designs (captured, not yet built): `docs/design/host-repoint-reconciliation.md`
-— what should happen when the shipper is repointed at a new, empty host (house identity,
-local binding state, and a refuse-then-`init-here` gate so transcripts never land on the
-wrong server).
-
-In constellation terms (`TERMINOLOGY.md`) memhouse is an **agency**: a **house**
-— the `mem` database — plus a **resident** working in it, the shipper. The house
-alone would hold; the shipper is what makes it act. It competes with
-memory-house; if it wins, it becomes memory-house v4.
-
-## What's supported
-
-| Surface | Status |
-|---|---|
-| macOS | primary — developed and driven here daily |
-| Linux | real — installs, ships, `service install` (systemd `--user`), rootless podman `deploy --local`; exercised on Debian and Ubuntu machines |
-| Windows | **untested** — the adapters declare Windows paths but no one has run a single install; treat it as unknown until this row changes |
-| ClickHouse | 25.11 and 26.x, both in CI; 26.2+ needs no flags, 25.x needs the text-index flag the shipper already passes |
-| Node | **≥ 24** — SQLite comes from `node:sqlite`, which is stable in 24. It works flagless on 22.13+ but prints `ExperimentalWarning` on every command (measured on v22.23.2), and Node 20 is past EOL. There is no native dependency and no build step at any version. |
+See [`AGENTS.md`](AGENTS.md) before your first change. Deeper reading:
+`memhouse/DESIGN.md` (the design and why), `memhouse/house/HOUSE.md` (layout and schema),
+`SECURITY.md` (what holds, and what does not).
 
-## Heritage & license
+## Heritage and license
 
-Built on [agentlytics](https://github.com/f/agentlytics) by Fatih Kadir Akın (MIT)
-— the adapters, dashboard, and cost engine come from there, and this repo's history
-carries the full lineage. MIT.
+Built on [agentlytics](https://github.com/f/agentlytics) by Fatih Kadir Akın (MIT). The
+adapters, dashboard and cost engine come from there, and this repository's history carries
+the full lineage. MIT.

package/SECURITY.md

@@ -0,0 +1,68 @@
+# Security model — stated plainly
+
+memhouse ships your coding-agent transcripts to a ClickHouse **you choose** — a container
+on your laptop, a box you run, your company's cluster, or ClickHouse Cloud. memhouse runs
+no service of its own: no memhouse cloud to sign up for, no telemetry, no phone-home. The
+credential is yours and the data is in your account, wherever you decided that is. That
+makes the security model short, and worth stating without varnish.
+
+## What holds
+
+- **A member reaches their own rooms and nothing else.** One grant, on `mem.<name>_*`:
+  their rooms, present and future. Ungranted rooms are not merely unreadable but absent
+  from `SHOW TABLES`, and a member cannot create, drop or re-grant outside their pattern
+  (measured on 25.11 and 26.7). Reserved databases (`system`, `information_schema`) are
+  refused as house names everywhere.
+- **Nobody is granted the database.** `ALL ON db.*` is dynamic — it covers rooms created
+  later — and a member holding it beside others could read *and* re-grant every
+  housemate's transcripts, needing no admin and notifying nobody. memhouse never issues
+  it: not to a member, not to the operator's own member account. The operator's reach is
+  the admin credential, kept separately.
+- **A member can only share what is theirs.** Grant option is scoped to their own rooms,
+  so `memhouse share` needs no operator and cannot reach a housemate's rows. A scoped
+  share (`--only`) builds its row filters BEFORE granting anything, so a scoping failure
+  grants nothing rather than leaving the grantee with everything.
+- **Attribution cannot be faked by a client.** `user_id` is `MATERIALIZED
+  currentUser()` — computed by the server during the insert — and `async_insert = 0
+  CONST` is pinned on every member so the stamp cannot be skipped (an async flush
+  stores it empty; measured on 25.11).
+- **The dashboard binds loopback** (`127.0.0.1`) by default, and `deploy --local`
+  binds the ClickHouse container to loopback too.
+- **Credentials are never printed.** The skills are under standing instruction not to
+  echo the env file, and the API's responses and error bodies were checked for
+  credential leakage under the acceptance suite.
+- **The tarball is audited in CI** for env files, credentials and host identities.
+
+## What you must know
+
+- **The dashboard has no authentication.** Loopback-only is the protection. If you
+  expose `MEMHOUSE_HOST=0.0.0.0`, anyone who can reach the port can read every
+  transcript in the house and run read-only SQL. Do not expose it; put a reverse proxy
+  with auth in front if you must.
+- **`/api/query` is read-only by enforcement, within limits.** Writes and table
+  functions (`url()`, `file()`, …) are refused server-side per request; resource use is
+  capped per query. It is still full SQL over your own house — treat dashboard access
+  as house access.
+- **The env file holds the house credential** (`~/.memhouse/env`, mode-restricted).
+  `service install` inlines the same credential into the systemd/launchd unit, and says
+  so. `uninstall` keeps it by default; `--credentials` or `--full-removal` remove it.
+- **Transcripts are shipped as-is.** memhouse does not redact. Whatever your editors
+  wrote to disk — including any secret an agent echoed into a session — is what lands
+  in the house. The house is as sensitive as your shell history; place it accordingly.
+- **Isolation is grants, and grants are checkable.** A housemate can run `SHOW GRANTS`
+  and see exactly what they hold; memhouse does not ask anyone to trust a row policy they
+  cannot inspect. What it does NOT defend against is the operator: whoever administers
+  the ClickHouse can read every room by definition, and no arrangement inside the server
+  changes that. If you should not be readable by the person running the server, you need
+  a different server, not a different layout.
+- **Members can enumerate each other** on a shared server: a table you may not read
+  errors differently (`Code: 497`) from one that does not exist (`Code: 60`). ClickHouse
+  behaviour, verified independent of memhouse's grants. It leaks names, never content —
+  and in a shared house the names are guessable anyway (`<member>_messages`), while
+  `SHOW USERS` is granted to members deliberately so `/mem:house` can list who to share
+  with. Treat membership as public and content as private.
+
+## Reporting
+
+The repository is private during beta. Report security issues to the maintainer
+directly (ramazanpolat@gmail.com) rather than in a public channel.