@yugabytedb/meko-mcp 2.2.0 → 2.3.0

package/assets/skills/meko-mcp-tools-desktop/references/tools-troubleshooting.md

@@ -7,7 +7,7 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
 2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
 3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
-4. **Use your session's `agent_id` consistently on writes.** For Claude Desktop the default is `claude_desktop`; use `meko_agent` when writing cross-project facts. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Memory reads and `conversation_list` span all of this user's agents regardless of the value passed; `conversation_get` requires the creating agent's exact value.
+4. **Use your session's `agent_id` consistently on writes.** For Claude Desktop the default is `claude_desktop`; use `meko_agent` when writing cross-project facts. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Memory reads and `conversation_list` span all of this user's agents regardless of the value passed; the conversation calls (`conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`) require the creating agent's exact value.
 
 ---
 
@@ -26,6 +26,72 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 ---
 
+## Connection errors: `[Errno 111] Connection refused`
+
+**Affects:** any tool, intermittently. Reports show `memory_add`, `conversation_create`, `memory_search`, and `context_search` failing this way while identical calls succeed minutes later.
+
+**What it means:** the request reached no listening server, usually a server instance that was restarting or scaling. It is not a timeout and not a rejected argument.
+
+**What to do:** wait a few seconds and retry once. Retry `conversation_add_message` only with a `seed`, and never retry `conversation_create` (see the table below). If the retry also fails, report the failure. For a write, tell the user it was not saved; don't let a failed write pass silently.
+
+---
+
+## `memory_search` hangs or times out
+
+`memory_search` can stall for minutes under backend load while other tools respond. Don't raise the client timeout; that only makes the stall longer. Retry once. If it stalls again, report that the search failed, and if the user needs an answer now, try `context_search` or `memory_get_by_id` for a known id. `memory_get_all` only returns a recent window, so it can't replace a search.
+
+---
+
+## Quota errors that look like auth errors
+
+`free_tier_limit_reached` can arrive with HTTP 403, and automatic capture that hits a cap shows up as capture failing with 403. Read the error code, not the status. A quota error means the account reached a lifetime cap (see `tools-known-limitations.md`). Don't rotate keys or reinstall. Tell the user which tool hit the cap and that upgrading the plan lifts it.
+
+---
+
+## Datapack and ownership errors
+
+| Error | Meaning | What to do |
+|---|---|---|
+| `datapack_access_denied` | The `datapack_id` isn't a UUID, or it isn't owned by or shared with your account. The access check also fails closed on a transient server database error. | Retry once. If it repeats, stop; don't switch to another datapack. If the id came from a pin, ask the user to re-pin with the select-datapack skill. |
+| `datapack_id_required` | The call couldn't resolve a datapack. Conversation reads and writes (including `conversation_list`), `datapack_describe`, and `knowledgebase_delete_document` return it. | Pass the pinned `datapack_id`. Don't drop the parameter to make the call pass. |
+| `not_found` from `memory_get_by_id`, `memory_update`, or `memory_delete_by_id` | The memory doesn't exist **or** belongs to another account. The server returns the same error for both on purpose. | Check the id came from a search in this datapack. |
+| `memory_is_promoted` | The memory was promoted to shared knowledge and is read-only through MCP. | Point the user at the Cloud UI Learnings tab. |
+| `invalid_run_id` | `memory_delete_all` got a `run_id` that isn't a conversation id. | Pass the conversation UUID, or omit `run_id`. |
+| `embedder_error` from `knowledgebase_search` | The server couldn't resolve the embedding setup for this datapack's index. | Report it; retrying won't help. |
+| `invalid_force_source` from `context_search` | `force_source` isn't `auto`, `memory`, `knowledge_base`, or `conversation`. | Omit `force_source`. |
+
+---
+
+## Conversation writes fail right after `conversation_create`
+
+`conversation_add_message` has intermittently returned `not_found`, or `agent_id_mismatch` naming agent `'None'`, seconds after `conversation_create` returned that id. It shows up most with several parallel subagents writing to one conversation. Retry once with the same `seed` after a few seconds. If it still fails, don't create a new conversation for the same work: save the durable findings with `memory_add` and tell the user the transcript is incomplete.
+
+On a long conversation that has worked before, `not_found` can instead mean the trace grew too large to load. See `tools-known-limitations.md`.
+
+---
+
+## "No Meko account found for cognito identity ..." on every call
+
+Every Meko tool fails with this error while the connection itself looks fine. Two users hit it for the same reason: Claude Desktop had both the Meko URL connector (Settings > Connectors, which signs in through the browser) and the API-key install from `npx @yugabytedb/meko-mcp --client claude-desktop`, and Desktop used the connector's identity. The word "provisioned" in the error points at a backend account problem, but the fix is on the client:
+
+1. Ask the user for the full list under Settings > Connectors, not just `claude_desktop_config.json`.
+2. Have them remove the Meko URL connector and keep only the API-key install. Use the full API key from the downloaded file.
+3. Quit Claude Desktop completely (Cmd+Q) and reopen it.
+
+---
+
+## "Server disconnected" with `SyntaxError ... node:fs/promises ... 'constants'`
+
+The MCP bridge started under an old Node.js version. `npx` picked up a Node older than 20 from the user's `PATH` (often through `nvm`). Have the user make Node 20 or later the default, for example `nvm alias default 20`, then fully quit and reopen Claude Desktop. Current installer releases declare Node 20.18.1 or later as their minimum.
+
+---
+
+## You can't run a delete the user asked for
+
+Some Claude Desktop deployments refuse Meko delete tools (`memory_delete_by_id`, `memory_delete_all`, `conversation_delete`, `knowledgebase_delete_document`) by policy, even when the datapack owner asks. If that applies to you, say so plainly. Give the user the exact ids with a one-line summary of each and the tool call to run from a client that allows deletes, such as Claude Code. Don't report anything as deleted.
+
+---
+
 ## agent_id errors
 
 On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.

