memroot 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/plugins/claude/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": "claude_code", "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/claude/skills/memroot-status/SKILL.md

@@ -0,0 +1,19 @@
+---
+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 "${CLAUDE_PLUGIN_ROOT}/scripts/status.mjs"
+   ```
+2. Call the memroot MCP server's `connection_status` tool for the account, authorized project, and retrieval mode. In Claude Code the memroot tools are `mcp__memroot__projects_list`, `mcp__memroot__memory_retrieve`, `mcp__memroot__memory_create` and `mcp__memroot__connection_status`; if they are deferred, load them with tool search first.
+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 claude --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/codex/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memroot",
-  "version": "0.1.0-alpha.1",
-  "description": "Connect Memroot and explicitly save or retrieve engineering knowledge.",
+  "version": "0.1.0-alpha.3",
+  "description": "Connect Memroot, explicitly save or retrieve engineering knowledge, and optionally capture it after sessions end.",
   "author": {
     "name": "Memroot"
   },
@@ -9,10 +9,10 @@
   "interface": {
     "displayName": "Memroot",
     "shortDescription": "Connect Memroot and manage durable engineering knowledge.",
-    "longDescription": "Setup links native Codex MCP OAuth to Memroot. After authorization, explicitly save user-approved knowledge and retrieve structured memory packs. Verify the connection with connection_status and persistence with a fresh-session retrieval. Automatic session capture and extraction are unavailable.",
+    "longDescription": "Setup links native Codex MCP OAuth to Memroot. After authorization, explicitly save user-approved knowledge and retrieve structured memory packs. Optional session capture (memroot capture on) runs a bundled background worker after a session ends: it redacts the transcript locally, runs Codex without tools to extract candidates, and uploads only typed memories labeled session-extracted. Trust the Memroot SessionStart and SessionEnd hooks once in /hooks.",
     "developerName": "Memroot",
     "category": "Productivity",
-    "capabilities": ["Read"],
+    "capabilities": ["Read", "Write"],
     "defaultPrompt": ["Check my Memroot plugin status."]
   }
 }

package/dist/plugins/codex/README.md

@@ -1,18 +1,22 @@
 # Memroot for Codex
 
-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.3`. 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. Setup registers the production remote MCP server with Codex and opens native OAuth sign-in when needed. The MCP tools provide explicit save and retrieval after authorization. Static scripts cannot verify account connectivity. Automatic session capture and extraction 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 remote MCP server with Codex and opens native OAuth sign-in when needed. The MCP tools provide explicit save and retrieval after authorization.
 
-The SessionStart hook supplies a short, static capability notice. It accepts at most 64 KiB of event JSON and waits at most 500 ms for stdin. Malformed inputs and unrelated events exit quietly. It never includes event fields in output. There is no Stop or SessionEnd handler because this release cannot capture or upload sessions.
+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. 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.
 
-After installation, review and trust the hook through `/hooks` in Codex. Plugin installation does not establish hook trust. Changed hook definitions require review again.
+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.
 
-Official references verified September 13, 2026:
+The SessionStart hook supplies a short static context about memory retrieval (timeout 3 s). The SessionEnd hook has Codex's maximum 3 s timeout and typically returns in about 25 ms.
 
-- [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins)
-- [OpenAI hook contracts and trust](https://learn.chatgpt.com/docs/hooks)
+After installation, review and trust both hooks through `/hooks` in Codex. Plugin installation does not establish hook trust, and Codex skips untrusted hooks. Trust is pinned per hook definition; `hooks/hooks.json` is kept byte-stable across releases (the SessionStart entry is unchanged from `0.1.0-alpha.1`) so upgrades do not require re-trusting. The compatibility manifest relies on default `hooks/hooks.json` discovery; hook commands use `PLUGIN_ROOT`.
+
+Setup owns the single user-scope `memroot` MCP registration; this plugin intentionally declares no second MCP server.
 
-The compatibility manifest intentionally relies on default `hooks/hooks.json` discovery. Hook commands use `PLUGIN_ROOT`; Codex also provides Claude-compatible plugin variables.
+Inspect the installed plugin through the agent's native plugin interface.
 
-Setup owns the single user-scope `memroot` MCP registration; this plugin intentionally declares no second MCP server. Repeated setup reuses authorized native credentials. Check `connection_status` and complete a save/retrieve round trip before claiming memory works.
+Official references verified October 2, 2026:
+
+- [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins)
+- [OpenAI hook contracts and trust](https://learn.chatgpt.com/docs/hooks)

package/dist/plugins/codex/hooks/hooks.json

@@ -11,6 +11,17 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/session-end.mjs\"",
+            "timeout": 3
+          }
+        ]
+      }
     ]
   }
 }