mnemos-capture 1.6.0 → 1.7.0

package/README.md

@@ -1,17 +1,14 @@
 <div align="center">
   <br>
   <a href="https://xkg.xmu.sh">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="public/xkg-hero-dark.gif">
-      <img src="public/xkg-hero-light.gif" width="160" height="160" alt="xkg">
-    </picture>
+    <img src="public/brand/xkg-icon-dark.png" width="160" height="160" alt="xkg">
   </a>
   <br>
   <br>
   <p>
-    <a href="https://www.npmjs.com/package/mnemos-capture"><img src="https://img.shields.io/npm/v/mnemos-capture?color=1c74d8&labelColor=000820&style=flat" alt="npm" /></a>
-    <img src="https://img.shields.io/badge/MCP-compatible-9dd8f5?labelColor=000820&style=flat" alt="MCP" />
-    <img src="https://img.shields.io/badge/license-MIT-f0f4f8?labelColor=000820&style=flat" alt="MIT" />
+    <a href="https://www.npmjs.com/package/@xmu-labs/xkg"><img src="https://img.shields.io/npm/v/@xmu-labs/xkg?color=777493&labelColor=11131A&style=flat" alt="npm" /></a>
+    <img src="https://img.shields.io/badge/MCP-compatible-B8B5D0?labelColor=11131A&style=flat" alt="MCP" />
+    <img src="https://img.shields.io/badge/license-MIT-F2F1F6?labelColor=11131A&style=flat" alt="MIT" />
   </p>
 </div>
 
@@ -53,7 +50,7 @@ You find useful stuff, you capture through the web app, then xkg connects it int
 xkg will continuously compound that knowledge over time — keeping AI workers' context up to date as human knowledge evolves.
 
 > [!IMPORTANT]