package/assets/skills/meko-select-datapack-desktop/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "1.2.1"
+  version: "1.2.2"
   tags: meko, datapack, selection, project, claude-desktop, desktop
 ---
 
@@ -28,7 +28,7 @@ text:        "meko_active_datapack=<uuid> name=<name> selected_at=<iso8601>"
 metadata:    { "type": "active-datapack-pin" }
 ```
 
-You discover it by calling `memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)` at the start of any turn that's about to make a Meko MCP write. If you find a pin, pass `datapack_id="<uuid>"` to every Meko call that accepts it. If you don't find one, fall back to the server default (omit the parameter).
+You discover it by calling `memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<this conversation's id>", limit=1)` (`conversation_id` is required and must be a 32-hex id; before `conversation_create`, pass a freshly generated one, never `""`) at the start of any turn that's about to make a Meko MCP write. If you find a pin, pass `datapack_id="<uuid>"` to every Meko call that accepts it. If you don't find one, fall back to the server default (omit the parameter).
 
 ## When to invoke this skill
 
@@ -85,7 +85,7 @@ the Role column. Do not hardcode "Owner", do not invent or normalize the value
 response is the source of truth — see `references/role-display-future.md` for
 the taxonomy.
 
-If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>')` to make one, or visit the Meko Cloud console."* Stop here.
+If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>', conversation_id='<conversation id>')` to make one, or visit the Meko Cloud console."* Stop here.
 
 If the response has exactly **one** entry, **auto-select it**. Print: *"Only one datapack: `<name>`. Auto-selecting. Run `meko-select-datapack-desktop` again with `clear` to unset."* Skip the table; jump to step 4 (persist) and step 5 (confirm).
 
@@ -192,7 +192,7 @@ would split capture across the old and new datapacks or fail outright.
 ## Edge cases
 
 - **Multiple pin memories somehow exist** — the user (or a buggy earlier run) created duplicates. Use the most recent (highest `selected_at`); offer to delete the others.
