memroot 0.1.0-alpha.1 → 0.1.0-alpha.4

package/README.md

@@ -8,7 +8,7 @@ npx memroot setup
 
 Requires Node.js 22 or later on macOS or Linux and an installed agent CLI with native plugin support. The interactive setup detects agent CLIs, lets you select agents, and previews the user-scope installation. Cancel before confirming to leave your files unchanged.
 
-**This is an alpha.** Selecting Codex installs its native plugin and configures `https://api.memroot.dev/mcp` using Codex’s native OAuth sign-in. Follow the browser consent screen to link your production account. No separate `memroot login` is needed for Codex MCP. Repeating setup reuses existing authorization; cancelled sign-in can be resumed by repeating setup. Automatic session capture and extraction are unavailable.
+**This is an alpha.** Selecting Codex installs its native plugin and configures `https://api.memroot.dev/mcp` using Codex’s native OAuth sign-in. Follow the browser consent screen to link your production account. No separate `memroot login` is needed for Codex MCP. Repeating setup reuses existing authorization; cancelled sign-in can be resumed by repeating setup. Automatic session capture is opt-in; see [Session capture](#session-capture-opt-in).
 
 For scripts:
 
@@ -20,6 +20,9 @@ npx memroot doctor
 npx memroot login        # browser sign-in; --no-browser prints the URL
 npx memroot status       # cloud auth + agent install state
 npx memroot token        # fresh access token for agent adapters
+npx memroot capture on   # opt in to session-end memory capture
+npx memroot capture status
+npx memroot capture off
 npx memroot logout
 ```
 
@@ -27,7 +30,7 @@ The refresh token is stored only in the OS credential store (macOS Keychain via
 
 Agent values are `claude`, `codex`, and `grok`. `--agent` can be repeated. `--yes` requires explicit agents. `--dry-run` prints planned commands without running an agent CLI or writing files.
 
-Plugin files live under `$XDG_DATA_HOME/memroot`, defaulting to `~/.local/share/memroot`, independently of the npm cache. Setup delegates registration and installation to each agent's native plugin manager and keeps a separate success receipt for each agent. It preserves unrelated config and refuses conflicting marketplaces, modified managed files, and disabled installed plugins. Repeating setup verifies files and repairs a missing native installation. Native enablement and hook execution trust stay under the agent's control. Grok setup uses its native `--trust` flag to authorize the selected local Memroot plugin; this alpha has no Grok lifecycle hooks.
+Plugin files live under `$XDG_DATA_HOME/memroot`, defaulting to `~/.local/share/memroot`, independently of the npm cache. Setup delegates registration and installation to each agent's native plugin manager and keeps a separate success receipt for each agent. It preserves unrelated config and refuses conflicting marketplaces, modified managed files, and disabled installed plugins. Repeating setup verifies files and repairs a missing native installation. Native enablement and hook execution trust stay under the agent's control. Grok setup uses its native `--trust` flag to authorize the selected local Memroot plugin; its hooks are PostToolUse (a one-time session reminder) and SessionEnd. It also registers `https://api.memroot.dev/mcp` with `grok mcp add` at user scope; authorize it once inside Grok with `/mcps` (select memroot, press `i`). Grok runs the OAuth sign-in and keeps the credentials in its own store; Memroot setup never reads or copies them, and it preserves an existing `memroot` entry that differs. `grok mcp remove memroot` removes the registration.
 
 When upgrading Codex from a verified older Memroot release, setup replaces only its managed `memroot` marketplace through Codex's native remove/add commands, then installs the new plugin. The previous files and receipt remain available until installation succeeds; rerunning setup resumes an interrupted upgrade. Native MCP authorization is independent and is reused when already configured and authorized.
 
@@ -44,6 +47,27 @@ codex mcp remove memroot
 
 `logout` deauthenticates the named MCP server; `remove` deletes its native configuration. Neither plugin removal nor local credential removal should be treated as proof that the production grant is revoked; verify its revoked state in the console. `memroot logout` removes the separate Memroot CLI credentials and does not disconnect Codex's independently stored MCP authorization. This release does not remove native config or managed files automatically. Windows installation is not supported in this alpha.
 
+## Session capture (opt-in)
+
+Session capture saves durable engineering knowledge (decisions, conventions, root causes, failed approaches, procedures) after a coding session ends. It is off until you enable it; installing the plugins is not consent.
+
+```sh
+npx memroot capture on [--agent claude --agent codex --agent grok] [--allow-cross-agent-extraction] [--yes] [--no-browser]
+npx memroot capture status
+npx memroot capture off
+```
+
+`capture on` prints the disclosure and asks for confirmation (`--yes` in scripts), then authorizes a separate **Memroot CLI** capture connection in the browser (an MCP grant for the `memroot-cli` client whose refresh token is stored in the OS credential store as `<api base>#mcp`), verifies it with `connection_status`, and records your choice in `~/.memroot/capture.json` (0600). Interactive `setup` offers the same step with default **No**; `setup --capture` and `setup --no-capture` script it, and setup without either flag leaves consent unchanged.
+
+What happens, all inside the installed plugin (no `npx`, no network from hooks):
+
+- **SessionEnd hook** (Claude Code and Codex alongside the existing SessionStart hook; Grok alongside its PostToolUse session reminder) reads only the small stdin envelope, writes a job file under `$XDG_STATE_HOME/memroot/capture` (default `~/.local/state/memroot/capture`, directories 0700, files 0600) and starts a detached background worker. It never opens the transcript and returns in about 25 ms.
+- **Worker** reads only the referenced session transcript, keeps user and assistant text plus tool names and file paths (never tool output), removes secrets, personal email addresses and home paths locally (fail closed), and runs **your own agent CLI headless with no tools** (`claude -p`, `codex exec --ephemeral`, or `grok` headless) on at most 48,000 characters to propose memories. This spends your agent subscription or API quota and sends the redacted excerpt to that agent's model provider. Another agent's CLI is used only with `--allow-cross-agent-extraction`.
+- **Upload**: candidates are validated locally (exact evidence quotes, injection filter, a second redaction pass, the shared contract). Only typed memories are sent to `https://api.memroot.dev/mcp`, labeled **session-extracted (not user-attested)** with confidence at most 0.7. Each memory carries repo-relative paths and symbols it mentions, up to 3 short evidence quotes (at most 200 characters each) from the redacted transcript, your repository identity (normalized git remote), a salted hash of the session id, salted hashes of the quoted segments, and the extractor name, prompt version and model. Before extracting, the worker sends one retrieval query containing only the repository name to avoid duplicates. Raw transcripts are never uploaded. At most 3 memories per session and 10 per rolling 24 hours; each is one write against your plan quota.
+- **Stopping**: `memroot capture off` disables capture and deletes queued work (an in-progress run stops before uploading); revoking "Memroot CLI" in [Memroot Console](https://console.memroot.dev) or `memroot logout` stops uploads.
+
+Codex skips plugin hooks until you trust them: open `/hooks` in Codex and trust the Memroot SessionStart and SessionEnd hooks. `memroot capture status` reports the trust state, Claude Code's `disableAllHooks`, queued jobs, the last worker run and which agent CLIs are on PATH. Logs contain only hashes, counts, durations and error codes.
+
 [Memroot](https://memroot.dev)
 
 Codex setup reports plugin installation, MCP configuration and OAuth authorization separately. It always reports memory verification as not verified: only a successful tool round trip can prove persistence. Restart Codex, ask it to call Memroot `connection_status`, then explicitly ask it to save a small test memory. Open a fresh Codex session and ask it to retrieve that memory. Inspect the connection and memory in [Memroot Console](https://console.memroot.dev).