@yugabytedb/meko-mcp 1.1.0 → 2.0.0

package/README.md

@@ -18,7 +18,7 @@ The installer is path-agnostic — the three forms below are equivalent. Pick th
 | Repo clone, from repo root | `node installer/bin/create-meko-setup.mjs [options]` |
 | Repo clone, from `installer/` | `node bin/create-meko-setup.mjs [options]` |
 
-Claude Desktop install (issue [#7](https://github.com/amiramm/meko-mcp-server/issues/7)) still requires a repo clone — the `.skill` packaging script isn't bundled. All other clients work from the npm tarball without a checkout.
+Claude Desktop has two install paths: a one-click `.mcpb` Desktop Extension downloaded from GitHub Releases, and the scripted installer here (run via `npx` or from a clone) — only the latter also installs the agent skill bundle. See [Claude Desktop install](#claude-desktop-install) below for the full comparison.
 
 **Interactive (recommended for first-time users):**
 
@@ -40,19 +40,57 @@ npx @yugabytedb/meko-mcp --local --yes
 npx @yugabytedb/meko-mcp --client cursor --local --scope project --yes
 ```
 
-**Claude Desktop install (local, from a repo clone):**
+**Claude Desktop install:**
 
-Claude Desktop supports two install paths — pick one per machine:
+Claude Desktop has two install paths — pick based on whether you want the agent skill (the behavioral guide that teaches the agent *when* to call Meko tools — how to capture turns via per-turn `conversation_add_message` posting so the server can extract memories, and when the narrow explicit `memory_add` cases apply):
 
-**Option A — Desktop Extension (`.mcpb`), one-click.** Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/amiramm/meko-mcp-server/releases) and drag it onto **Claude Desktop > Settings > Extensions > Install from file**. You'll be prompted for your Meko MCP URL and API key in the Settings UI, and that's it. Best for non-technical users. See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle. Prerequisite: Node 18+ on PATH (the bundle launches `npx mcp-remote` under the hood).
+| | Option A: `.mcpb` Desktop Extension | Option B: `create-meko-setup` installer |
+|---|---|---|
+| Installs MCP server | Yes | Yes |
+| Installs the agent skill (behavioral guide) | **No** | **Yes** |
+| Repo clone needed | No | No (works via `npx`); clones also work |
+| Best for | Non-technical users; quickest path to a working MCP connection | Anyone who wants the skill that teaches the agent *when* to call Meko tools |
+| Auto-capture of conversations/memories | No (see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8)) | Skill-driven — the agent posts each substantive turn via `conversation_add_message` and the server extracts memories from those posts. Still less reliable than Claude Code hooks because it's agent-driven, not lifecycle-driven. |
+
+You can also combine both: install via `.mcpb` for the MCP wiring, then run Option B to add the skill bundle. If you re-run the Option B installer on top of an `.mcpb` install, it detects the existing entry and prompts before overwriting `mcpServers.meko`.
+
+**Option A — Desktop Extension (`.mcpb`), one-click:**
+
+1. Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/yugabyte/meko-mcp-server/releases) (e.g. `meko-1.1.0.mcpb`).
+2. Open **Claude Desktop > Settings > Extensions > Install from file** and select the file (or drag the file onto that pane).
+3. When prompted, paste your Meko MCP URL and API key.
+4. Quit and relaunch Claude Desktop.
+5. Verify in chat: *"Is Claude configured with an MCP Server for Meko?"*
+
+Prerequisite: Node 18+ on `PATH` (the bundle launches `npx mcp-remote` under the hood). See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle.
 
-**Option B — `create-meko-setup` installer.** Use this when you want a scripted / repeatable install, or when you need the `.skill` bundle built at the same time:
+**Option B — `create-meko-setup` installer:**
+
+Run via `npx` (no clone needed) — pick the form that matches the table at the top of this section. From a repo clone:
 
 ```bash
 node installer/bin/create-meko-setup.mjs --client claude-desktop --local --yes
 ```
 
-Builds a `.skill` bundle at `skills/meko-mcp-tools-desktop.skill`. Drag it onto Claude Desktop (or import via Settings > Extensions) once and restart the app. The installer also merges `mcpServers.meko` into `claude_desktop_config.json`. If it detects that Meko was previously installed via the `.mcpb` path (Option A), it flags the entry and prompts before overwriting so you don't end up with two conflicting configs.
+Or via npm without a clone:
+
+```bash
+npx @yugabytedb/meko-mcp --client claude-desktop --local --yes
+```
+
+This does two things:
+
+1. Merges `mcpServers.meko` into `claude_desktop_config.json` (backed up to `.bak`).
+2. Builds two bundles — `meko-mcp-tools-desktop.skill` (memory doctrine) and `meko-select-datapack-desktop.skill` (datapack selection/pinning) — and prints their absolute paths. The location depends on how you invoked the installer — under the npm package's asset root for `npx`, or under `skills/` in your clone. **Import both**; the selector bundle is required for pinned-datapack capture routing.
+
+Then, **once per machine**:
+
+1. Open the path that the installer printed (look for the `Built Meko skill bundle: ...` log lines — there are two).
+2. Drag **both** `meko-mcp-tools-desktop.skill` and `meko-select-datapack-desktop.skill` onto the Claude Desktop window — or import each via **Settings > Extensions > Install from file**.
+3. Quit and relaunch Claude Desktop.
+4. Verify both loaded: ask *"Which Meko skills do you have available?"* — the agent should mention `meko-mcp-tools-desktop` and `meko-select-datapack-desktop`.
+
+Re-run the installer to refresh the bundles when skill content updates; you'll need to re-drag the rebuilt `.skill` files to pick up changes.
 
 **Install on multiple clients at once:**
 
@@ -107,14 +145,22 @@ The canary used to do a `memory_add` → `memory_get_by_id` → `memory_delete_b
 - **Cursor**
   - MCP config: `~/.cursor/mcp.json` or `.cursor/mcp.json`
   - Hooks config: `~/.cursor/hooks.json` or `.cursor/hooks.json` (native mode)
-  - Skills path: `~/.cursor/skills` or `.cursor/skills`
+  - Stable hook scripts: `~/.cursor/meko-hooks/hooks-handlers` or `.cursor/meko-hooks/hooks-handlers`. The installer copies the shipped tree here so an npx cache cleanup cannot break configured hooks.
+  - Skills path: `~/.cursor/skills` or `.cursor/skills`. Packaged installs copy skills instead of symlinking back into the ephemeral npm package cache.
 - **OpenAI Codex (CLI + Desktop App)** — one install configures both surfaces (they share `~/.codex/`).
   - MCP config: `~/.codex/config.toml` (TOML; `[mcp_servers.<name>]` block).
   - Skills path: `~/.agents/skills/meko-mcp-tools/` (the shared agent-skills convention).
   - System prompt: `~/.codex/AGENTS.md` (a Meko-managed sentinel block is upserted; user content outside the fence is preserved).
-  - **Cloud auth**: Codex's TOML stores `bearer_token_env_var = "MEKO_API_KEY"` rather than the key itself. You must export `MEKO_API_KEY` in your shell before launching Codex. The installer offers (interactively, never with `--yes`) to append the export line to your shell rc (`~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`). On macOS, when the desktop app is detected the installer also offers to run `launchctl setenv MEKO_API_KEY ...` since macOS apps launched from Finder/Dock do not inherit shell-rc env vars.
+  - **Cloud auth (MCP server)**: Codex's TOML stores `bearer_token_env_var = "MEKO_API_KEY"` rather than the key itself. You must export `MEKO_API_KEY` in your shell before launching Codex. The installer offers (interactively, never with `--yes`) to append the export line to your shell rc (`~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`). On macOS, when the desktop app is detected and an API key is supplied, the installer runs `launchctl setenv MEKO_API_KEY ...` so Codex.app launched from Finder/Dock can authenticate in the current login session.
+  - **Cloud WAF User-Agent** (cloud installs only): Cloud Meko sits behind a WAF that returns an HTML `403 Forbidden` for any HTTP request with no `User-Agent`. Codex's native MCP client sends none by default, so its `initialize` handshake would 403 and the `meko` server would fail to start with `MCP client for 'meko' failed to start ... HTTP 403`. `codex mcp add` exposes no header flag, so the installer writes a per-server header into `~/.codex/config.toml`:
+    ```toml
+    [mcp_servers.meko]
+    http_headers = { "User-Agent" = "codex-mcp/1.0 (+https://github.com/yugabyte/meko-mcp-server)" }
+    ```
+    This is **scoped to the Meko server block only** — it affects requests Codex makes to the Meko MCP server and nothing else (other MCP servers, other Codex traffic are untouched). The installer **merges** rather than clobbers: it reads whatever headers you already have — in either the inline `http_headers = { … }` form or the table form `[mcp_servers.meko.http_headers]` — keeps every one of them, and only *adds* a `User-Agent` if you don't already have one (a custom User-Agent is left exactly as you set it). If you had the table form, it's folded into the single inline line so there's never a conflicting duplicate definition. This holds **across a reinstall** too: re-registration deletes and rewrites the whole server block, so the installer snapshots your headers beforehand and merges them back. It **backs up `config.toml` to `config.toml.bak`** before writing. Local installs skip this (no WAF in front of `localhost`). Related: the capture-hook side of the same WAF issue is [#174](https://github.com/yugabyte/meko-mcp-server/issues/174).
   - **No project scope**: Codex has no per-project config. `--scope project --client codex` warns and degrades to user scope.
-  - **No auto-capture**: Codex does not expose user-installable session lifecycle hooks, so `session-start` / `session-end` capture is not available. Memory persistence still works via the model proactively calling `memory_search` / `memory_add` (the AGENTS.md block prompts this).
+  - **Auto-capture hooks**: when Codex hooks are available, the installer copies the Meko hook scripts to `~/.codex/meko-hooks/hooks-handlers/`, writes Meko lifecycle hooks to `~/.codex/hooks.json` pointing at that copy, and prunes stale Meko hook entries from deleted install paths. The scripts live under `$CODEX_HOME` (not the shipped package) on purpose: under `npx @yugabytedb/meko-mcp` the package unpacks into an ephemeral `~/.npm/_npx/<hash>/` cache dir that npx later garbage-collects, so a `hooks.json` pinned there would become a dangling `bash '<missing>'` and Codex would report `SessionStart hook (failed) — hook exited with code 127`. Copying under `$CODEX_HOME` gives the hook a home-dir-stable target; re-running the installer refreshes the copy and auto-heals any stale npx-pinned entry. `memory_search` still handles recall; capture is driven by the hooks (and, where hooks are unavailable, by AGENTS.md-prompted per-turn `conversation_add_message` posting that the server extracts memories from). Explicit `memory_add` is reserved for the narrow cases — the user says "remember this", a fact lives only in the assistant's output or a tool result, or a negated/corrected fact needs overwriting.
+  - **API key storage** (security note): Codex's hooks.json schema rejects a top-level `env` block and provides no per-command env field. The installer writes `MEKO_MCP_URL` and (when supplied) `MEKO_API_KEY` to `~/.codex/meko-env.sh` at mode 0600 (user read/write only); each hook's `command` field sources that file before invoking bash, e.g. `. '/Users/you/.codex/meko-env.sh' && bash '/Users/you/.codex/meko-hooks/hooks-handlers/session-start.sh'`. The key never appears in process arguments, so `ps -ef` from another user can't lift it while a hook is running. Trust boundary is the same as `~/.aws/credentials` or `~/.netrc` — file-system permissions on the user's home directory. If your threat model precludes even that, install for the local Meko URL (no API key prompt), or skip hook installation by deleting the Meko entries from `~/.codex/hooks.json` and removing `~/.codex/meko-env.sh` and `~/.codex/meko-hooks/` after install.
   - **Restart Codex.app** after install so it picks up the new MCP server registration.
 
 ## CLI Reference
@@ -132,7 +178,7 @@ Usage:
 | `--local` | Use local Meko at `http://localhost:8000/mcp` (no API key needed) | `false` |
 | `--scope <scope>` | Config scope: `user` or `project` (`claude-desktop` uses user scope config) | `user` |
 | `--name <name>` | MCP server name in config | `meko` |
-| `--cursor-hook-mode <mode>` | Cursor hook strategy: `native`, `claude-compat`, `hybrid` | `hybrid` |
+| `--cursor-hook-mode <mode>` | Cursor hook strategy: `native` or `claude-compat` | `native` |
 | `--skip-skills` | Skip plugin marketplace and skills installation (steps 3-4) | `false` |
 | `--skip-validation` | Skip post-install validation (step 5) | `false` |
 | `--no-canary` | Skip the canary `datapack_list` call. Basic connectivity + tools/list still run. | `false` |
@@ -286,7 +332,7 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 ### What does NOT get migrated (v1)
 
 - Slash-command skills, hooks, and `.claude/settings.json` — those remain in Claude Code's own config; Meko has no equivalent tool.
-- Knowledge-base documents — would need an S3 upload path and `knowledgebase_trigger_index_creation` wiring.
+- Knowledge-base documents — KB ingestion is UI-only (Datapack → Actions → Add Knowledge); not exposed via MCP.
 - Transcripts from other coding agents (Aider, Continue.dev, Windsurf, Codex). Claude Code + Cursor only.
 - `user_id` is left null on every call (the server fills it from the API key). Multi-user routing is a follow-up.
 
@@ -297,15 +343,17 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 | One-command install | Yes | Yes | Yes | Yes |
 | MCP server registration | via `claude mcp add` | via `claude_desktop_config.json` merge using `mcp-remote` stdio bridge | via `.cursor/mcp.json` merge | via `codex mcp add` (CLI) or direct TOML write (App-only) |
 | Backup before config write | `.bak` on `~/.claude/settings.json` | `.bak` on `claude_desktop_config.json` | `.bak` on Cursor config | `.bak` on `~/.codex/config.toml` and `~/.codex/AGENTS.md` |
-| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (hybrid hook mode) | **No** — Codex has no user-installable hooks; AGENTS.md prompts proactive memory tool calls instead |
+| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (native hooks; first SessionStart may pause briefly while creating the Meko conversation) | **No** — Codex has no user-installable hooks; AGENTS.md prompts proactive memory tool calls instead |
 | Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Skill + AGENTS.md (proactive `memory_add`) |
 | Skill install | Plugin marketplace (automatic) | `.skill` bundle auto-built, user drags into app | Copy into `.cursor/skills` | Copy into `~/.agents/skills/meko-mcp-tools/` |
 | Uninstall | Full automatic | MCP entry removed; skill must be removed manually from app | MCP + hooks + skills cleaned up | MCP entry, skill dir, and AGENTS.md block all cleaned up |
+
+Cursor previously had a hybrid hook mode that also wrote Claude-compatible hooks into `~/.claude/settings.json`. If you used that mode and now see duplicate `claude_code:*` Meko instructions in Cursor, remove the old Meko hook entries from `~/.claude/settings.json` unless you still use them for Claude Code.
 | `agent_id` used by skill | `claude_code:<repo>` per project (via SessionStart hook); cross-project facts go to `meko_agent` | `claude_desktop` | `cursor:<repo>` per project (via Cursor hook); cross-project facts go to `meko_agent` | Whatever the agent derives by following the meko-mcp-tools skill (no hook injects an agent_id; the AGENTS.md block defers to the skill) |
 | Transport | HTTP only | HTTP (or stdio via hand-edited config) | HTTP only | HTTP (Codex's `bearer_token_env_var` model) |
-| Auth model | inline `Authorization: Bearer ...` header | inline header via `mcp-remote` | inline header | env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`) |
+| Auth model | inline `Authorization: Bearer ...` header | inline header via `mcp-remote` | inline header | MCP server: env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`). Hooks: key written to `~/.codex/meko-env.sh` at mode 0600; each hook command sources the file before bash (no env block in Codex's hooks schema; see [Security](#security)). |
 | Project scope | Yes (`--scope project`) | No | Yes (`--scope project`) | No (warns and degrades to user scope) |
-| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — | Auto-capture (blocked on upstream Codex exposing user-installable hooks) |
+| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — | Native `codex:<repo>` agent_id classification in capture.js |
 
 ## Cloud vs Local
 
@@ -323,22 +371,32 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 
 ## Security
 
-**Where credentials are stored:**
+**Where credentials are stored** (per client; all files inherit standard user-only filesystem permissions):
 
-- **API key header** -- stored in `~/.claude.json` (MCP server config, managed by `claude mcp add`). Readable only by the current user.
-- **`MEKO_API_KEY` env var** -- written to `~/.claude/settings.json` so lifecycle hooks can authenticate with the MCP server. This file has standard user-only filesystem permissions.
+- **Claude Code**
+  - API key header — stored in `~/.claude.json` (MCP server config, managed by `claude mcp add`).
+  - `MEKO_API_KEY` env var — written to `~/.claude/settings.json` under `env` so lifecycle hooks can authenticate with the MCP server.
+- **Claude Desktop**
+  - `MEKO_API_KEY` env var — written to `claude_desktop_config.json` under `mcpServers.<name>.env`. The header itself uses `${MEKO_API_KEY}` interpolation in `args`, so the key value lives only in the `env` block.
+- **Cursor**
+  - API key header — stored in `~/.cursor/mcp.json` (or `.cursor/mcp.json` for project scope) under `mcpServers.<name>.headers.Authorization`.
+  - `MEKO_API_KEY` env var — written to `~/.cursor/hooks.json` (native hook mode) and/or `~/.claude/settings.json` (claude-compat hook mode) under `env` so lifecycle hooks can authenticate.
+- **OpenAI Codex (CLI + Desktop App)**
+  - MCP-server bearer reference — `~/.codex/config.toml` stores `bearer_token_env_var = "MEKO_API_KEY"`, **not** the key itself. The runtime env (shell rc or `launchctl setenv`) supplies the value.
+  - Hook commands — Codex's `~/.codex/hooks.json` schema rejects a top-level `env` block and provides no per-command env field, so the installer writes `MEKO_API_KEY` to `~/.codex/meko-env.sh` at **mode 0600** (user read/write only). Each Meko hook's `command` field sources that file before invoking bash, so the key never appears in process arguments — `ps -ef` from another user can't lift it while the hook runs. Same trust boundary as `~/.aws/credentials` or `~/.netrc` (file-system permissions on the user's home directory). To opt out: install for the local Meko URL (no key prompt), or skip Codex hook installation by deleting the Meko entries from `~/.codex/hooks.json` and removing `~/.codex/meko-env.sh` and `~/.codex/meko-hooks/` after install. The hook scripts themselves are copied to `~/.codex/meko-hooks/hooks-handlers/` (a home-dir-stable location) rather than referenced from the shipped package, so `npx`'s cache garbage-collection can't leave the hook pointing at a deleted script (which would fail with `code 127`).
 
 **How credentials are protected:**
 
 - The `--verbose` flag never prints the actual API key. It always appears as `<set>` or `<not set>`.
 - `--dry-run` mode redacts the key in displayed commands (shown as `<set>`).
 - The API key is never logged to stdout or stderr during normal operation.
-- Interactive mode uses masked input (echoes `*` characters) when prompting for the API key.
-- The `MEKO_API_KEY` env var fallback means the key does not need to appear in shell history -- set it in your shell profile or CI secrets.
+- Interactive mode uses silent input (sudo/ssh-style — no characters echoed) when prompting for the API key to prevent cleartext leaks during paste or with specific terminal configurations.
+- The `MEKO_API_KEY` env var fallback means the key does not need to appear in shell history — set it in your shell profile or CI secrets.
+- During Codex installs, the installer emits a `warn`-level log line confirming where the API key has been written.
 
 **Backups:**
 
-Before modifying `~/.claude/settings.json`, the installer creates a `.bak` copy at `~/.claude/settings.json.bak`. The merge is additive: existing keys are preserved unless explicitly overridden.
+Before modifying any config file the installer touches, it creates a `.bak` copy alongside the original (e.g. `~/.claude/settings.json.bak`, `~/.codex/config.toml.bak`, `~/.codex/AGENTS.md.bak`). The merge is additive: existing keys are preserved unless explicitly overridden.
 
 ## Upgrading
 
@@ -512,7 +570,7 @@ cp ~/.claude/settings.json.bak ~/.claude/settings.json
 Missing core tools: memory_search, memory_get_by_id, conversation_create. Found 0 tool(s) total.
 ```
 
-The MCP server responded but does not expose the expected tools (`memory_search`, `memory_get_by_id`, `conversation_create`, `db_summarize_database`). This usually means a server version mismatch. Update the MCP server or check which datapack is connected. `memory_get_by_id` is used by the canary round-trip for direct-row verification (see [Post-install validation](#post-install-validation-canary-round-trip) above), so an older server that exposes `memory_search` but not `memory_get_by_id` will fail the canary check.
+The MCP server responded but does not expose the expected tools (`memory_search`, `memory_get_by_id`, `conversation_create`, `datapack_list`). This usually means a server version mismatch. Update the MCP server or check which datapack is connected. `memory_get_by_id` is used by the canary round-trip for direct-row verification (see [Post-install validation](#post-install-validation-canary-round-trip) above), so an older server that exposes `memory_search` but not `memory_get_by_id` will fail the canary check.
 
 ### DNS lookup failed
 
@@ -538,7 +596,7 @@ After the installer writes `claude_desktop_config.json`, **quit and relaunch** C
    ```json
    "meko": {
      "command": "npx",
-     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only"]
+     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only", "--header", "User-Agent:meko-mcp-installer/1.0"]
    }
    ```
    If you see a `"url"` field at the top level instead, re-run the installer to rewrite it.
@@ -557,7 +615,7 @@ The installer runs `skills/scripts/package-desktop-skill.sh` via `bash`. If pack
 
 ### Claude Desktop capture doesn't happen automatically
 
-Expected: Claude Desktop has no SessionStart / PreCompact / SessionEnd hook API, so automatic transcript capture is not yet implemented. The skill tells the agent to proactively call `memory_add` and `conversation_create`, but this relies on agent behavior. See [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) for the planned automatic-capture work.
+Expected: Claude Desktop has no SessionStart / PreCompact / SessionEnd hook API, so there is no lifecycle-driven transcript capture. Instead, the skill tells the agent to post each substantive turn via `conversation_add_message` (creating a conversation first with `conversation_create`); the server then extracts durable memories from those posts. This per-turn posting replaces the old proactive-`memory_add` model and addresses the proactive-save unreliability tracked in [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8), but it still relies on agent behavior rather than a hook.
 
 ## Uninstalling
 

package/assets/hooks-handlers/before-submit-prompt.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+# Legacy Cursor native beforeSubmitPrompt hook. Cursor does not support context
+# injection from this event; native installs use SessionStart for context.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+load_cursor_hook_env() {
+  if [ -n "${MEKO_MCP_URL:-}" ]; then
+    return
+  fi
+  eval "$(node -e '
+    const fs = require("fs");
+    const path = require("path");
+    function shellQuote(value) {
+      return "'"'"'" + String(value).replace(/'"'"'/g, "'"'"'\\'"'"''"'"'") + "'"'"'";
+    }
+    const candidates = [
+      path.join(process.cwd(), ".cursor", "hooks.json"),
+      path.join(process.env.HOME || "", ".cursor", "hooks.json"),
+    ];
+    for (const file of candidates) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+        const env = cfg && cfg.env && typeof cfg.env === "object" ? cfg.env : {};
+        const out = [];
+        for (const key of ["MEKO_MCP_URL", "MEKO_API_KEY"]) {
+          if (typeof env[key] === "string" && env[key]) {
+            out.push(`export ${key}=${shellQuote(env[key])}`);
+          }
+        }
+        if (out.length) {
+          process.stdout.write(out.join("\n"));
+          break;
+        }
+      } catch {}
+    }
+  ')"
+}
+
+load_cursor_hook_env
+HOOK_INPUT="$(cat)"
+
+printf '%s' "$HOOK_INPUT" | MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" before-submit-prompt

package/assets/hooks-handlers/cursor-session-start.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Cursor native SessionStart hook. Cursor only documents context injection from
+# SessionStart, so this wrapper returns the Meko context synchronously.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+load_cursor_hook_env() {
+  if [ -n "${MEKO_MCP_URL:-}" ]; then
+    return
+  fi
+  eval "$(node -e '
+    const fs = require("fs");
+    const path = require("path");
+    function shellQuote(value) {
+      return "'"'"'" + String(value).replace(/'"'"'/g, "'"'"'\\'"'"''"'"'") + "'"'"'";
+    }
+    const candidates = [
+      path.join(process.cwd(), ".cursor", "hooks.json"),
+      path.join(process.env.HOME || "", ".cursor", "hooks.json"),
+    ];
+    for (const file of candidates) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+        const env = cfg && cfg.env && typeof cfg.env === "object" ? cfg.env : {};
+        const out = [];
+        for (const key of ["MEKO_MCP_URL", "MEKO_API_KEY"]) {
+          if (typeof env[key] === "string" && env[key]) {
+            out.push(`export ${key}=${shellQuote(env[key])}`);
+          }
+        }
+        if (out.length) {
+          process.stdout.write(out.join("\n"));
+          break;
+        }
+      } catch {}
+    }
+  ')"
+}
+
+load_cursor_hook_env
+MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" session-start