-- **The pinned datapack no longer exists on the server** — the next Meko MCP call will fail with a not-found error. Re-run the skill to pick a new one or `clear` the stale pin.
+- **The pinned datapack no longer exists or was unshared** — the next Meko MCP call that passes it fails with `datapack_access_denied`. Re-run the skill to pick a new one or `clear` the stale pin.
 - **memory_search times out or fails** — fall back to the server default (omit `datapack_id`) and tell the user *"Couldn't read the active-datapack pin. Using server default for this call."* Don't guess a UUID.
 - **User explicitly overrides for a single call** — pass the user's `datapack_id` for that one call. Do NOT update the pin memory.
 

package/assets/skills/meko-select-datapack-desktop/references/cookbook.md

@@ -8,7 +8,7 @@ Concrete transcripts of the four flows the skill supports on Claude Desktop.
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [empty]
 
 > datapack_list(conversation_id="<conv-id>")
@@ -23,7 +23,7 @@ One match: `prod-research`. Pinning.
              metadata='{"type":"active-datapack-pin"}')
 [returns id=mem_abc123]
 
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [verifies the row exists]
 
 Pinned datapack `prod-research` (`8b1c…f4a2`) for Claude Desktop.
@@ -41,7 +41,7 @@ datapack_id flows through automatically.
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [returns id=mem_abc123, text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
 
 > datapack_list(conversation_id="<conv-id>")
@@ -66,7 +66,7 @@ The `memory_update` is critical here — using `memory_add` again would create a
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [empty]
 
 > datapack_list(conversation_id="<conv-id>")
@@ -90,7 +90,7 @@ Pinned datapack `meko-local-setup` (`a17d…cc91`). Run this skill again with
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [returns id=mem_abc123]
 
 > memory_delete_by_id(

package/assets/skills/meko-select-datapack-desktop/references/role-display-future.md

@@ -24,13 +24,15 @@ Note that the upstream Go source (the `Datapack` struct in `api_server/internal/
 
 ## Other fields the live response includes
 
-Beyond the columns the skill renders by default, `datapack_list` returns counts that may be useful in some flows:
+`datapack_list` doesn't compute counts; its list response carries no count fields. If the user asks for counts, call `datapack_describe(datapack_id=<id>, conversation_id="<conversation id>")` and read them from that response:
 
-- `memory_count` — total memories the caller has under this datapack (per `(user_id, agent_id)` scoping).
-- `knowledge_count` — knowledge-base entries on the datapack.
-- `learnings_count` — promoted-to-shared memories on the datapack.
+- `memory_count`: all memories stored in the datapack.
+- `collective_memory_count`: memories promoted to shared knowledge.
+- `learnings_count`: memories awaiting a promotion decision.
+- `knowledge_base_file_count`: uploaded KB documents (`null` if the status endpoint is unreachable).
+- `knowledge_chunk_count`: KB chunks across all documents. `knowledge_count` is a deprecated alias.
 
-These aren't in the spec column set. Don't add them silently. If the user asks for counts, render them on request — and read the numbers from the live response, never invent them.
+Don't add counts to the table silently, and never invent the numbers.
 
 ## Sharing UI vs API state
 

package/assets/skills/meko-select-datapack-desktop/references/troubleshooting.md

@@ -18,12 +18,12 @@ You (or an earlier run) created duplicates by using `memory_add` instead of `mem
 
 The cookbook's Flow 2 demonstrates the correct switch path.
 
-## Symptom: A pinned datapack returns "not found" when used
+## Symptom: A pinned datapack returns `datapack_access_denied` when used
 
-The pin became stale — the datapack was deleted in another client. Tell the user:
+The pin became stale: the datapack was deleted, or its share to you was revoked, in another client. The server checks ownership and shares on every call that passes a `datapack_id`, so the call fails with `datapack_access_denied` (older servers returned a not-found error). The check also fails closed on a transient server database error, so retry the call once before treating the pin as stale. Tell the user:
 
 ```
-The pinned datapack `<name>` (`<id>`) no longer exists on the server.
+The pinned datapack `<name>` (`<id>`) no longer exists or is no longer shared with you.
 Run `meko-select-datapack-desktop` to pick a fresh one, or `clear` to unpin.
 ```
 
@@ -40,7 +40,7 @@ The user has zero datapacks. Print:
 ```
 You don't have any datapacks yet. Create one with:
 
-  datapack_create(name="<your-datapack-name>")
+  datapack_create(name="<your-datapack-name>", conversation_id="<conversation id>")
 
 Or visit the Meko Cloud console (Datapacks → New datapack).
 ```

package/bin/create-meko-setup.mjs

@@ -19,6 +19,7 @@ import { parseClientList } from '../lib/clients/aliases.mjs';
 import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
 import { checkLatest } from '../lib/version-check.mjs';
 import { runCaptureStatus } from '../lib/capture-status.mjs';
+import { captureCleanupArgs, runCaptureCleanup } from '../lib/capture-cleanup.mjs';
 
 // ---------------------------------------------------------------------------
 // Flag definitions
@@ -48,6 +49,11 @@ const options = {
   // --- Capture health (Capture V2 Workstream D) ---
   'capture-status':   { type: 'boolean', default: false },
   json:               { type: 'boolean', default: false },
+  'capture-cleanup':  { type: 'string' },
+  session:            { type: 'string', multiple: true },
+  all:                { type: 'boolean', default: false },
+  'max-exchanges':    { type: 'string' },
+  'pace-ms':          { type: 'string' },
 
   // --- Migrate subcommand ---
   migrate:            { type: 'boolean', default: false },
@@ -75,11 +81,11 @@ function readVersion() {
   return pkg.version;
 }
 
-const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex', 'kiro'];
+const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex', 'kiro', 'opencode'];
 
 function printHelp() {
   const text = `
-Meko Setup for Claude Code, Claude Desktop, Cursor, Codex, and Kiro
+Meko Setup for Claude Code, Claude Desktop, Cursor, Codex, Kiro, and OpenCode
 
 Install and configure Meko MCP Server in one command.
 
@@ -108,11 +114,13 @@ Examples:
   # Install for Kiro (IDE and kiro-cli share the same config):
   create-meko-setup --client kiro --yes
 
+  create-meko-setup --client opencode --scope user --yes
+
   # Local Meko (docker-compose stack, Claude Code):
   create-meko-setup --local --yes
 
 Options:
-  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex, kiro.
+  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex, kiro, opencode.
                         "claude" is accepted as an alias for claude-code;
                         "kiro-cli" and "kiro-ide" for kiro.
                         Comma-separated, or "all" to target every supported client (default: claude-code)
@@ -153,7 +161,27 @@ Capture health (durable outbox / recovery):
                         Exit 0 = healthy|catching_up, 2 = degraded_retrying,
                         3 = blocked_action_required.
   --json                With --capture-status, print machine-readable JSON
-                        matching the capture-health cache shape.
+                        matching the capture-health cache shape. Also
+                        accepted by --capture-cleanup.
+  --capture-cleanup <action>
+                        Clean up stuck capture on this machine:
+                          status   list sessions with unsent work and the
+                                   background capture processes (read-only)
+                          stop     stop SessionEnd workers and in-flight
+                                   drains, and park all unsent work so no
+                                   hook retries it (nothing is deleted)
+                          resume   unpark and hand back to the hooks
+                          drain    send now, one session at a time; stops
+                                   and re-parks at the first failure
+                          discard  skip a session's unsent exchanges for
+                                   good (needs --yes)
+                          repair   clear stale failure fields and leftover
+                                   PID, lease, and job files
+                        Options: --session <id> or a bare session ID
+                        (repeatable, prefix ok),
+                        --all, --dry-run, --json, --yes,
+                        --max-exchanges N (drain, default 200),
+                        --pace-ms N (drain, default 1000).
 
 Migrate existing conversations and memories into Meko:
   --migrate             Start a detached migration of existing Claude Code
@@ -272,7 +300,22 @@ function parseRate(raw) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const { values: flags } = parseArgs({ options, strict: true });
+  const { values: flags, positionals } = parseArgs({
+    options,
+    strict: true,
+    allowPositionals: true,
+  });
+  // Only --capture-cleanup takes bare arguments: session IDs, so
+  // `--capture-cleanup drain c0acdeb2` works like `--session c0acdeb2`.
+  if (positionals.length > 0) {
+    if (flags['capture-cleanup'] === undefined) {
+      error(
+        `Unexpected argument '${positionals[0]}'. This command does not take positional arguments`,
+      );
+      process.exit(1);
+    }
+    flags.session = [...(flags.session || []), ...positionals];
+  }
   const projectRoot = process.cwd();
 
   // --help
@@ -297,8 +340,17 @@ async function main() {
     if (out.stderr) process.stderr.write(out.stderr);
     process.exit(out.code);
   }
+  // --capture-cleanup <action>: inspect, stop, park, drain, or discard
+  // stuck capture sessions. Exit codes: 0 done, 1 error, 2 partly done.
+  if (flags['capture-cleanup'] !== undefined) {
+    const out = runCaptureCleanup(
+      captureCleanupArgs(flags['capture-cleanup'], flags),
+    );
+    if (out.error) error(out.error);
+    process.exit(out.code);
+  }
   if (flags.json) {
-    error('--json requires --capture-status');
+    error('--json requires --capture-status or --capture-cleanup');
     process.exit(1);
   }
 
@@ -478,6 +530,7 @@ async function main() {
         cursor: 'Cursor',
         codex: 'OpenAI Codex (CLI + App)',
         kiro: 'Kiro (IDE + kiro-cli)',
+        opencode: 'OpenCode CLI/TUI',
       }[id];
       return {
         label: id,
@@ -760,15 +813,23 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot, datapack }
       dryRun: true,
       datapack: datapack ?? null,
     });
+    if (dry && dry.ok === false) {
+      dim(`Skipped migration offer: ${dry.message || "dry run failed"}`);
+      return;
+    }
     const s = dry?.message?.match(/Claude Code sessions: *(\d+)/);
     const c = dry?.message?.match(/Cursor sessions: *(\d+)/);
+    const x = dry?.message?.match(/Codex sessions: *(\d+)/);
+    const o = dry?.message?.match(/OpenCode sessions: *(\d+)/);
     const m = dry?.message?.match(/Memory items \(MD\): *(\d+)/);
     const counts = {
       claude: s ? Number(s[1]) : 0,
       cursor: c ? Number(c[1]) : 0,
+      codex: x ? Number(x[1]) : 0,
+      opencode: o ? Number(o[1]) : 0,
       memory: m ? Number(m[1]) : 0,
     };
-    const total = counts.claude + counts.cursor + counts.memory;
+    const total = counts.claude + counts.cursor + counts.codex + counts.opencode + counts.memory;
     if (total === 0) return;
 
     console.log('');
@@ -776,6 +837,8 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot, datapack }
       `Found existing data to migrate: ` +
       `${counts.claude} Claude Code sessions, ` +
       `${counts.cursor} Cursor sessions, ` +
+      `${counts.codex} Codex sessions, ` +
+      `${counts.opencode} OpenCode sessions, ` +
       `${counts.memory} memory items.`,
     );
     const proceed = await askYesNo(

package/lib/capture-cleanup.mjs

@@ -0,0 +1,63 @@
+/**
+ * capture-cleanup.mjs: installer helper that invokes capture-cleanup-cli.js.
+ *
+ * Resolves the CLI the same way capture-status.mjs does, so a published
+ * package runs the bundled copy next to the capture.js it drains with.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { resolveCaptureStatusCli } from "./capture-status.mjs";
+
+/**
+ * Absolute path to capture-cleanup-cli.js under the active asset root.
+ * @returns {string}
+ */
+export function resolveCaptureCleanupCli() {
+  return join(dirname(resolveCaptureStatusCli()), "capture-cleanup-cli.js");
+}
+
+/**
+ * Build the CLI argument list from parsed installer flags.
+ *
+ * @param {string} action
+ * @param {{ session?: string[], all?: boolean, 'dry-run'?: boolean,
+ *   json?: boolean, yes?: boolean, 'max-exchanges'?: string,
+ *   'pace-ms'?: string }} flags
+ * @returns {string[]}
+ */
+export function captureCleanupArgs(action, flags = {}) {
+  const args = [action];
+  for (const id of flags.session || []) args.push("--session", id);
+  if (flags.all) args.push("--all");
+  if (flags["dry-run"]) args.push("--dry-run");
+  if (flags.json) args.push("--json");
+  if (flags.yes) args.push("--yes");
+  if (flags["max-exchanges"] != null) args.push("--max-exchanges", String(flags["max-exchanges"]));
+  if (flags["pace-ms"] != null) args.push("--pace-ms", String(flags["pace-ms"]));
+  return args;
+}
+
+/**
+ * Run the capture-cleanup CLI with inherited stdio (drain prints progress)
+ * and return its exit code.
+ *
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ code: number, cliPath: string, error?: string }}
+ */
+export function runCaptureCleanup(args, opts = {}) {
+  const cliPath = resolveCaptureCleanupCli();
+  if (!existsSync(cliPath)) {
+    return { code: 1, cliPath, error: `capture-cleanup CLI not found at ${cliPath}` };
+  }
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    stdio: "inherit",
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+  });
+  const code =
+    typeof result.status === "number" && result.status >= 0 ? result.status : 1;
+  return { code, cliPath };
+}

package/lib/clients/claude-code.mjs

@@ -65,6 +65,7 @@ const MEKO_MARKETPLACE_NAME = "meko-agent-skills";
 const MEKO_ALWAYS_AVAILABLE_TOOLS = [
   "mcp__meko__memory_add",
   "mcp__meko__memory_search",
+  "mcp__meko__context_search",
   "mcp__meko__memory_get_all",
   "mcp__meko__memory_get_by_id",
   "mcp__meko__memory_update",

package/lib/clients/codex.mjs

@@ -254,7 +254,7 @@ export function createCodexAdapter(options = {}) {
       const next = removeCodexConfigBlock(raw, name);
       if (next !== raw) writeWithBackup(path, next);
     },
-    async registerServer({ name, url, apiKey, dryRun, verbose, log, scope, yes }) {
+    async registerServer({ name, url, apiKey, dryRun, verbose, log, scope }) {
       const path = settingsPathFor(scope, log);
       const useApiKey = apiKey ? "MEKO_API_KEY" : null;
       const cliCmd = buildCliRegisterCommand(name, url, useApiKey);
@@ -353,35 +353,6 @@ export function createCodexAdapter(options = {}) {
       // Cloud auth UX: env-var-only model. The key is never written to
       // config.toml; the user's runtime env supplies it. Print actionable
       // instructions and (when interactive) offer to wire things up.
-      if (apiKey) {
-        const platform = surfaces.app?.platform ?? process.platform;
-        const hasApp = Boolean(surfaces.app);
-        const shellRc = detectShellRc();
-        printCloudAuthInstructions({ shellRc, hasApp, platform, log });
-        if (!yes) {
-          await maybeOfferRcAppend({
-            apiKey,
-            shellRc,
-            promptUser,
-            log,
-          });
-          if (hasApp && platform === "darwin") {
-            await maybeOfferLaunchctlSetenv({
-              apiKey,
-              promptUser,
-              runCommand,
-              log,
-            });
-          }
-        } else if (hasApp && platform === "darwin") {
-          setLaunchctlMekoApiKey({
-            apiKey,
-            runCommand,
-            log,
-          });
-        }
-      }
-
       if (surfaces.app) {
         log.dim?.("  Restart Codex.app to attach the new MCP server.");
       }
@@ -427,6 +398,61 @@ export function createCodexAdapter(options = {}) {
         );
       }
     },
+    /**
+     * Cloud auth UX: env-var-only model. The key is never written to
+     * config.toml, so the user's runtime env must supply it. This is a
+     * separate adapter step (not part of registerServer) because an
+     * interactive reinstall where the user declines the overwrite prompt
+     * skips registration entirely - and the launchd env would otherwise
+     * never be refreshed after a key rotation. See
+     * yugabyte/meko-mcp-server#337.
+     */
+    async syncCloudAuthEnvironment({ apiKey, dryRun, log, yes }) {
+      if (!apiKey || dryRun) return;
+      const platform = surfaces.app?.platform ?? process.platform;
+      const hasApp = Boolean(surfaces.app);
+      const shellRc = detectShellRc();
+      printCloudAuthInstructions({ shellRc, hasApp, platform, log });
+      if (!yes) {
+        // Offer launchctl BEFORE rc-append, and isolate the rc-append
+        // failure mode. `maybeOfferRcAppend` throws when the shell rc is
+        // fish and the API key contains a `'` (fish single-quoting can't
+        // escape it). If that threw first, the launchctl offer - the
+        // yugabyte/meko-mcp-server#337 fix - would never run.
+        //
+        // macOS: offer launchctl setenv regardless of whether Codex.app
+        // is present. Spotlight- and Alfred-launched Codex CLI reads the
+        // launchd env too. Login-session inheritance means every
+        // GUI-launched process in this session then sees MEKO_API_KEY
+        // (visible via `launchctl getenv`, `ps e` on descendants,
+        // crash reports); the prompt copy calls that out so the choice
+        // is informed.
+        if (platform === "darwin") {
+          await maybeOfferLaunchctlSetenv({
+            apiKey,
+            promptUser,
+            runCommand,
+            log,
+          });
+        }
+        try {
+          await maybeOfferRcAppend({
+            apiKey,
+            shellRc,
+            promptUser,
+            log,
+          });
+        } catch (err) {
+          log?.warn?.(`  Skipping shell rc append: ${err.message}`);
+        }
+      } else if (platform === "darwin") {
+        setLaunchctlMekoApiKey({
+          apiKey,
+          runCommand,
+          log,
+        });
+      }
+    },
     installSkills({ dryRun, log, scope, name }) {
       void scope; // Codex skills are user-scope only.
       const serverName = name ?? "meko";
@@ -1317,7 +1343,7 @@ function renderAgentsMdBlock(version, name) {
     `${AGENTS_MD_START} v${version}`,
     "## Meko memory (auto-managed by meko installer)",
     "",
-    `You have a persistent memory store via the \`${name}\` MCP server. At the start of every conversation, call \`${toolPrefix}memory_search\` for relevant personal context; use \`${toolPrefix}knowledgebase_search\` when the request concerns shared datapack knowledge. When the user shares facts, preferences, or decisions worth remembering, call \`${toolPrefix}memory_add\`. Skill details: ~/.agents/skills/meko-mcp-tools/SKILL.md`,
+    `You have a persistent memory store via the \`${name}\` MCP server. At the start of every conversation, call \`${toolPrefix}context_search\` for relevant context: it returns personal memory, shared datapack knowledge, and past conversations in one call. Use \`${toolPrefix}memory_search\` or \`${toolPrefix}knowledgebase_search\` when you need a single source. When the user shares facts, preferences, or decisions worth remembering, call \`${toolPrefix}memory_add\`. Skill details: ~/.agents/skills/meko-mcp-tools/SKILL.md`,
     "",
     "Cloud auth requires `MEKO_API_KEY` exported in your shell (or, for the desktop app on macOS, set via `launchctl setenv`).",
     AGENTS_MD_END,
@@ -1350,9 +1376,16 @@ function printCloudAuthInstructions({ shellRc, hasApp, platform, log }) {
     log.dim?.(`    fish:      set -gx MEKO_API_KEY '<your-meko-api-key>'`);
   }
   log.dim?.(`  Then open a new terminal (or run "exec $SHELL" / "exec fish").`);
-  if (hasApp && platform === "darwin") {
+  if (platform === "darwin") {
+    // Explain launchd for both Codex.app and CLI-only macOS installs.
+    // GUI-launched Codex (Finder, Dock, Spotlight, Alfred, `open -a`) reads
+    // launchd's env, not the shell rc, so a fresh install or a rotated key
+    // needs `launchctl setenv` to propagate. Shell-launched CLI still
+    // reads its shell rc.
     log.warn?.(
-      "macOS Codex.app launched from Finder/Dock does NOT inherit shell rc — set it via launchctl too:",
+      hasApp
+        ? "macOS Codex.app launched from Finder/Dock does NOT inherit shell rc - set it via launchctl too:"
+        : "macOS Codex CLI launched from Spotlight/Alfred/`open` does NOT inherit shell rc - set it via launchctl too:",
     );
     log.dim?.(
       `    launchctl setenv MEKO_API_KEY '<your-meko-api-key>'  # current login session`,
@@ -1360,6 +1393,9 @@ function printCloudAuthInstructions({ shellRc, hasApp, platform, log }) {
     log.dim?.(
       "    (For permanence across reboots, add a ~/Library/LaunchAgents/com.meko.env.plist.)",
     );
+    log.warn?.(
+      "  launchctl setenv writes to the login session's env, which every subsequently GUI-launched process inherits (visible via `launchctl getenv`, `ps e` on descendants, and crash reports).",
+    );
   }
 }
 
@@ -1443,9 +1479,15 @@ export async function maybeOfferLaunchctlSetenv({
   runCommand,
   log,
 }) {
+  // Default to Yes: this is the setting that makes GUI-launched Codex on
+  // macOS see the fresh key. Users who habitually hit Enter at the prompt
+  // otherwise leave launchd empty and Codex authenticates with whatever key
+  // it had at first start. See yugabyte/meko-mcp-server#337. The prompt
+  // names both Codex.app and Spotlight-launched CLI so a user without the
+  // desktop app understands why the offer applies to them.
   const accept = await promptUser(
-    "Run `launchctl setenv MEKO_API_KEY ...` so Codex.app sees the key now?",
-    false,
+    "Run `launchctl setenv MEKO_API_KEY ...` so GUI-launched Codex (App, Spotlight, Alfred, `open`) sees the key now? (writes the key into the login session env, inherited by every subsequently GUI-launched process)",
+    true,
   );
   if (!accept) return { set: false };
   return setLaunchctlMekoApiKey({ apiKey, runCommand, log });
@@ -1463,6 +1505,9 @@ export function setLaunchctlMekoApiKey({ apiKey, runCommand, log }) {
   try {
     runCommand(`launchctl setenv MEKO_API_KEY ${shellQuote(apiKey)}`);
     log?.dim?.("  Set MEKO_API_KEY via launchctl (current login session).");
+    log?.warn?.(
+      "  Fully quit any running Codex (Cmd-Q, or `pkill -x codex` for the CLI) and relaunch — a process already running will keep its previous MEKO_API_KEY.",
+    );
     return { set: true };
   } catch (err) {
     log?.warn?.("  launchctl setenv failed; run it manually if Codex.app needs cloud auth.");

package/lib/clients/common.mjs

@@ -88,6 +88,13 @@ export function resolveHooksRoot() {
   return join(getAssetRoot(), "hooks-handlers");
 }
 
+/**
+ * @returns {string} absolute path to the installer-owned OpenCode plugin source
+ */
+export function resolveOpenCodePluginSource() {
+  return join(getAssetRoot(), "opencode-plugin", "meko.js");
+}
+
 /**
  * @returns {string} absolute path to the statusline script source.
  *   Lives under skills/scripts/ in source, mirrored under assets/scripts/ in

package/lib/clients/index.mjs

@@ -3,6 +3,7 @@ import { createClaudeDesktopAdapter } from "./claude-desktop.mjs";
 import { createCodexAdapter } from "./codex.mjs";
 import { createCursorAdapter } from "./cursor.mjs";
 import { createKiroAdapter } from "./kiro.mjs";
+import { createOpenCodeAdapter } from "./opencode.mjs";
 
 /**
  * @returns {Record<string, object>}
@@ -14,5 +15,6 @@ export function getClientAdapters() {
     cursor: createCursorAdapter(),
     codex: createCodexAdapter(),
     kiro: createKiroAdapter(),
+    opencode: createOpenCodeAdapter(),
   };
 }