memhouse 0.8.0 → 0.11.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
@@ -64,7 +76,7 @@ memhouse update [--check]                  upgrade, restart daemons, check the s
 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 plugins install claude            /memhouse:search, :sessions, :sql —
+memhouse plugins install claude            /mem:search, :sessions, :sql —
                                            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
@@ -77,7 +89,7 @@ an agent — so an agent can install its own memory unattended.
 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 `/memhouse:search` ends up missing from
+Installing into just the default config is how `/mem:search` ends up missing from
 the instance you actually work in, silently, since a missing skill never announces
 itself.
 
@@ -149,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
@@ -189,45 +199,62 @@ which is also why joining a ClickHouse someone else runs (a kernel's, a team's)
 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
+### The house never destroys what it cannot rebuild
 
-Rows carry an `origin`. The shipper clears a session before re-inserting it, so a
-shorter re-parse can't leave a stale tail behind — but that clear only removes rows
-the shipper itself wrote (`origin='ship'`). Anything you imported from an older
-house, another product, or a machine that no longer exists survives a re-ship.
+**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.
 
-`origin` is in the sorting key of `messages` and `tool_calls` too, so
-ReplacingMergeTree can't quietly collapse an imported row against a shipped one. Both
-halves matter: guarding only the delete still loses data, through the merge instead of
-the mutation.
+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.
 
-`sessions` is the deliberate exception — one row per session, no `origin` in its key.
-A session's metadata has a single current version, and keying it on origin gives the
-same session two rows, which makes every rollup count its messages twice.
+So rows carry an `epoch`: which parse of the session they belong to.
 
-The shipper checks both directions before it writes and prints the rebuild if a house
-has it wrong, so an old house cannot be corrupted by a new shipper.
+- **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.
 
-## Troubleshooting
+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 `--allow-scripts` flag
+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 `house_events`, and `memhouse doctor` reads it back.
 
-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.
+## Troubleshooting
 
-(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.)
+### An editor reads zero sessions
 
-It is not silent: `memhouse discover` and `memhouse doctor` both name the skipped
-adapters. The other twelve adapters keep working.
+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.
 
-`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
@@ -262,7 +289,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
 ```
@@ -293,6 +320,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)