@yugabytedb/meko-mcp 1.2.0 → 2.0.0

package/README.md

@@ -42,7 +42,7 @@ npx @yugabytedb/meko-mcp --client cursor --local --scope project --yes
 
 **Claude Desktop install:**
 
-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, like proactive `memory_add`):
+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: `.mcpb` Desktop Extension | Option B: `create-meko-setup` installer |
 |---|---|---|
@@ -50,7 +50,7 @@ Claude Desktop has two install paths — pick based on whether you want the agen
 | 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 only — the agent is prompted to call `memory_add` proactively, but it's not as reliable as Claude Code hooks |
+| 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`.
 
@@ -81,16 +81,16 @@ 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 the `meko-mcp-tools-desktop.skill` bundle and prints its absolute path. The location depends on how you invoked the installer — under the npm package's asset root for `npx`, or under `skills/` in your clone.
+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 line).
-2. Drag `meko-mcp-tools-desktop.skill` onto the Claude Desktop window — or import it via **Settings > Extensions > Install from file**.
+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 the skill loaded: ask *"Which Meko skills do you have available?"* — the agent should mention `meko-mcp-tools-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 bundle when skill content updates; you'll need to re-drag the rebuilt `.skill` to pick up changes.
+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:**
 
@@ -145,15 +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 (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.
-  - **Auto-capture hooks**: when Codex hooks are available, the installer writes Meko lifecycle hooks to `~/.codex/hooks.json` and prunes stale Meko hook entries from deleted install paths. Memory persistence still also works via the model proactively calling `memory_search` / `memory_add` (the AGENTS.md block prompts this).
-  - **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 '/.../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` after install.
+  - **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
@@ -325,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.
 
@@ -336,11 +343,13 @@ 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 (native hooks) | Yes (hooks via `~/.codex/hooks.json`) |
-| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Yes (hooks + skill + AGENTS.md) |
+| 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 |
-| `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` | `claude_code:<repo>` per project (capture.js still classifies non-cursor hooks as the `claude_code` client; native `codex:<repo>` derivation is a follow-up); cross-project facts go to `meko_agent` |
+
+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 | 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) |
@@ -374,14 +383,14 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
   - `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` after install.
+  - 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.
+- 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.
 
@@ -561,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
 
@@ -587,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.
@@ -606,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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
-# Cursor native beforeSubmitPrompt hook. It only reads local cache populated by
-# cursor-session-start.sh; it never performs Meko network calls.
+# 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)"