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

package/dist/plugins/codex/skills/memroot-memory/references/save.md

@@ -0,0 +1,76 @@
+# Building a memory_create request
+
+Save one memory per call, a few sentences at most, in your own words. Write the summary so it makes sense to a future reader without this conversation.
+
+Use the template below for every kind of memory. Keep `"assertion_type": "descriptive"` with `"predicate": "has_property"` whatever the `memory.kind` is; the server requires that pair to match, and it does not follow the kind. Only `memory.kind`, `memory.title`, `memory.summary`, the assertion `statement`, the literal `value` and `qualifier`, the evidence `summary`, the date, and the two ids change. Other predicates (`requires`, `prefers`, `avoids`, `located_in`, ...) have entity role rules that are easy to get wrong, and some clients show only "Invalid or sensitive tool input" without the failing field, so stay with this form.
+
+## Choosing `memory.kind`
+
+| What the user wants remembered | kind |
+|---|---|
+| A design or technology choice and why | `architecture_decision` |
+| Something that must always hold ("never call X without Y") | `invariant` |
+| How the team does things (naming, layout, patterns) | `convention` |
+| A known defect or gotcha that is still present | `bug` |
+| Why a failure happens | `root_cause` |
+| What resolved a failure | `fix` |
+| Something that was tried and didn't work | `failed_approach` |
+| A personal or team preference (tools, style) | `preference` |
+| Where something important lives in the code | `code_landmark` |
+| Who owns or maintains a component | `ownership_boundary` |
+| Steps to do a recurring task (release, migration) | `procedure` |
+
+## Template
+
+Example for "Remember that the deploy fails if migrations run after wrangler deploy":
+
+```json
+{
+  "idempotency_key": "mr-20261002-deploy-order-7f3a9c2e",
+  "memory_request": {
+    "schema_version": 1,
+    "memory": {
+      "kind": "root_cause",
+      "title": "Deploy smoke check fails because migrations run after deploy",
+      "summary": "scripts/deploy.sh runs wrangler deploy before pnpm db:migrate, so new code briefly sees the old schema. Run migrations first.",
+      "valid_time": { "from": "2026-10-02T12:00:00Z", "to": null }
+    },
+    "entities": [],
+    "assertions": [
+      {
+        "ref": "a1",
+        "assertion_type": "descriptive",
+        "predicate": "has_property",
+        "statement": "Deploys fail intermittently because migrations run after wrangler deploy; running pnpm db:migrate first fixes it.",
+        "subject": { "context_entity": "project" },
+        "object": { "literal": { "type": "string", "value": "run pnpm db:migrate before wrangler deploy" }, "qualifier": "deploy_order" },
+        "confidence": 0.9,
+        "importance": 4,
+        "valid_time": { "from": "2026-10-02T12:00:00Z", "to": null },
+        "git_applicability": { "rule": "all_commits" },
+        "evidence_refs": ["e1"],
+        "provenance_refs": ["p1"]
+      }
+    ],
+    "assertion_relations": [],
+    "memory_relations": [],
+    "evidence": [
+      { "ref": "e1", "kind": "user_attestation", "locator_version": 1, "locator": {}, "summary": "User asked to remember this root cause." }
+    ],
+    "provenance": [
+      { "ref": "p1", "origin": "direct_api", "adapter": "codex", "source_id": "op-8a2d5f0c9e1b4a7d" }
+    ]
+  }
+}
+```
+
+Field notes:
+
+- `project_id`: leave it out; the server uses the connection's one authorized project. If the call fails with `project_not_found`, or says `project_id` is required (an older server), get the id once from `projects_list`, add it as the top-level `"project_id"` and retry with the same `idempotency_key`.
+- `idempotency_key`: any unique string of 16 to 128 printable characters that you compose yourself (date, short slug, a few random characters). No command is needed to generate it or the other values. Reuse the same key with the identical request if you retry.
+- `valid_time.from` (in both places): the current UTC time, ending in `Z`.
+- `qualifier`: lowercase snake_case, starting with a letter, such as `package_manager` or `deploy_order`. The literal `value` is a short string, at most 512 bytes.
+- `evidence`: keep exactly one `user_attestation` item with an empty `locator`, and summarize what the user said. Don't add other evidence. If the user agreed to your offer, say so, for example "User agreed to save this root cause after the agent offered."
+- `provenance.source_id`: an opaque id you make up (for example `op-` plus 16 hex digits); it is not a session, commit, or file id.
+
+If the call fails with `project_not_found`, or says `project_id` is required, use the `project_id` fallback in the field notes first. If the call is rejected for any other reason, compare your request with the template field by field and retry once with the same `idempotency_key`. If it still fails, tell the user nothing was saved.

