memroot 0.1.0-alpha.0 → 0.1.0-alpha.3

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 installer alpha.** The plugins provide integration status and static startup guidance. Cloud sign-in, memory retrieval, session capture, and extraction are not available in this release. Installing a plugin does not connect cloud memory. No credentials or transcripts are collected or uploaded.
+**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:
 
@@ -17,16 +17,63 @@ npx memroot setup --agent codex --yes
 npx memroot setup --agent claude --agent grok --yes
 npx memroot setup --agent codex --yes --dry-run
 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
 ```
 
+The refresh token is stored only in the OS credential store (macOS Keychain via `security`, libsecret via `secret-tool` on Linux); sign-in fails closed when neither is available. Non-secret settings live in `~/.memroot/config.json`. `MEMROOT_API_BASE` or `--api-base` override the default `https://api.memroot.dev`; `--env dev` targets a local API stub on `localhost:8787`.
+
 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.
 
 `doctor` checks managed file integrity and native plugin presence. Restart your coding agent after setup. Use the installed Memroot status skill to inspect release capabilities.
 
 If an agent command fails, update that agent and inspect its `plugin --help`. Native plugin managers may partially register a marketplace before installation fails; setup writes no success receipt for that attempt. Retry after resolving the native error. Installation is serialized by a lock; after an interrupted process, verify no setup is running before removing the `.setup-lock` directory named by the error.
 
-To remove the integration, use the agent's native plugin manager. This release deliberately does not remove native config or managed files automatically. Windows installation is not supported in this alpha.
+To remove the plugin, use the agent's native plugin manager. Codex's `memroot` MCP registration is separate: uninstalling the plugin leaves that server and its account access in place. To disconnect production access, revoke the corresponding Codex connection in [Memroot Console](https://console.memroot.dev), then deauthenticate and remove the native MCP registration:
+
+```sh
+codex mcp logout memroot
+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).
+
+Codex owns its MCP credentials; Memroot setup never reads or copies them. Setup preserves conflicting endpoints, disabled servers, unrelated MCP entries, and unknown auth states. A failed inspection does not trigger replacement authorization. Use Codex's native MCP management to resolve a conflict. `memroot status` and `doctor` inspect current native MCP status without requesting new grants.
+
+Legacy non-secret prototype config is backed up once to `~/.memroot/config.json.legacy-backup` with owner-only permissions before an atomic reset to the current schema. Old user IDs and email addresses are not proof of identity and are never imported as authenticated accounts. Credentials and unsafe remote URLs cause migration to stop with the original intact. Unknown non-secret fields remain in the protected backup. Separate CLI sign-in retains its OS credential-store behavior described above.
+
+Codex command support rechecked 2026-09-26 against [official MCP documentation](https://developers.openai.com/codex/mcp) and installed Codex 0.157.1. A deployment supporting these tools is required; setup alone does not verify deployment health.