@yugabytedb/meko-mcp 1.1.0 → 2.0.0

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

@@ -0,0 +1,105 @@
+# Complete Tool Catalog and Decision Tree
+
+**22 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
+
+## Quick health check before using tools
+
+Before starting a session, verify that the Meko MCP tools are working:
+
+1. `memory_search(scope="read", query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
+2. `datapack_list(scope="read")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
+
+## Decision tree: which tool do I need?
+
+```
+User wants to...
+├── Search a knowledge base? ---------------> knowledgebase_search (read)
+├── Add documents to a knowledge base? -----> point user at Meko UI: Datapack → Actions → Add Knowledge
+│                                              (no MCP tool — Cloud uses UI ingestion only)
+├── Store or recall information?
+│   ├── Store a fact/preference/entity? -----------> memory_add (write)
+│   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
+│   ├── Search past knowledge? --------------------> memory_search (read)
+│   └── Retrieve a past conversation? -------------> conversation_get (read)
+├── Persist or retrieve a file?
+│   ├── Upload a generated file (report, CSV, PDF)? -> artifact_put (write)
+│   └── Retrieve a previously uploaded file? -------> artifact_get (read)
+└── Manage datapacks?
+    └── CRUD datapack? --------------------> datapack_create/list/describe/update/delete
+```
+
+Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typically in the Meko control-plane UI — and is not exposed as tools here.
+
+## Knowledge Base Tools (1)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `knowledgebase_search(scope, query, agent_id, conversation_id, datapack_id, limit=10)` | read | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
+
+## Memory Tools (8)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `memory_add(scope, text, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | write | Store fact/preference/entity as long-term memory |
+| `memory_search(scope, query, agent_id, conversation_id="", user_id=None, limit=10, datapack_id=None)` | read | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
+| `memory_get_by_id(scope, memory_id, agent_id, conversation_id, datapack_id=None)` | read | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
+| `memory_get_all(scope, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | read | List all memories for agent |
+| `memory_update(scope, memory_id, text, agent_id, conversation_id, datapack_id=None)` | write | Overwrite memory text |
+| `memory_delete_by_id(scope, memory_id, agent_id, conversation_id, datapack_id=None)` | write | Delete a single memory |
+| `memory_delete_all(scope, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | admin | Delete all memories for agent (destructive) |
+| `flush_pending_memory_candidates(scope, agent_id)` | read | **Deprecated.** Superseded by automatic extraction from posted turns — post substantive turns with `conversation_add_message` and the server extracts memories from them. Now returns a `deprecated` payload pointing at `conversation_add_message`; kept one release for backward compatibility. |
+
+## Conversation Tools (6)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `conversation_create(scope, agent_id, user_id=None, app_id=None, run_id=None, title=None, metadata=None, session_id="")` | write | Create conversation container (Langfuse session) |
+| `conversation_add_message(scope, conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None, trace_id="")` | write | Add a message turn (Langfuse trace) |
+| `conversation_get(scope, conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | read | Retrieve conversation, optionally with messages |
+| `conversation_list(scope, agent_id, conversation_id="", user_id=None, limit=20, offset=0)` | read | List conversations for agent. `conversation_id` optional (omit for browse). |
+| `conversation_update(scope, conversation_id, agent_id, title=None, metadata=None)` | write | Update title or metadata |
+| `conversation_delete(scope, conversation_id, agent_id)` | admin | Delete entire conversation (destructive) |
+
+## Datapack Management Tools (5)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `datapack_create(scope, name)` | write | Create new datapack |
+| `datapack_list(scope)` | read | List all datapacks |
+| `datapack_describe(scope, datapack_id, include_status=False)` | read | Describe datapack by UUID |
+| `datapack_update(scope, datapack_id, connection_string)` | write | Update connection string |
+| `datapack_delete(scope, datapack_id)` | admin | Delete datapack by UUID (irreversible) |
+
+## Artifact Tools (2)
+
+Content-addressed blob store scoped to a datapack. Files < 1 MB go inline in the DB; files ≥ 1 MB go to S3. Identity is SHA-256 — uploading the same bytes twice returns the same `content_hash`. Free-tier artifacts expire after 30 days of inactivity; pro-tier artifacts have no TTL.
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `artifact_put(scope, filename, content_base64, content_type, conversation_id, datapack_id=None, agent_id=None)` | write | Upload a file to the datapack. Returns `{artifact_id, content_hash, filename, size_bytes, stored_in}`. Max 5 MiB (configurable via `MEKO_MAX_ARTIFACT_UPLOAD_BYTES`). |
+| `artifact_get(scope, content_hash, conversation_id, datapack_id=None, agent_id=None)` | read | Retrieve a file by SHA-256 hash. Small files return `content_base64` inline; large files (S3) are written to `~/.meko/artifacts/<hash>/<filename>` and `local_path` is returned. |
+
+## Observability Tools (1)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `track_token_usage(scope, conversation_id, name, input_tokens=0, output_tokens=0, total_tokens=None, model=None, message_id=None, datapack_id=None)` | write | Record an LLM-cost GENERATION observation on the conversation's trace. Primarily called by first-party Meko services (e.g. inference_gateway) that know their LLM's exact token counts. Most end-agents (Cursor, Claude Desktop) don't have those counts at the MCP call layer, so this tool is rarely useful for third-party agents. |
+
+## Platform capabilities NOT exposed via MCP
+
+Some things the Meko platform can do are not wired into the MCP tool surface today. If a user asks about them, do not invent MCP tool calls — point them at the appropriate control plane instead. Agents attempting these as MCP tools will hit "tool not found".
+
+| Capability | Where it lives | How to reach it |
+|---|---|---|
+| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
+| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
+| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:datapack_id/langfuse/project-keys` |
+| Account / billing / tier management | Meko UI only | Not available via MCP or public REST |
+
+The MCP-exposed `datapack_create` / `datapack_list` / `datapack_describe` / `datapack_update` / `datapack_delete` tools above are a deliberate subset — the common CRUD that an agent reasonably needs mid-conversation. Anything involving agent or KB lifecycle is control-plane territory.
+
+For knowledge-base content on Cloud, the canonical path is **UI upload**: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` queries the resulting index from MCP.
+
+## Common Parameter Patterns
+
+Every tool accepts `scope` as the first parameter. Memory and KB tools accept optional `datapack_id` to target a specific datapack. Memory and conversation tools require `agent_id` for namespace isolation (see `tools-agent-id-conventions.md`).

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

@@ -0,0 +1,70 @@
+# Knowledge Base / RAG workflow
+
+`knowledgebase_search` is the only KB tool exposed via MCP. Index
+creation and ingestion happen out of band — through the **Meko UI**
+(`cloud.mekodata.ai`).
+
+## Decision table
+
+| Situation | Use this | Why |
+|---|---|---|
+| Search an existing KB | `knowledgebase_search` | The one KB tool exposed via MCP |
+| Add documents to a KB | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). No MCP equivalent |
+| Anything else (list / delete / rename / re-index) | **UI** | No MCP tools for KB lifecycle |
+
+## knowledgebase_search — the one you'll actually call
+
+```
+knowledgebase_search(
+    scope="read",
+    query="natural-language question",
+    agent_id="claude_desktop",
+    conversation_id="<uuid from conversation_create>",
+    datapack_id="<datapack UUID — REQUIRED on this tool>",
+    limit=10)
+```
+
+Required: `scope`, `query`, `agent_id`, `conversation_id`, `datapack_id`.
+Unlike the memory tools, `datapack_id` has no default here — you must
+pass it explicitly. `agent_id` is **ignored for filtering** on this
+tool (KB results are team-shared on the datapack), but you still pass
+it — your session's value is fine.
+
+## Response shape
+
+Populated KB:
+
+```
+{
+  "results": [
+    {
+      "content": "<chunk text>",
+      "similarity": 0.87,
+      "source_uri": "<original source URI>",
+      "document_name": "<file key>",
+      ...
+    },
+    ...
+  ],
+  "count": <int>
+}
+```
+
+Empty or nonexistent KB: `{"results": [], "count": 0}` (no error,
+just an empty array).
+
+## UI ingestion — what the user sees
+
+From `cloud.mekodata.ai`:
+
+1. Open a datapack (`/datapacks/<name>`).
+2. Click **Actions** → **Add Knowledge**.
+3. Drag-and-drop or browse for files. Supported: PDF, TXT, MD, JSON,
+   MP4. Per-file limit 5 MB. Up to 10 files per batch.
+4. The UI handles upload, storage, and index build. The user does not
+   pick a bucket or provide credentials.
+5. Search results from `knowledgebase_search` become available once
+   indexing completes.
+
+If a user asks you "how do I add a document to my knowledge base?",
+point them at this flow.

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

@@ -0,0 +1,71 @@
+# Scope Permission Hierarchy and Per-Tool Requirements
+
+**WRONG:** `memory_add(scope="read", ...)` → PermissionError: requires 'write' or higher.
+**WRONG:** `memory_delete_all(scope="write", ...)` → PermissionError: requires 'admin'.
+
+## Scope Hierarchy
+
+```
+admin  (level 2)  -- can do everything
+  ↓
+write  (level 1)  -- can read + write, not admin-only
+  ↓
+read   (level 0)  -- can only read
+```
+
+Higher scopes include lower scopes. An unrecognized scope string always fails.
+
+## Per-Tool Requirements
+
+### read scope (9 tools)
+
+| Tool | Group |
+|------|-------|
+| `knowledgebase_search` | RAG |
+| `memory_search` | Memory |
+| `memory_get_by_id` | Memory |
+| `memory_get_all` | Memory |
+| `flush_pending_memory_candidates` | Memory |
+| `conversation_get` | Conversation |
+| `conversation_list` | Conversation |
+| `datapack_list` | Datapack |
+| `datapack_describe` | Datapack |
+
+### write scope (9 tools)
+
+| Tool | Group |
+|------|-------|
+| `memory_add` | Memory |
+| `memory_update` | Memory |
+| `memory_delete_by_id` | Memory |
+| `conversation_create` | Conversation |
+| `conversation_add_message` | Conversation |
+| `conversation_update` | Conversation |
+| `datapack_create` | Datapack |
+| `datapack_update` | Datapack |
+| `track_token_usage` | Observability |
+
+### admin scope (3 tools — destructive, irreversible)
+
+| Tool | Group |
+|------|-------|
+| `memory_delete_all` | Memory |
+| `conversation_delete` | Conversation |
+| `datapack_delete` | Datapack |
+
+Agent and knowledge-base lifecycle tools are not MCP-exposed — see "Platform capabilities NOT exposed via MCP" in `tools-overview.md`.
+
+## Best Practices
+
+1. **Use the minimum scope needed.** `scope="read"` for reads documents intent and prevents accidental writes.
+2. **The scope is a parameter, not an auth token.** When OAuth is enabled, the actual permission check happens against the OAuth token's claims. Both `scope` parameter and OAuth permissions must be satisfied.
+
+## Common Mistakes
+
+**WRONG:** `scope="all"` — there is no "all" scope. Valid values are exactly: `"read"`, `"write"`, `"admin"`. Nothing else.
+
+Other invalid values that will fail: `"readwrite"`, `"rw"`, `"full"`, `"any"`.
+
+The error `Insufficient scope: 'all'. This tool requires 'read' or higher.` means the scope string was not recognized as a valid value. Always use one of the three valid strings.
+
+**Default choice:** Start with `scope="read"` unless you specifically need to write or delete.

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

@@ -0,0 +1,75 @@
+# Troubleshooting — Error Recovery and Retry Strategies
+
+These patterns are extracted from real agent sessions. Follow them to avoid wasting tool calls and context window on repeated failures.
+
+## General rules
+
+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.** For Claude Desktop the default is `claude_desktop`; for cross-project common facts use `meko_agent`. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Use `agent_id="meko_agent"` deliberately on `memory_search`/`memory_get_all` only when you want the common bucket — empty string also resolves to `meko_agent`, not a cross-agent fan-out. Don't switch between forms mid-session.
+
+---
+
+## Connection errors: "connection already closed"
+
+**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently.
+
+**Why it happens:** The Python memory subsystem uses a connection cache that doesn't recover from dropped connections (unlike the Go API server which has retry logic with 5 retries and 3-second delays).
+
+**What to do:**
+
+1. Retry the same call **once**.
+2. If it fails again, the memory subsystem is unhealthy for this session — stop trying memory calls and tell the user. Do not waste tokens re-sending the same payload.
+
+**Anti-pattern from real sessions:** Agent called `memory_add` with 500+ tokens of text, got "connection already closed", retried the identical call 3 more times (each 500+ tokens). Wasted ~2000 tokens on guaranteed failures.
+
+---
+
+## Scope parameter errors
+
+**Error:** `Insufficient scope: 'all'. This tool requires 'read' or higher.`
+
+The only valid scope values are: `"read"`, `"write"`, `"admin"`.
+
+- Use `"read"` for all read operations (default choice)
+- Use `"write"` for inserts, updates, creates, memory writes
+- Use `"admin"` only for destructive deletes
+
+**Never use:** `"all"`, `"readwrite"`, `"rw"`, or any other value.
+
+---
+
+## 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.
+
+`agent_id` is **not a constant**. Cloud Meko supports multiple agents on one datapack, and the Cloud UI renders every `agent_id` as a badge on each row regardless of value. The canonical shape for new writes is `<client>:<repo-basename>` for coding agents (e.g. `claude_code:meko-mcp-server`), a bare client name for non-coding clients like Claude Desktop (`claude_desktop`), or `meko_agent` for the cross-project common bucket — see `tools-agent-id-conventions.md`.
+
+### "My writes are landing in `meko_agent` instead of my agent's bucket"
+
+If you call `memory_add` with empty / None / whitespace `agent_id`, the server does NOT reject the write. It silently resolves the value to `meko_agent` (the cross-project common bucket) and the row lands there. The Cloud UI then shows a `meko_agent` badge instead of your client's badge.
+
+Fix: always pass a concrete non-empty `agent_id`. For Claude Desktop use `agent_id="claude_desktop"`; for hook-driven clients (Claude Code, Cursor) fetch the value the SessionStart hook injected into `additionalContext` and pass it verbatim. Use `agent_id="meko_agent"` only when you genuinely want a fact in the cross-project pool (user identity, global preferences).
+
+### "My reads return fewer results than I expected"
+
+`memory_search` and `memory_get_all` filter strictly on your passed `agent_id`. A memory written by `claude-code:<slug-A>` is invisible to a search with `agent_id="cursor:<slug-B>"`. If you need a broader view, call repeatedly across the agent_ids you want to cover, or point the user at the UI's Memory Summary page (which shows every row regardless of agent_id).
+
+### "I'm seeing rows tagged with legacy agent_id values"
+
+Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, or similar ad-hoc values. All remain readable. New writes should follow the canonical `<client>:<project-slug>` form; don't try to retag old rows.
+
+---
+
+## Safe-to-retry vs not
+
+| Tool | Safe to retry? | Why |
+|------|---------------|-----|
+| All `read` scope tools | Yes | Reads are idempotent |
+| `memory_add` | Yes (once) | Mem0 has dedup logic |
+| `memory_update` | Yes (once) | Overwrites same ID |
+| `memory_delete_by_id` | Yes | Deleting already-deleted is a no-op |
+| `conversation_create` | **No** | Creates duplicate conversations |
+| `conversation_add_message` with `seed` | Yes | Seed-based dedup prevents duplicates |
+| `conversation_add_message` without `seed` | **No** | Creates duplicate messages |

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

@@ -0,0 +1,198 @@
+---
+name: meko-select-datapack-desktop
+description: >-
+  Lists the user's Meko datapacks, shows authorization, supports search and
+  pagination, and pins one as the active datapack on Claude Desktop. Triggers
+  when the user says things like "switch datapack", "use datapack <name>",
+  "list my datapacks", "which datapack am I on", "pin <name>", or any request
+  to change or inspect the active datapack. Persistence is via memory_add
+  (Desktop has no SessionStart hook), so the pin survives across sessions
+  until the user clears it.
+license: MIT
+metadata:
+  author: Meko
+  version: "1.1.0"
+  tags: meko, datapack, selection, project, claude-desktop, desktop
+---
+
+# meko-select-datapack-desktop — Pin a datapack for Claude Desktop
+
+Claude Desktop has no SessionStart hook, so the Claude Code variant's sidecar/hook design doesn't apply here. Instead, the pin is stored as a **memory** with a structured tag, scoped to `agent_id="claude_desktop"` (Desktop's project bucket), and you re-read it on every Desktop turn before issuing Meko MCP tool calls. The pin outlives a single Desktop conversation — it sticks until the user explicitly clears it. Same project-scoped semantic as the Claude Code variant; different mechanism.
+
+## How persistence works (Desktop)
+
+A single memory under `agent_id="claude_desktop"` carries the pin:
+
+```
+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).
+
+## When to invoke this skill
+
+Trigger immediately on any of these signals:
+
+- User says "switch datapack", "change datapack", "use datapack X", "select datapack", "pick a datapack".
+- User says "list my datapacks", "what datapacks do I have", "show me my datapacks".
+- User says "which datapack am I on", "which datapack is active", "what's pinned".
+- User says "clear datapack", "unpin datapack", "stop using <name>".
+- The first Meko MCP write of a turn AND `memory_search` for `meko_active_datapack` returned no result AND the user has more than one datapack — proactively offer to pin one.
+
+## On every Meko-touching turn (not just when this skill triggers)
+
+Before issuing a Meko MCP write tool call (memory_add, db_run_write_query, conversation_add_message, etc.), if you don't already know the active pin from this turn's earlier work:
+
+```
+memory_search(scope="read",
+              query="meko_active_datapack",
+              agent_id="claude_desktop",
+              conversation_id="<this conversation's id>",
+              limit=1)
+```
+
+Parse the result. If a pin row is present, extract the UUID from the text body (after `meko_active_datapack=`) and pass it as `datapack_id` to every Meko MCP call this turn. If not, omit `datapack_id` and let the server resolve the default.
+
+This is once per turn, not once per call. Cache within the turn.
+
+## The flow
+
+### 1. List
+
+Use a **temporary** conversation for browsing only. Call
+`conversation_create(scope="write", agent_id="claude_desktop", title="Claude
+Desktop datapack selection")` and use its returned ID for the read-only
+`datapack_list` below and for the pin `memory_add`/`memory_update` in step 4.
+
+**Do not reuse this conversation for later capture.** It lives in whatever
+datapack was active when it was created (typically the default), and a
+conversation cannot move between datapacks. Once a datapack is pinned, capture
+must flow through a *new* conversation created in the selected datapack — see
+step 5.
+
+```
+datapack_list(scope="read", conversation_id="<this conversation's id>")
+```
+
+The response is an array; the fields you'll use are `datapack_id`,
+`datapack_name`, `created_at`, and `account_id`.
+
+If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(scope='admin', name='<name>')` 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).
+
+### 2. Render the table
+
+For 2+ datapacks, render a numbered table. **Page size 10.** Default sort: `created_at DESC` (newest first).
+
+```
+Your datapacks (showing 1-10 of 14):
+
+#   Name                                   Role    Created       Status     Active?
+1   meko-local-setup                       Owner   2026-04-30    ready       ←  (pinned)
+2   meko_default_datapack                  Owner   2026-04-30    ready
+3   prod-research                          Owner   2026-04-12    ready
+…
+
+Reply with: a number (1-10) to pin · a substring to search · `next` / `prev` to page
+            · `clear` to unset · `cancel` to leave the current pin alone
+
+Note: Role is hardcoded to "Owner" today. Shared / Viewer / Contributor /
+Maintainer roles are pending upstream backend work — see references/role-display-future.md.
+```
+
+Mark the currently-pinned row with `←  (pinned)` based on the `memory_search` result (if any).
+
+### 3. Parse the user's reply
+
+- **Integer in range** → that row is the choice.
+- **Substring** → re-render filtered. If it narrows to one row, that's the choice.
+- **`next` / `prev`** → re-render next/previous page.
+- **`cancel`** → leave any existing pin in place; print *"Cancelled. Active datapack unchanged."* Stop.
+- **`clear` / `none` / `unpin`** → see step 4's clear path.
+- **Unrecognized** → re-prompt with the legend.
+
+### 4. Persist
+
+**On first pin (no existing pin memory):**
+
+```
+memory_add(scope="write",
+           text="meko_active_datapack=<uuid> name=<name> selected_at=<iso8601>",
+           agent_id="claude_desktop",
+           conversation_id="<this conversation's id>",
+           metadata='{"type":"active-datapack-pin"}')
+```
+
+Verify the write with `memory_search` (the standard Meko verify-after-write rule from `meko-mcp-tools-desktop`). Capture the returned memory `id`.
+
+**On switch (existing pin memory found):**
+
+```
+memory_update(scope="write",
+              memory_id="<existing pin id>",
+              text="meko_active_datapack=<new uuid> name=<new name> selected_at=<iso8601>",
+              agent_id="claude_desktop",
+              conversation_id="<this conversation's id>")
+```
+
+Always update — never `memory_add` a second pin. Two pin memories will produce ambiguous reads.
+
+**On clear:**
+
+```
+memory_delete_by_id(scope="write",
+                    memory_id="<existing pin id>",
+                    agent_id="claude_desktop",
+                    conversation_id="<this conversation's id>")
+```
+
+If `memory_search` returned no pin, there's nothing to delete — print *"No pin was set; nothing to clear."* and stop.
+
+**Conversation transition after a clear (same rule as a switch).** The pin memory is now gone, but the session's current conversation still physically lives in the datapack that was pinned when it was created — a conversation cannot move to the default. You must pick exactly one of these; do not mix them:
+
+- **Option A — keep capturing to the current conversation this session.** It stays in its original (now-unpinned) datapack, so you must keep passing that **same old `datapack_id`** on its `conversation_add_message` calls — do NOT switch it to the default (that would fail). The clear only affects *new* sessions. Disclose: *"Pin cleared. This chat keeps saving to `<old datapack name>`; new chats will use the default datapack."*
+- **Option B — start default-datapack capture immediately.** Create a **new** conversation with no `datapack_id` (`conversation_create(scope="write", agent_id="claude_desktop")`) and post all subsequent turns there. Stop posting to the old conversation. Disclose: *"Pin cleared. Started a new chat context saving to the default datapack."*
+
+Default to Option A (least disruptive) unless the user wants the switch to take effect right now. Either way, never send `datapack_id=default` to the pre-existing pinned conversation.
+
+### 5. Confirm
+
+```
+Pinned datapack `<name>` (`<uuid>`) for Claude Desktop.
+
+This is stored as a memory under agent_id="claude_desktop". It will persist
+across sessions until you run this skill again with `clear` (or `switch` to
+a different datapack).
+
+I'll read this pin via `memory_search` before each Meko MCP write so the
+right `datapack_id` flows through automatically.
+```
+
+**Then start a fresh conversation for capture in the selected datapack.** The
+temporary selection conversation from step 1 belongs to the datapack that was
+active when it was created and cannot be moved. For subsequent capture this
+session, call `conversation_create(scope="write", agent_id="claude_desktop",
+datapack_id="<the newly pinned uuid>", title="<topic>")` and post turns
+(`conversation_add_message`) to *that* conversation with the same
+`datapack_id`. Do not keep posting to the selection conversation — doing so
+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.
+- **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.
+
+## Critical: do NOT use other persistence mechanisms
+
+Don't write to local files, don't use environment variables, don't ask the user to paste the UUID into every prompt. A single tagged memory is the entire mechanism. Anything else creates drift between what you think is pinned and what `memory_search` will report.
+
+## Reference sections
+
+| File | What it covers |
+|------|---------------|
+| `references/cookbook.md` | Sample list / search / select / clear transcripts on Desktop |
+| `references/troubleshooting.md` | Pin not recalled, duplicate pins, stale UUID recovery |

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

@@ -0,0 +1,121 @@
+# Cookbook — meko-select-datapack-desktop
+
+Concrete transcripts of the four flows the skill supports on Claude Desktop.
+
+## Flow 1 — First pin (no existing pin memory)
+
+**User:** `pin prod-research as my active datapack`
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[empty]
+
+> datapack_list(scope="read")
+[14 entries returned, filtering by "prod-research"]
+
+One match: `prod-research`. Pinning.
+
+> memory_add(scope="write",
+             text="meko_active_datapack=8b1c…f4a2 name=prod-research selected_at=2026-05-25T18:42:00Z",
+             agent_id="claude_desktop",
+             conversation_id="<conv-id>",
+             metadata='{"type":"active-datapack-pin"}')
+[returns id=mem_abc123]
+
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[verifies the row exists]
+
+Pinned datapack `prod-research` (`8b1c…f4a2`) for Claude Desktop.
+
+Stored as a memory under agent_id="claude_desktop"; persists across sessions
+until you run this skill again with `clear` or `switch`.
+
+I'll read this pin via memory_search before each Meko MCP write so the right
+datapack_id flows through automatically.
+```
+
+## Flow 2 — Switch (pin memory already exists)
+
+**User:** `switch to the q2-roadmap-deck datapack`
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[returns id=mem_abc123, text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
+
+> datapack_list(scope="read")
+[14 entries returned, filtering by "q2-roadmap-deck"]
+
+One match: `q2-roadmap-deck`. Switching pin.
+
+> memory_update(scope="write",
+                memory_id="mem_abc123",
+                text="meko_active_datapack=4c2e…a991 name=q2-roadmap-deck selected_at=2026-05-25T19:05:00Z",
+                agent_id="claude_desktop",
+                conversation_id="<conv-id>")
+
+Switched pin from `prod-research` to `q2-roadmap-deck` (`4c2e…a991`).
+```
+
+The `memory_update` is critical here — using `memory_add` again would create a duplicate pin memory.
+
+## Flow 3 — Single-datapack auto-select
+
+**User:** (first Meko write attempt, no pin yet)
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[empty]
+
+> datapack_list(scope="read")
+[1 entry returned]
+
+Only one datapack: `meko-local-setup`. Auto-selecting.
+
+> memory_add(scope="write",
+             text="meko_active_datapack=a17d…cc91 name=meko-local-setup selected_at=…",
+             agent_id="claude_desktop",
+             conversation_id="<conv-id>",
+             metadata='{"type":"active-datapack-pin"}')
+
+Pinned datapack `meko-local-setup` (`a17d…cc91`). Run this skill again with
+`clear` to unset.
+```
+
+## Flow 4 — Clear
+
+**User:** `unpin datapack`
+
+**Skill:**
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+[returns id=mem_abc123]
+
+> memory_delete_by_id(scope="write",
+                      memory_id="mem_abc123",
+                      agent_id="claude_desktop",
+                      conversation_id="<conv-id>")
+
+Pin cleared. Subsequent Meko MCP calls will use the server default.
+```
+
+If `memory_search` returned empty: *"No pin was set; nothing to clear."*
+
+## Flow 5 — Read-the-pin pattern (every Meko-touching turn)
+
+This isn't a user-triggered flow — it's the per-turn lookup the skill teaches you to do silently before any Meko MCP write:
+
+```
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop",
+                conversation_id="<conv-id>", limit=1)
+[returns text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
+
+# Extract UUID after "meko_active_datapack=" → 8b1c…f4a2
+
+> memory_add(scope="write", text="…", datapack_id="8b1c…f4a2",
+             agent_id="claude_desktop", conversation_id="<conv-id>")
+```
+
+Cache the UUID for the rest of the turn — don't call `memory_search` once per Meko tool call.