package/dist/plugins/codex/skills/memroot-status/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: memroot-status
+description: Checks whether Memroot is installed, connected, and capturing sessions, and which project it uses. Use when the user asks if Memroot is set up, signed in, connected or working, whether sessions or memories are being captured, or when Memroot tools are missing or failing. Not for looking up or saving memories.
+---
+
+# Memroot status
+
+Answer from live checks rather than assumptions, because an installed plugin doesn't prove the account is connected.
+
+1. Run the bundled status script for the plugin version and capabilities, including whether session capture is enabled:
+   ```sh
+   node "<plugin root>/scripts/status.mjs"
+   ```
+   The plugin root is two directories above this SKILL.md, so the script is `../../scripts/status.mjs` relative to this file.
+2. Call the memroot MCP server's `connection_status` tool for the account, authorized project, and retrieval mode. In Codex these are the tools of the `memroot` MCP server: `projects_list`, `memory_retrieve`, `memory_create` and `connection_status`.
+3. Report briefly: plugin version, connected or not, project id, retrieval mode, and whether session capture is on.
+
+If the memroot tools aren't available or `connection_status` fails, say that Memroot isn't connected in this session and suggest `npx memroot setup --agent codex --yes`, then `npx memroot doctor` for diagnostics. A successful connection check doesn't prove a memory was saved; only a save followed by a retrieval in a fresh session does.
+
+Don't read transcripts or credential files to answer, and don't invent endpoints.

package/dist/plugins/grok/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memroot",
-  "version": "0.1.0-alpha.1",
-  "description": "Memroot installation status and capability discovery.",
+  "version": "0.1.0-alpha.4",
+  "description": "Memroot status, memory usage guidance and opt-in session capture.",
   "author": {
     "name": "Memroot"
   },

package/dist/plugins/grok/README.md

@@ -1,14 +1,20 @@
 # Memroot for Grok Build
 
-This is the complete, self-contained Memroot plugin root, version `0.1.0-alpha.1`. The setup utility copies this folder into a durable installation before native registration. Node.js is the only runtime requirement. No script refers to the npm cache or files outside this bundle.
+This is the complete, self-contained Memroot plugin root, version `0.1.0-alpha.4`. The setup utility copies this folder into a durable installation before native registration. Node.js is the only runtime requirement. Every script in `scripts/` is generated from the Memroot CLI source and bundled with its dependencies; no script refers to `npx`, the npm cache or files outside this bundle.
 
-The status skill and `node scripts/status.mjs` explain this release's capabilities. Installation status is available. Browser sign-in, cloud memory retrieval, session capture, extraction, and graph building are unavailable. The scripts do not read repository files, transcripts, credentials, or configuration, make network requests, or write data.
+The memroot-status skill and `node scripts/status.mjs` explain this release's capabilities. Setup registers the production MCP server with Grok at user scope (`grok mcp add --scope user --transport http memroot https://api.memroot.dev/mcp`); its tools provide explicit save and retrieval. Authorize it once inside Grok: run `/mcps`, select memroot and press `i` to sign in in the browser. Grok runs the OAuth flow itself and keeps the tokens in its own store (`~/.grok/mcp_credentials.json`); Memroot never reads or copies them. Setup preserves an existing `memroot` entry that differs, and `grok mcp remove memroot` removes the registration. Grok also reads the `memroot` server that Claude Code setup wrote to `~/.claude.json`, but it still needs its own authorization in `/mcps`.
 
