memhouse 0.7.1 → 0.9.0

package/README.md

@@ -1,19 +1,31 @@
 # memhouse
 
-Long-term memory for coding agents. memhouse 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
-ClickHouse. Nothing is proxied or intercepted. Then you can search every past
-session, see what it cost, and let an agent query its own history.
+**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.
+
+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 own**. Nothing is proxied, intercepted, or sent to anyone's cloud. 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.
+
+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.
 
 ```bash
-npm install -g memhouse --allow-scripts=better-sqlite3
+npm install -g memhouse
 memhouse onboard
 ```
 
-That is the whole install. `onboard` finds your editors, sets up a house, ships,
-and starts the dashboard. **Don't drop `--allow-scripts`** — see
-[below](#the-allow-scripts-flag).
+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`.
@@ -22,7 +34,7 @@ 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 --allow-scripts=better-sqlite3
+sudo npm install -g memhouse
 ```
 
 If the prefix is yours (Homebrew, fnm, nvm, volta), `sudo` is the wrong fix and
@@ -36,6 +48,13 @@ makes it worse — [EACCES on install](#eacces-on-install) tells them apart.
 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
@@ -142,13 +161,11 @@ memhouse update            # upgrade, restart the daemons, check the house schem
 memhouse update --check    # compare versions, change nothing
 ```
 
-A bare `npm i -g memhouse@latest` does one third of the job. It does not re-pass
-`--allow-scripts=better-sqlite3`, so the five SQLite adapters go quiet; 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 all three, and from a
-checkout it rebuilds `public/` — otherwise `git pull` serves you the previous release's
-dashboard forever.
+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
@@ -157,19 +174,30 @@ immediate.
 
 ## How your memory is stored
 
-**One house, one set of rooms per member.** You own `sessions_<you>`,
-`messages_<you>`, `tool_calls_<you>` in the `mem` database, and hold grants on
-those and nothing else. Isolation is a grant that is simply *absent*, so it fails
-closed — no row policy that has to be right on every table and every read path.
+**A house is a database; its rooms are three shared tables.** `sessions`, `messages`
+and `tool_calls` live in whatever database you point at — your own name by default
+(`polat.messages`), a team's (`team_a.messages`), even `default`. Everyone in the
+house writes into the same tables with their own credential, and 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. No filter
+is the whole house — which is exactly what a team dashboard wants.
 
-All of *your* machines ship into *your* rooms; the `host` column tells them apart.
-Another member's machines never do. A team-wide read is a `Merge` room
-(`all_sessions`) plus a `GRANT`, which narrows to whatever the caller can already
-see. Sharing a whole room needs no operator.
+Sharing is not a feature bolted on top; it IS the house. A team makes a database,
+grants each person `ALL` on it, and their shippers all write into the same rooms:
 
-The member name comes from the server — `SELECT currentUser()` — not from your
-config. A client that could name its own member could write into someone else's
-rooms.
+```sql
+CREATE DATABASE team_a;
+CREATE USER alice IDENTIFIED BY '…';
+GRANT ALL ON team_a.* TO alice;    -- repeat per housemate
+```
+
+`ALL` on your own house reaches nothing outside it — the database is the boundary,
+which is also why joining a ClickHouse someone else runs (a kernel's, a team's) needs
+no negotiation beyond a database and a credential. Housemates are collaborators;
+groups that should not see each other get separate houses.
 
 ### Imported history is protected
 
@@ -192,24 +220,22 @@ has it wrong, so an old house cannot be corrupted by a new shipper.
 
 ## Troubleshooting
 
-### The `--allow-scripts` flag
-
-Five adapters — **cursor, zed, opencode, goose, antigravity** — read sessions out
-of SQLite files, and `better-sqlite3` builds its native binding from an install
-script. npm 12 blocks install scripts by default, so without the flag those five
-read nothing and you ship a partial history.
+### An editor reads zero sessions
 
-(This said six and named windsurf, which is wrong: windsurf lists its sessions over
-language-server RPC and touches SQLite only to read a usage key, so a dead binding
-costs it numbers, not sessions. `editors/index.js` has the real list.)
+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.
 
-It is not silent: `memhouse discover` and `memhouse doctor` both name the skipped
-adapters. The other twelve adapters keep working.
-
-`npx` takes the same flag, before the package name:
+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 --allow-scripts=better-sqlite3 -y memhouse discover
+npx -y memhouse discover      # no flags here either
 ```
 
 ### `EACCES` on install
@@ -244,7 +270,7 @@ A rootless podman house has the same problem for the same reason, and
 ## Working from a checkout
 
 ```bash
-npm install            # the repo's allowScripts field covers the binding
+npm install            # two runtime deps, no build step
 node bin/memhouse.js …
 npm test               # syntax gate + unit checks
 ```
@@ -275,6 +301,16 @@ In constellation terms (`TERMINOLOGY.md`) memhouse is an **agency**: a **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. |
+
 ## Heritage & license
 
 Built on [agentlytics](https://github.com/f/agentlytics) by Fatih Kadir Akın (MIT)