-> We are migrating from **mnemos** / **Xmu** to **xkg**. The app now lives at [xkg.xmu.sh](https://xkg.xmu.sh) and the code at [xmu-labs/xkg](https://github.com/xmu-labs/xkg). Connectors set up with `mnemos-capture.vercel.app` keep working. The npm package still says `mnemos-capture`. Sorry for the inconvenience.
+> We are migrating from **mnemos** / **Xmu** to **xkg**. The app now lives at [xkg.xmu.sh](https://xkg.xmu.sh) and the code at [xmu-labs/xkg](https://github.com/xmu-labs/xkg). The npm package is now `@xmu-labs/xkg`. Connectors set up with `mnemos-capture.vercel.app` and commands that run `npx mnemos-capture@latest` keep working: every release is published under both names. Sorry for the inconvenience.
 
 ## Start here
 
@@ -95,7 +92,7 @@ https://xkg.xmu.sh/api/mcp
 ```
 
 ```bash
-npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
+npx -y @xmu-labs/xkg@latest serve-mcp --key YOUR_API_KEY
 ```
 
 The CLI binary is **`xkg`** (also `xmu` and `mnemos-capture`). An MCP server already registered as `xmu` or `mnemos`, or set up with `mnemos-capture@latest`, keeps working.
@@ -126,7 +123,7 @@ Name the connector `xkg`, paste `https://xkg.xmu.sh/api/mcp`, sign in with GitHu
 The same command works in every CLI — Cursor, Codex, Gemini CLI, VS Code, Claude Code, or anything that can launch a local MCP server:
 
 ```bash
-npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
+npx -y @xmu-labs/xkg@latest serve-mcp --key YOUR_API_KEY
 ```
 
 Register that command in the tool you use.
@@ -140,7 +137,7 @@ Add this to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (all projects):
   "mcpServers": {
     "xkg": {
       "command": "npx",
-      "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
+      "args": ["-y", "@xmu-labs/xkg@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
     }
   }
 }
@@ -157,7 +154,7 @@ Add this to `.vscode/mcp.json`:
   "servers": {
     "xkg": {
       "command": "npx",
-      "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
+      "args": ["-y", "@xmu-labs/xkg@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
     }
   }
 }
@@ -172,7 +169,7 @@ Codex CLI — add this to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.xkg]
 command = "npx"
-args = ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
+args = ["-y", "@xmu-labs/xkg@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
 ```
 
 Codex App: Settings → MCP → add the same `npx` command.
@@ -180,13 +177,13 @@ Codex App: Settings → MCP → add the same `npx` command.
 #### Gemini CLI
 
 ```bash
-gemini mcp add xkg npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
+gemini mcp add xkg npx -y @xmu-labs/xkg@latest serve-mcp --key YOUR_API_KEY
 ```
 
 #### Claude Code
 
 ```bash
-claude mcp add xkg -- npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
+claude mcp add xkg -- npx -y @xmu-labs/xkg@latest serve-mcp --key YOUR_API_KEY
 ```
 
 Or the URL, no API key:
@@ -198,7 +195,7 @@ claude mcp add --transport http xkg https://xkg.xmu.sh/api/mcp
 Optional session hooks (MCP works without them):
 
 ```bash
-npx -y mnemos-capture@latest setup-hooks --key YOUR_API_KEY --briefing --vault
+npx -y @xmu-labs/xkg@latest setup-hooks --key YOUR_API_KEY --briefing --vault
 ```
 
 Hooks are local files — they run in the CLI and editor extensions, not in the browser.
@@ -212,7 +209,7 @@ Settings → Developer → Edit Config. Add the same `npx` block to `claude_desk
   "mcpServers": {
     "xkg": {
       "command": "npx",
-      "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
+      "args": ["-y", "@xmu-labs/xkg@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
     }
   }
 }
@@ -227,7 +224,7 @@ If the tool can launch a local process, register the same `npx` command. If it h
   "mcpServers": {
     "xkg": {
       "command": "npx",
-      "args": ["-y", "mnemos-capture@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
+      "args": ["-y", "@xmu-labs/xkg@latest", "serve-mcp", "--key", "YOUR_API_KEY"]
     }
   }
 }
@@ -256,14 +253,14 @@ No MCP support yet? Capture in the [xkg app](https://xkg.xmu.sh) and connect lat
 4. **Execute** — Hand the plan to your worker in the current session, or run it in an isolated git worktree:
 
    ```bash
-   npx -y mnemos-capture@latest config set agent "claude -p"
-   npx -y mnemos-capture@latest kos --key YOUR_API_KEY
+   npx -y @xmu-labs/xkg@latest config set agent "claude -p"
+   npx -y @xmu-labs/xkg@latest kos --key YOUR_API_KEY
    ```
 
    `kos` creates a worktree, loads the plan as the contract, launches the assistant you configured, and prints the verification checklist when it finishes.
 
    ```bash
-   npx -y mnemos-capture@latest config set agent "codex exec"
+   npx -y @xmu-labs/xkg@latest config set agent "codex exec"
    ```
 
 ### Example capture
@@ -317,7 +314,8 @@ You don't have to memorize these. Ask in plain language: "save this", "what do I
 | `briefing` | Get project-specific recommendations |
 | `generate_plan` | Turn selected captures into an implementation plan |
 | `list_plans` | List or read saved plans |
-| `apply_capture` | Mark a capture as applied |
+| `apply_capture` | Mark a capture as applied, with the commit that applied it |
+| `apply_stats` | Captures applied per week, and how many came with a commit |
 | `archive_capture` | Archive a capture |
 | `delete_capture` | Delete a capture |
 | `apply_to_context` | Get file-level suggestions for the current task |
@@ -331,20 +329,23 @@ You don't have to memorize these. Ask in plain language: "save this", "what do I
 No global install required. The binary is **`xkg`** (also `xmu` and `mnemos-capture`). Via npx:
 
 ```bash
-npx -y mnemos-capture@latest <command>
+npx -y @xmu-labs/xkg@latest <command>
 ```
 
 | Command | What it does |
 | --- | --- |
-| `npx -y mnemos-capture@latest` | Open the hosted app |
+| `npx -y @xmu-labs/xkg@latest` | Open the hosted app |
 | `serve-mcp --key YOUR_API_KEY` | Run the local MCP proxy |
 | `setup-hooks --key YOUR_API_KEY [--briefing] [--vault]` | Install Claude Code hooks |
+| `setup-git-hook --key YOUR_API_KEY` | In a repo: record commits whose message has an `xkg-capture: <filename>` trailer (works with any coding agent). The key is stored in `~/.xkg/config.json`, not in the hook. Setup checks that the hook can reach xkg, and the hook runs the CLI version that installed it (run setup again to update) |
 | `config set agent "claude -p"` | Set which assistant `kos` should drive |
 | `kos --key YOUR_API_KEY` | Implement the latest plan in an isolated worktree |
 | `inbox-check --key YOUR_API_KEY [--briefing]` | Debug the session hook |
 | `vault-check --key YOUR_API_KEY` | Debug the vault hook |
 | `help` | Show help |
 
+What changed in each version: [GitHub Releases](https://github.com/xmu-labs/xkg/releases).
+
 ## Your context stays in GitHub
 
 Captures live as structured Markdown in **your** GitHub repository. Private by default.
@@ -372,6 +373,7 @@ The whole point of this repo being public is that you can check these claims rat
 | `pin_hash` | salted scrypt (`src/lib/pin.ts`) |
 | `api_key` | hashed — not recoverable |
 | `llm_provider`, `llm_api_key` | encrypted |
+| `display_name`, `avatar_data` | optional in-app name and photo; never written back to GitHub |
 | `token_version` | bumped to revoke everything |
 | login attempts, OAuth clients/codes, refresh-token ids | auth plumbing |
 
@@ -396,7 +398,11 @@ Your MCP key is shown exactly once. If you lose it, generate a new one.
 
 **PIN unlock is device-bound.** It only works on a device that has already signed in with GitHub. A PIN on its own is not enough to reach your account.
 
-**Revoking access.** Generating a new MCP key invalidates the old key, every signed-in session, and every connected MCP client. Sessions also expire after 30 days.
+**Revoking access.** Generating a new MCP key invalidates the old key, every other signed-in session, and every connected MCP client. Sessions also expire after 30 days.
+
+**Deleting your account.** Settings → Delete account removes your account row and every record keyed to it, and asks GitHub to revoke xkg's access (`src/lib/account.ts`). Your captures stay in your repo.
+
+The hosted service's [Privacy Policy](https://xkg.xmu.sh/privacy) and [Terms of Service](https://xkg.xmu.sh/terms) say the same in legal form.
 
 ## Cost
 
@@ -423,7 +429,13 @@ Working on the code? See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-[MIT License](./LICENSE)
+[MIT License](./LICENSE). Contributions are welcome under the same licence; see
+[CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+**Trademarks.** The MIT licence covers the code, not names or logos: the xkg name and logo are not
+licensed for use as your own brand. Claude, ChatGPT, Codex, Gemini, Grok, Cursor and VS Code are
+trademarks of their respective owners, named here only to say which tools xkg works with; no
+endorsement is implied.
 
 If you use xkg in published work:
 

package/dist/cli/git-hook.js

@@ -0,0 +1,91 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import { execFileSync } from "child_process";
+import { callMcp, initializeMcp } from "./hooks.js";
+import { getCurrentVersion } from "./version-check.js";
+/**
+ * Links commits to the captures they apply, with any coding agent or none.
+ * The commit message carries one `xkg-capture: <filename>` trailer per
+ * capture; a git post-commit hook reports each one to apply_capture with the
+ * commit sha. The server counts a capture and commit once, so an agent that
+ * also calls apply_capture itself does not double count.
+ */
+const PACKAGE = "@xmu-labs/xkg";
+const MARKER = "# xkg";
+/** The MCP client name the hook's reports carry, so the server counts them by agent. */
+export const HOOK_CLIENT = "xkg-git-hook";
+function git(cwd, ...args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+/** `xkg-capture` values from the commit message's trailer block only (as git parses it), once each. */
+export function captureTrailers(message) {
+    let trailers;
+    try {
+        trailers = execFileSync("git", ["interpret-trailers", "--parse"], { input: message, encoding: "utf-8", timeout: 5000 });
+    }
+    catch {
+        return [];
+    }
+    const found = [...trailers.matchAll(/^xkg-capture:[ \t]*(\S+)[ \t]*$/gim)].map((m) => m[1]);
+    return [...new Set(found)];
+}
+/**
+ * Installs or updates xkg's line in the repo's post-commit hook and returns the hook's path.
+ * The line holds no credential (the hooks directory may be tracked); the key comes from
+ * `xkg config` at run time. It reads the sha before going to the background, so a quick
+ * next commit can't be reported in its place. It runs the CLI version that installed it, so
+ * a new release reaches a repo only when the hook is installed again.
+ */
+export function installPostCommitHook(cwd = process.cwd(), version = getCurrentVersion()) {
+    const hooksDir = resolve(cwd, git(cwd, "rev-parse", "--git-path", "hooks"));
+    const path = join(hooksDir, "post-commit");
+    const pin = version === "0.0.0" ? "latest" : version;
+    const line = `xkg_sha=$(git rev-parse HEAD); npx -y ${PACKAGE}@${pin} post-commit --sha "$xkg_sha" >/dev/null 2>&1 & ${MARKER}`;
+    const existing = existsSync(path) ? readFileSync(path, "utf-8") : "#!/bin/sh\n";
+    if (!/^#!\s*\S*\b(?:env\s+)?(?:sh|bash|zsh|dash|ksh)\b/.test(existing.split("\n")[0] ?? "")) {
+        throw new Error(`${path} is not a shell script; add this line to it yourself:\n${line}`);
+    }
+    const kept = existing.split("\n").filter((l) => !l.endsWith(MARKER) || !l.includes(" post-commit "));
+    const body = kept.join("\n").replace(/\n*$/, "\n");
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(path, `${body}${line}\n`);
+    chmodSync(path, 0o755);
+    return path;
+}
+/** Runs after each commit: reports every `xkg-capture:` trailer of `sha` to apply_capture. Never throws. */
+export async function postCommit(apiKey, sha, cwd = process.cwd()) {
+    try {
+        const full = git(cwd, "rev-parse", "--verify", `${sha}^{commit}`);
+        const trailers = captureTrailers(git(cwd, "log", "-1", "--format=%B", full));
+        if (trailers.length === 0)
+            return;
+        const files = git(cwd, "diff-tree", "--root", "--no-commit-id", "--name-only", "-r", full).split("\n").filter(Boolean);
+        const target = files.slice(0, 5).join(", ") + (files.length > 5 ? ` and ${files.length - 5} more` : "");
+        // One session for all of this commit's reports. Without one they still count, as "unknown".
+        const session = await initializeMcp(apiKey, HOOK_CLIENT, 10000)
+            .then((res) => (res.ok ? res.headers.get("mcp-session-id") : null))
+            .catch(() => null);
+        for (const filename of trailers) {
+            await callMcp(apiKey, "apply_capture", { filename, commit_sha: full, target_file: target }, 10000, session).catch(() => null);
+        }
+    }
+    catch {
+        // Never disturb a commit
+    }
+}
+/** Checks that the hook can reach xkg with this key. Reports no capture. */
+export async function checkHookConnection(apiKey) {
+    let res;
+    try {
+        res = await initializeMcp(apiKey, HOOK_CLIENT, 10000);
+    }
+    catch (err) {
+        return { ok: false, reason: `Could not reach xkg: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (res.status === 401) {
+        return { ok: false, reason: `xkg rejected the API key (HTTP 401). Run setup-git-hook again with a current key.` };
+    }
+    if (!res.ok)
+        return { ok: false, reason: `xkg answered HTTP ${res.status}.` };
+    return { ok: true };
+}

package/dist/cli/hooks.js

@@ -102,8 +102,12 @@ export function setupHooks(apiKey, opts = {}) {
     // skipIfExists (serve-mcp auto-install): preserve user-configured hooks but
     // silently migrate hooks that pin a version or use the old package name.
     if (existingCmd && opts.skipIfExists) {
-        if (isCurrentHook(existingCmd))
+        if (isCurrentHook(existingCmd)) {
+            // A vault hook left under the old PreToolCall key never ran; move it.
+            if (findVaultHook(hooks.PreToolCall ?? []))
+                setupPreToolHook(apiKey, { silent: opts.silent, skipIfExists: true });
             return;
+        }
         // Migration: preserve the existing --briefing flag when upgrading to @latest
         opts = { ...opts, briefing: existingCmd.includes("--briefing") };
     }
@@ -130,41 +134,57 @@ export function setupHooks(apiKey, opts = {}) {
             console.log("At the start of each Claude Code session you'll see your inbox count.");
         }
     }
-    if (opts.vault) {
+    if (opts.vault || findVaultHook(hooks.PreToolCall ?? [])) {
         setupPreToolHook(apiKey, { silent: opts.silent, skipIfExists: opts.skipIfExists });
     }
 }
-export function setupPreToolHook(apiKey, opts = {}) {
-    const settings = readSettings();
-    const hooks = settings.hooks ?? {};
-    const preToolCall = hooks.PreToolCall ?? [];
-    let existingCmd = null;
-    for (const group of preToolCall) {
-        for (const h of group.hooks ?? []) {
-            if (typeof h.command === "string" && isXkgPreToolHook(h.command)) {
-                existingCmd = h.command;
-                break;
-            }
-        }
-        if (existingCmd)
-            break;
-    }
-    if (existingCmd && opts.skipIfExists) {
-        if (isCurrentHook(existingCmd))
-            return;
-    }
-    const command = `npx -y ${PACKAGE}@latest vault-check --key ${apiKey}`;
-    const filtered = preToolCall
+/** Tools whose edits trigger a vault scan. Also the PreToolUse matcher. */
+const EDITING_TOOLS = ["Edit", "Write", "MultiEdit"];
+/** Removes xkg vault hooks from one hook event's groups, dropping groups left empty. */
+function withoutVaultHook(groups) {
+    return groups
         .map((group) => ({
         ...group,
         hooks: (group.hooks ?? []).filter((h) => !(typeof h.command === "string" && isXkgPreToolHook(h.command))),
     }))
         .filter((group) => (group.hooks ?? []).length > 0);
-    filtered.push({ hooks: [{ type: "command", command }] });
-    settings.hooks = { ...hooks, PreToolCall: filtered };
+}
+function findVaultHook(groups) {
+    for (const group of groups) {
+        for (const h of group.hooks ?? []) {
+            if (typeof h.command === "string" && isXkgPreToolHook(h.command))
+                return h.command;
+        }
+    }
+    return null;
+}
+/**
+ * Installs the vault hook on PreToolUse for file edits.
+ *
+ * Earlier versions wrote it under `PreToolCall`, which Claude Code has no such
+ * event for, so it never ran. Any hook left there is moved to PreToolUse.
+ */
+export function setupPreToolHook(apiKey, opts = {}) {
+    const settings = readSettings();
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const legacy = hooks.PreToolCall ?? [];
+    const existingCmd = findVaultHook(preToolUse);
+    if (existingCmd && opts.skipIfExists && isCurrentHook(existingCmd) && !findVaultHook(legacy))
+        return;
+    const command = `npx -y ${PACKAGE}@latest vault-check --key ${apiKey}`;
+    const filtered = withoutVaultHook(preToolUse);
+    filtered.push({ matcher: EDITING_TOOLS.join("|"), hooks: [{ type: "command", command }] });
+    const next = { ...hooks, PreToolUse: filtered };
+    const legacyLeft = withoutVaultHook(legacy);
+    if (legacyLeft.length > 0)
+        next.PreToolCall = legacyLeft;
+    else
+        delete next.PreToolCall;
+    settings.hooks = next;
     writeSettings(settings);
     if (!opts.silent) {
-        console.log("xkg vault hook installed (PreToolCall).");
+        console.log("xkg vault hook installed (PreToolUse).");
         console.log("Your knowledge vault will surface relevant captures as you edit files.");
     }
 }
@@ -203,13 +223,31 @@ function detectProjectContext() {
     // Local agent instructions may contain private maintainer notes; do not upload them.
     return parts.length > 0 ? parts.join("\n\n") : "current project";
 }
-export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000) {
+/**
+ * Opens an MCP session that names the caller, so the server can tell which
+ * agent made the calls on it. Returns the raw reply; callers read the status
+ * or the Mcp-Session-Id header.
+ */
+export async function initializeMcp(apiKey, client, timeoutMs = 15000) {
+    return fetch(HOSTED_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "initialize",
+            params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: client } },
+            id: 1,
+        }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}
+export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000, sessionId) {
+    const headers = { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+    if (sessionId)
+        headers["Mcp-Session-Id"] = sessionId;
     const res = await fetch(HOSTED_URL, {
         method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${apiKey}`,
-        },
+        headers,
         body: JSON.stringify({
             jsonrpc: "2.0",
             method: "tools/call",
@@ -236,8 +274,7 @@ export async function vaultCheck(apiKey) {
             return;
         }
         // Only act on file-editing tool calls
-        const editingTools = ["Edit", "Write", "MultiEdit"];
-        if (!hookData.tool_name || !editingTools.includes(hookData.tool_name))
+        if (!hookData.tool_name || !EDITING_TOOLS.includes(hookData.tool_name))
             return;
         const filePath = hookData.tool_input?.["file_path"] ??
             hookData.tool_input?.["path"];
@@ -256,7 +293,11 @@ export async function vaultCheck(apiKey) {
         const filenameMatches = text.match(/(?:inbox|applied|archived)\/[\w-]+\.md/g) ?? [];
         if (filenameMatches.length > 0)
             appendSessionSurfaced(filenameMatches);
-        process.stdout.write(text.trim() + "\n");
+        // Plain stdout from a PreToolUse hook only reaches the debug log; the agent
+        // reads it only as additionalContext.
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: text.trim() },
+        }) + "\n");
     }
     catch {
         // Silent fail — never interrupt a tool call
@@ -286,7 +327,9 @@ export async function inboxCheck(apiKey, opts = {}) {
             if (applyNow.length > 0) {
                 const filenames = applyNow.map((s) => `'${s.filename}'`).join(", ");
                 process.stdout.write(`\n---\nxkg: ${applyNow.length} insight${applyNow.length === 1 ? "" : "s"} ready to apply now.\n` +
-                    `Run generate_plan with selected_captures: [${filenames}] to get a full implementation plan.\n`);
+                    `Run generate_plan with selected_captures: [${filenames}] to get a full implementation plan.\n` +
+                    `When you commit a change that applies one, add a trailer per capture to the commit message (e.g. xkg-capture: ${applyNow[0].filename}), ` +
+                    `then call apply_capture with its filename and the commit sha (git rev-parse HEAD). xkg counts each capture and commit once.\n`);
             }
             return;
         }

package/dist/cli/index.js

@@ -41,6 +41,52 @@ async function main() {
         await vaultCheck(apiKey);
         return;
     }
+    if (command === "setup-git-hook") {
+        const { installPostCommitHook, checkHookConnection } = await import("./git-hook.js");
+        const { readConfig, setConfigField } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const keyArg = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
+        // The hook file may be tracked in git, so the key lives in ~/.xkg/config.json instead
+        if (keyArg)
+            setConfigField("key", keyArg);
+        if (!readConfig().key) {
+            console.error("Usage: npx @xmu-labs/xkg setup-git-hook --key YOUR_API_KEY (run inside the repo)");
+            process.exit(1);
+        }
+        try {
+            const path = installPostCommitHook();
+            console.log(`xkg git hook installed: ${path}`);
+            console.log("Commits with an `xkg-capture: <filename>` trailer are now recorded as applied.");
+        }
+        catch (err) {
+            console.error(err instanceof Error && err.message.includes("not a shell script")
+                ? err.message
+                : "Not a git repository. Run this inside the repo you code in.");
+            process.exit(1);
+        }
+        // The hook runs in the background with its output discarded, so check now that it can report.
+        const check = await checkHookConnection(readConfig().key);
+        if (check.ok) {
+            console.log("Checked: the hook reached xkg with your key.");
+        }
+        else {
+            console.error(`The hook is installed but can't report yet: ${check.reason}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === "post-commit") {
+        const { postCommit } = await import("./git-hook.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        const shaIdx = args.indexOf("--sha");
+        const sha = shaIdx !== -1 ? args[shaIdx + 1] : "HEAD";
+        if (!apiKey || !sha)
+            process.exit(0); // silent fail in hook context
+        await postCommit(apiKey, sha);
+        return;
+    }
     if (command === "config") {
         const { runConfigCommand } = await import("./config.js");
         runConfigCommand(args.slice(1));
@@ -84,8 +130,9 @@ function printHelp() {
     xkg serve-mcp --key KEY                                    Start the MCP server for your AI worker
     xkg setup-hooks --key KEY                                  Install inbox count hook (fast)
     xkg setup-hooks --key KEY --briefing                       Install full briefing hook (uses LLM)
-    xkg setup-hooks --key KEY --vault                          Install vault hook (PreToolCall)
+    xkg setup-hooks --key KEY --vault                          Install vault hook (PreToolUse)
     xkg setup-hooks --key KEY --briefing --vault               Install both hooks
+    xkg setup-git-hook --key KEY                               Record commits with an xkg-capture trailer (any agent)
     xkg config set agent "claude -p"                           Set which AI worker kos drives
     xkg kos --key KEY [--plan FILE]                            Implement a plan in an isolated worktree
     xkg help                                                   Show this help
@@ -97,6 +144,7 @@ function printHelp() {
     generate_plan     — Turn selected captures into a full implementation plan
     list_plans        — List or read saved implementation plans
     vault_scan        — Scan all captures for relevance to current activity
+    apply_stats       — Captures applied per week, and how many came with a commit
     curate            — Validate URLs and flag stale captures
 
   kos — implement plans with your own AI worker (model-agnostic):

package/dist/cli/mcp-server.js

@@ -11,25 +11,8 @@ const pending = new Set();
 function rpcError(id, message) {
     sendMessage({ jsonrpc: "2.0", id, error: { code: -32603, message } });
 }
-async function proxyToHosted(apiKey, msg) {
-    let res;
-    try {
-        res = await fetch(HOSTED_URL, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${apiKey}`,
-            },
-            body: JSON.stringify(msg),
-        });
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : "unknown error";
-        rpcError(msg.id, `Could not reach xkg at ${HOSTED_URL}: ${detail}`);
-        return;
-    }
-    const body = await res.text().catch(() => "");
-    const result = interpretResponse(res.status, res.headers.get("content-type"), body);
+async function proxyToHosted(hosted, msg) {
+    const result = await hosted.send(msg);
     if ("error" in result) {
         rpcError(msg.id, result.error);
         return;
@@ -61,6 +44,47 @@ export function interpretResponse(status, contentType, body) {
         return { error: `xkg returned malformed JSON (HTTP ${status}).` };
     }
 }
+/**
+ * The connection to the hosted server. It keeps the Mcp-Session-Id that
+ * `initialize` returns and sends it on every later call, so the server knows
+ * which agent is calling. When the session expires (404), it replays the
+ * client's `initialize` for a new one and retries the call once.
+ */
+export function createHostedSession(apiKey, url, fetchFn = fetch) {
+    let sessionId = null;
+    let initializeMsg = null;
+    async function post(msg) {
+        const headers = { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` };
+        if (sessionId && msg.method !== "initialize")
+            headers["Mcp-Session-Id"] = sessionId;
+        let res;
+        try {
+            res = await fetchFn(url, { method: "POST", headers, body: JSON.stringify(msg) });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : "unknown error";
+            return { error: `Could not reach xkg at ${url}: ${detail}` };
+        }
+        if (msg.method === "initialize")
+            sessionId = res.headers.get("mcp-session-id") ?? sessionId;
+        const body = await res.text().catch(() => "");
+        return { ...interpretResponse(res.status, res.headers.get("content-type"), body), status: res.status };
+    }
+    return {
+        async send(msg) {
+            if (msg.method === "initialize")
+                initializeMsg = msg;
+            const hadSession = sessionId !== null && msg.method !== "initialize";
+            let { status, ...reply } = await post(msg);
+            if (status === 404 && hadSession && initializeMsg) {
+                sessionId = null;
+                await post(initializeMsg);
+                ({ status, ...reply } = await post(msg));
+            }
+            return reply;
+        },
+    };
+}
 /** Track a proxied request so shutdown can await it. */
 function track(p) {
     pending.add(p);
@@ -98,6 +122,7 @@ export async function serveMcp() {
         // Non-fatal — hook setup should never block the MCP server from starting
     }
     process.stderr.write("xkg MCP server starting (proxying to hosted instance)...\n");
+    const hosted = createHostedSession(apiKey, HOSTED_URL);
     let buffer = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
@@ -113,7 +138,7 @@ export async function serveMcp() {
                 // Handle notifications/initialized locally (no response needed)
                 if (msg.method === "notifications/initialized")
                     continue;
-                track(proxyToHosted(apiKey, msg));
+                track(proxyToHosted(hosted, msg));
             }
             catch {
                 process.stderr.write(`Failed to parse: ${line}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnemos-capture",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "xkg — Turn what you discover into context your AI workers can use. Capture once, then brief, plan, and execute with any MCP-compatible tool.",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
     "prepublishOnly": "npm run build:cli",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:e2e": "playwright test",
+    "test:e2e": "playwright test --project=network",
+    "test:ui": "playwright test --project=ui",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit"
   },
@@ -40,7 +41,10 @@
     "type": "git",
     "url": "git+https://github.com/xmu-labs/xkg.git"
   },
-  "homepage": "https://github.com/xmu-labs/xkg",
+  "homepage": "https://xkg.xmu.sh",
+  "bugs": {
+    "url": "https://github.com/xmu-labs/xkg/issues"
+  },
   "files": [
     "dist/cli/",
     "LICENSE",