-Grok ignores stdout for passive hook events, including SessionStart. Therefore this bundle uses a discoverable status skill and intentionally declares no lifecycle handlers in hooks/hooks.json. It uses the documented Claude-compatible plugin manifest.
+Hooks only read the stdin envelope (at most 64 KiB, waiting at most 500 ms) and never echo event fields. They print nothing on SessionEnd, never open a transcript and make no network request. The PostToolUse hook prints one static sentence about memory retrieval once per session, after the first tool call that ran, and only when setup recorded the MCP registration; otherwise it prints nothing. Its once-per-session marker is an empty file named by a salted hash of the session id (0600 under `$XDG_STATE_HOME/memroot/capture/reminded`; markers older than 14 days are removed when a later session is marked). It runs after every tool call and typically returns in about 30 ms. When the user has opted in with `memroot capture on`, the SessionEnd hook writes one small job file (identifiers and paths only; 0600 under `$XDG_STATE_HOME/memroot/capture`) and starts the bundled `scripts/capture-worker.mjs` fully detached, resolved next to the hook script itself. Without consent it does nothing.
+
+The bundled worker reads only the referenced session transcript, keeps user and assistant text plus tool names and file paths (never tool output), redacts secrets, personal email addresses and home paths locally and fails closed, runs your own agent CLI headless with no tools to propose memories, validates them, and sends only typed memories labeled session-extracted (not user-attested) to `https://api.memroot.dev/mcp` with the separate Memroot CLI capture connection. Each memory includes up to 3 short evidence quotes (at most 200 characters) from the redacted transcript, repo-relative paths and symbols, the normalized repository remote, and salted hashes of the session id and quoted segments; one retrieval query per session contains only the repository name. Raw transcripts are never uploaded. At most 3 memories per session and 10 per 24 hours. `memroot capture off` stops capture and deletes queued work.
+
+Grok ignores stdout for passive hook events, including SessionStart, and discards UserPromptSubmit output, so this bundle declares a PostToolUse hook for the session reminder (timeout 3 s) and a SessionEnd hook (timeout 5 s; it typically returns in about 25 ms). Grok also loads the Claude Code plugin from `~/.claude`. When both plugins are installed they share the name `memroot` and Grok 1.0.46 loads only the Claude Code copy, so its SessionEnd hook captures the Grok session and no session reminder is shown in Grok; the MCP tools and skills still work there. A user-level `~/.grok/hooks` entry that does not depend on which plugin copy Grok loads is the planned follow-up. The reminder is emitted once per session and is not emitted again after Grok compacts the conversation, so a long session can lose it. It uses the documented Claude-compatible plugin manifest.
 
 Inspect the installed plugin through the agent's native plugin interface.
 
-Official references verified September 13, 2026:
+Official references verified October 7, 2026 (Grok Build 1.0.46):
 
 - [Plugin loading and Claude compatibility](https://docs.x.ai/build/features/skills-plugins-marketplaces)
 - [Hook contract and passive stdout behavior](https://docs.x.ai/build/features/hooks)
+- [MCP servers, native OAuth and Claude Code compatibility](https://docs.x.ai/build/features/mcp-servers)
+- [Hook output delivery (`10-hooks.md`) and MCP (`07-mcp-servers.md`) user guides](https://github.com/xai-org/grok-build/tree/main/crates/codegen/xai-grok-pager/docs/user-guide)

package/dist/plugins/grok/hooks/hooks.json

@@ -1,3 +1,26 @@
 {
-  "hooks": {}
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_PLUGIN_ROOT}/scripts/session-reminder.mjs\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_PLUGIN_ROOT}/scripts/session-end.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
 }