@yugabytedb/meko-mcp 2.2.0 → 2.5.0

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

@@ -1,22 +1,24 @@
 # Complete Tool Catalog and Decision Tree
 
-**23 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1). Combined Meko + AMP endpoints may expose additional infrastructure tools; those are outside this skill's scope.
+**28 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Retrieval (1), Memory (8), Conversation (6), Knowledge Base (4), Datapack (6), Artifacts (2), Observability (1). Combined Meko + AMP endpoints may expose additional infrastructure tools; those are outside this skill's scope.
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
-1. `memory_search(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(conversation_id="<this conversation's id>")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
+1. `memory_search(query="test", agent_id="claude_desktop", conversation_id="<id from conversation_create>")` — Confirms memory subsystem is up. May fail with "connection already closed" — see `tools-troubleshooting.md`.
+2. `datapack_search(conversation_id="<this conversation's id>", limit=1)`: confirms Meko API connectivity and returns one datapack your token has access to. On a server without `datapack_search`, call `datapack_list(conversation_id="<this conversation's id>")` instead.
 
 ## Decision tree: which tool do I need?
 
 ```
 User wants to...
+├── Ask "what do you know about X?" --------> context_search (read; memory + KB + past conversations in one call)
 ├── Search personal context? ---------------> memory_search (read)
 ├── Search shared datapack knowledge? ------> 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)
+├── Add a file to a knowledge base? --------> knowledgebase_upload_document (write)
+│   └── Check its indexing progress? -------> knowledgebase_document_status (read)
+├── Delete ONE knowledge-base file? --------> knowledgebase_delete_document (destructive — confirm with the user first)
 ├── Store or recall information?
 │   ├── Store a fact/preference/entity? -----------> memory_add (write)
 │   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
@@ -27,50 +29,63 @@ User wants to...
 │   ├── Upload a generated file (report, CSV, PDF)? -> artifact_put (write)
 │   └── Retrieve a previously uploaded file? -------> artifact_get (read)
 └── Manage datapacks?
+    ├── Find a datapack id by name? -------> datapack_search(query=...) (read)
     └── 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.
+Agent lifecycle and KB **index / source lifecycle** (creating indexes, adding sources, re-indexing) are managed outside the MCP surface — typically in the Meko control-plane UI. Single KB files are handled here: adding one (`knowledgebase_upload_document`, then `knowledgebase_document_status`) and deleting one (`knowledgebase_delete_document`).
 
-## Knowledge Base Tools (1)
+## Retrieval Tools (1)
 
 | Tool | Purpose |
 |------|---------|
-| `knowledgebase_search(query, agent_id, conversation_id, datapack_id, limit=10)` | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
+| `context_search(query, conversation_id, agent_id=None, datapack_id=None, limit=10, force_source="auto")` | Default first call for open-ended recall. Queries memory, the knowledge base, and the conversation-history cache in parallel and returns each source in its own bucket: `{"results": {"memory": [...], "knowledge_base": [...], "conversation": {"hits": [...], "thread": [...]}}, "token_savings": {...}}`. A bucket is `null` only when that source wasn't queried: `force_source` excluded it, or the server couldn't build a query vector for it. An empty bucket is ambiguous: either that source found nothing relevant, or it failed. `context_search` turns a failed source into an empty list and records the error only in the trace. Before you tell the user nothing is stored about X, confirm with `memory_search` or `knowledgebase_search`, which return errors. `force_source` is `"auto"` (all three), `"memory"`, `"knowledge_base"`, or `"conversation"`; any other value returns `invalid_force_source`. `limit` bounds the memory and KB buckets only; the conversation bucket returns up to 10 hits plus a thread of whole turns. The conversation bucket is datapack-wide. It returns embedded turns from every user and agent on the datapack, and each hit carries its author's `user_id`. Don't present a hit as this user's own history. |
+
+## Knowledge Base Tools (4)
+
+| Tool | Purpose |
+|------|---------|
+| `knowledgebase_search(query, conversation_id, datapack_id, agent_id=None, limit=10)` | Hybrid (semantic + keyword) search across KB chunks and promoted memories. `datapack_id` is REQUIRED (no default). Each hit has `id`, `chunk_text`, `document_id`, `metadata_filters`, `distance`, and `match_type` (`semantic`, `keyword`, or `hybrid`). |
+| `knowledgebase_delete_document(document_id, conversation_id, datapack_id="")` | Permanently delete ONE KB file (chunks + metadata; stored-file delete is best-effort — check `s3_deleted`). Irreversible: confirm with the user first. `document_id` comes from `knowledgebase_search` hits (no filename in hits — echo the id + chunk text). Owner/maintainer/uploader only (status 403 otherwise); status 409 while still indexing — wait and retry. |
+| `knowledgebase_upload_document(filename, size, content_hash, conversation_id, content_head_base64, datapack_id=None, agent_id=None)` | Requests a presigned S3 URL for a file (does not upload bytes itself — the caller POSTs to the returned `url`/`fields`). Returns `{datapack_id, url, fields, key, already_uploaded}` (fresh upload) or `{datapack_id, url: "", key, already_uploaded: true, existing_filename}` (dedup). Accepted extensions: pdf/txt/text/md/json/csv/xml/html/htm; `content_head_base64` (base64 of the file's first 3072 bytes, or the whole file if shorter) is **required** and is always sniffed against the extension before requesting the URL — a missing/blank value is rejected as `content_head_base64_required`, this check cannot be skipped. Idempotent by content hash. |
+| `knowledgebase_document_status(document_key, conversation_id, datapack_id=None, agent_id=None)` | Poll indexing progress for a file uploaded via `knowledgebase_upload_document`, using its returned `key` (passed here as `document_key`). `state` is one of `awaiting_upload`/`indexing` (non-terminal) or `completed`/`failed`/`abandoned`/`oversized` (terminal). |
 
 ## Memory Tools (8)
 
 | Tool | Purpose |
 |------|---------|
-| `memory_add(text, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
-| `memory_search(query, agent_id, conversation_id="", user_id=None, limit=10, datapack_id=None)` | Hybrid search across memories (semantic + keyword + entity boost). `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
-| `memory_get_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
-| `memory_get_all(agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | List all memories for agent |
-| `memory_update(memory_id, text, agent_id, conversation_id, datapack_id=None)` | Overwrite memory text |
-| `memory_delete_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Delete a single memory |
-| `memory_delete_all(agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | Delete all memories for agent (destructive) |
-| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403.
+| `memory_add(text, conversation_id, agent_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
+| `memory_search(query, conversation_id, agent_id=None, limit=10, datapack_id=None, run_id=None)` | Hybrid search across memories (semantic + keyword + entity boost). Drops rows below a server-configured similarity floor (default 0.2), so a weak query can return an empty list. `conversation_id` is required but only nests the trace. It must be a 32-hex id: `""` currently fails (MEKO-707), so pass a freshly generated one if you have no conversation yet. `run_id` filters to one conversation's memories. |
+| `memory_get_by_id(memory_id, conversation_id, agent_id=None, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. Returns `not_found` for a missing id and for an id that belongs to another account. |
+| `memory_get_all(conversation_id, agent_id=None, run_id=None, datapack_id=None, promoted=False)` | Recent window (about 20 rows) of the user's memories across every agent, plus the true `total`. Not a complete listing. `promoted=True` returns the recent window of promoted memories instead. `run_id` is ignored. |
+| `memory_update(memory_id, text, conversation_id, agent_id=None, datapack_id=None)` | Overwrite memory text. Returns `memory_is_promoted` for a promoted memory (edit those in the Cloud UI Learnings tab). |
+| `memory_delete_by_id(memory_id, conversation_id, agent_id=None, datapack_id=None)` | Delete a single memory. Returns `memory_is_promoted` for a promoted memory. |
+| `memory_delete_all(conversation_id, agent_id=None, run_id=None, datapack_id=None)` | Delete all memories in the **passed `agent_id`'s bucket** (destructive). Unlike reads, this is agent-scoped: omitting `agent_id` deletes only the `meko_agent` bucket. `run_id` narrows it to one conversation; a malformed value returns `invalid_run_id`. |
+| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403. |
 
 ## Conversation Tools (6)
 
 | Tool | Purpose |
 |------|---------|
-| `conversation_create(agent_id, user_id=None, app_id=None, run_id=None, title=None, metadata=None, session_id="")` | Create conversation container (Langfuse session) |
-| `conversation_add_message(conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None, trace_id="")` | Add a message turn (Langfuse trace) |
-| `conversation_get(conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | Retrieve conversation, optionally with messages |
-| `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List conversations for agent within a datapack. `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_list` to look it up. `conversation_id` optional (omit for browse). |
-| `conversation_update(conversation_id, agent_id, title=None, metadata=None)` | Update title or metadata |
-| `conversation_delete(conversation_id, agent_id)` | Delete entire conversation (destructive) |
+| `conversation_create(agent_id=None, run_id=None, title=None, metadata=None, session_id="", datapack_id=None)` | Create conversation container (Langfuse session) |
+| `conversation_add_message(conversation_id, input, output, agent_id=None, reasoning=None, metadata=None, seed=None, datapack_id=None, plan=None)` | Add a message turn (Langfuse trace). `output` is required. The response may include `extracted_memories` and, when the turn wasn't embedded for conversation search, `conversation_search_skipped` (`quota_exceeded` or `datapack_opted_out`). |
+| `conversation_get(conversation_id, agent_id=None, include_messages=False, limit=100, offset=0, datapack_id=None)` | Retrieve conversation, optionally with messages |
+| `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List the user's conversations within a datapack (`agent_id` does not filter — trace attribution only). `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_search(query=...)` to look it up. `conversation_id` optional (omit for browse). |
+| `conversation_update(conversation_id, agent_id=None, title=None, metadata=None, datapack_id=None)` | Update title or metadata |
+| `conversation_delete(conversation_id, agent_id=None, datapack_id=None)` | Delete entire conversation (destructive) |
 
-## Datapack Management Tools (5)
+## Datapack Management Tools (6)
 
 | Tool | Purpose |
 |------|---------|
-| `datapack_create(name)` | Create new datapack |
-| `datapack_list(conversation_id, datapack_id=None)` | List all datapacks. `conversation_id` is required for trace nesting; omit `datapack_id` to use the endpoint default. |
-| `datapack_describe(datapack_id, include_status=False)` | Describe datapack by UUID |
-| `datapack_update(datapack_id, name=None, description=None)` | Rename a datapack and/or update its description. Pass at least one of `name` / `description`. |
-| `datapack_delete(datapack_id)` | Delete datapack by UUID (irreversible) |
+| `datapack_create(name, conversation_id)` | Create new datapack |
+| `datapack_search(conversation_id, query="", name="", limit=20, cursor="", grant="", sort="created", include_total=False, datapack_id=None)` | Find datapacks and page through them. Returns `{datapacks, has_more, next_cursor, total}`. Use `query` for part of a name, `name` for an exact name, and `cursor` (the previous page's `next_cursor`) for the next page. `limit` is 1-100. `grant` is `owner` or `shared`; `sort` is `created` (newest first) or `name`. Pass `include_total=True` only when you must show "N of M". Rows carry no connection fields and no counts. Servers older than this tool don't have it; use `datapack_list` there. |
+| `datapack_list(conversation_id, datapack_id=None, query="", limit=0)` | Return datapacks as one array. Fine for a small account. `query` filters by part of a name; more than 100 matches return a `too_many_datapacks` error. `limit` returns the first matches (at most 100) without saying whether more exist. With neither, an account that can see more than 1000 datapacks (the server default limit) gets a `too_many_datapacks` error; use `datapack_search` then. `conversation_id` is required for trace nesting. |
+| `datapack_describe(conversation_id, datapack_id="", include_status=False)` | Describe a datapack by UUID (default datapack if omitted). Returns `memory_count`, `collective_memory_count` (promoted), `learnings_count` (awaiting a promotion decision), `knowledge_base_file_count`, `knowledge_chunk_count`, and `shared_knowledge_count`. `knowledge_base_file_count` and `shared_knowledge_count` are `null` when the status endpoint is unreachable; `knowledge_count` is a deprecated alias of `knowledge_chunk_count`. |
+| `datapack_update(datapack_id, conversation_id, name=None, description=None, conversation_search_opt_out=None)` | Rename a datapack, update its description, and/or opt out of (or back into) conversation-search caching. Pass at least one field. Opt-out is owner/maintainer only. |
+| `datapack_delete(datapack_id, conversation_id)` | Delete datapack by UUID (irreversible) |
+
+All six datapack tools reject an empty `conversation_id` with `conversation_id_required`.
 
 ## Artifact Tools (2)
 
@@ -98,10 +113,10 @@ Some things the Meko platform can do are not wired into the MCP tool surface tod
 | 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.
+The MCP-exposed `datapack_create` / `datapack_search` / `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.
+For a file already on disk or generated mid-conversation, requesting a URL with `knowledgebase_upload_document` and POSTing to it gets it into the KB without leaving MCP for a human's help. The UI upload path (Datapack → Actions → **Add Knowledge**, PDF/TXT/MD/JSON/CSV/XML/HTML, 5MB Free / 50MB Standard / 60MB Pro+ each, 10/batch) remains the way for a human to add files directly. `knowledgebase_search` queries the resulting index either way.
 
 ## Common Parameter Patterns
 
-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`).
+Memory and KB tools accept optional `datapack_id` to target a specific datapack. A `datapack_id` your account can't access returns `datapack_access_denied`. `agent_id` attributes writes. Conversations are agent-owned: `conversation_get`, `conversation_add_message`, `conversation_update`, and `conversation_delete` return `agent_id_mismatch` for any value other than the creating agent's. `agent_id` does **not** filter memory reads (`memory_search`/`memory_get_all`) or `conversation_list`, which return all your agents' rows for the user. `memory_delete_all` is the exception on the memory side: it deletes only the passed `agent_id`'s bucket. See `tools-agent-id-conventions.md`.

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

@@ -1,16 +1,21 @@
 # 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`).
+MCP exposes four KB tools: `knowledgebase_search` (retrieval),
+`knowledgebase_upload_document` and `knowledgebase_document_status` (add a
+file and track its indexing), and `knowledgebase_delete_document` (remove ONE
+uploaded file). Creating, listing or renaming a knowledge base itself still
+happens 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 |
+| Search an existing KB | `knowledgebase_search` | Retrieval over the indexed chunks |
+| Add a file to a KB | `knowledgebase_upload_document` + one direct S3 POST | Requests a presigned URL, then you POST the file to it; no need to leave MCP |
+| Track a file's indexing progress | `knowledgebase_document_status` | Poll with the `key` from the upload response, passed here as `document_key`, until `state` is terminal |
+| Add documents to a KB from the Cloud UI instead | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/CSV/XML/HTML, 5 MB Free / 50 MB Standard / 60 MB Pro+ each, 10/batch). Same index either way — this is the human-facing path, not required when an agent can upload directly |
+| Delete ONE uploaded file | `knowledgebase_delete_document` | Destructive; `document_id` from search hits; confirm with the user first |
+| Anything else (list / rename / re-index / source lifecycle) | **UI** | No MCP tools for the rest of KB lifecycle |
 
 ## knowledgebase_search — the one you'll actually call
 
@@ -23,7 +28,7 @@ knowledgebase_search(
     limit=10)
 ```
 
-Required: `query`, `agent_id`, `conversation_id`, `datapack_id`.
+Required: `query`, `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
@@ -37,10 +42,12 @@ Populated KB:
 {
   "results": [
     {
-      "content": "<chunk text>",
-      "similarity": 0.87,
-      "source_uri": "<original source URI>",
-      "document_name": "<file key>",
+      "id": "<chunk id>",
+      "chunk_text": "<chunk text>",
+      "document_id": "<KB document id; pass to knowledgebase_delete_document>",
+      "metadata_filters": {},
+      "distance": 0.31,
+      "match_type": "semantic" | "keyword" | "hybrid",
       ...
     },
     ...
@@ -49,9 +56,64 @@ Populated KB:
 }
 ```
 
+Lower `distance` is closer. Promoted memories appear as hits whose `metadata_filters.source` is `"memory"`. Hits carry no filename, so show the user the `document_id` and chunk text when they need to identify a file.
+
 Empty or nonexistent KB: `{"results": [], "count": 0}` (no error,
 just an empty array).
 
+## knowledgebase_upload_document — putting a file in
+
+This tool never touches the file's bytes itself — it only requests a
+presigned S3 URL. **You POST the file to that URL yourself**, as a
+second step:
+
+```
+knowledgebase_upload_document(
+    filename="report.pdf",
+    size=42000,
+    content_hash="<sha256 hex of the file's bytes>",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop",
+    content_head_base64="<base64 of the file's first ~4KB>")
+```
+
+Build the POST from every key in the response's `fields`, not a hand-picked list:
+a missing signed field such as `x-amz-security-token` makes S3 answer 403. Use
+the Python, curl, or PowerShell snippet under `knowledgebase_upload_document`
+in `tools-cookbook.md`. Confirm with the user first: the file becomes visible to
+every datapack member.
+
+Required: `filename`, `size` (the exact byte count — the URL accepts no
+other length), `content_hash`, `conversation_id`, `content_head_base64`. `content_hash` is the SHA-256 hex digest of the
+file's bytes, computed by you (e.g. `sha256sum`) — it becomes part of
+the S3 key, so it also drives the dedup check. A response with
+`already_uploaded: true` means identical content already exists; skip
+the S3 POST entirely, there is nothing left to upload. Otherwise POST
+as above: every key in `fields` as a form field (in order), then the
+bytes last as a field named `"file"`. Meko registers the object once
+it lands, so no separate confirm call is needed after the POST. Accepted extensions:
+pdf, txt, text, md, json, csv, xml, html, htm; `content_head_base64` is
+always sniffed against the extension before requesting the URL,
+rejecting an obvious mismatch immediately instead of waiting for the
+watcher — a missing/blank value is rejected as
+`content_head_base64_required`, this sniff cannot be skipped.
+Ingestion is asynchronous — save the response's
+`key` (as `document_key`) and poll `knowledgebase_document_status`.
+
+## knowledgebase_document_status — tracking it
+
+```
+knowledgebase_document_status(
+    document_key="<the upload response's `key`>",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop")
+```
+
+`state` covers the whole lifecycle: `awaiting_upload` and `indexing`
+are non-terminal (poll again); `completed`, `failed`, `abandoned`, and
+`oversized` are terminal. `NOT_FOUND` means the `document_key` doesn't
+belong to this datapack.
+
 ## UI ingestion — what the user sees
 
 From `cloud.mekodata.ai`:
@@ -59,11 +121,14 @@ 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.
+   CSV, XML, HTML. Per-file limit 5 MB (Free) / 50 MB (Standard) / 60 MB (Pro+). 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.
+If a *human* asks you "how do I add a document to my knowledge base?",
+point them at this flow. If *you* (the agent) have the file's bytes —
+already on disk, or generated mid-conversation — call
+`knowledgebase_upload_document` directly instead of describing the UI
+flow to yourself.

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,74 @@ 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`, `knowledgebase_upload_document`, `knowledgebase_document_status`, 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. |
+| `read_only_access` | You're a viewer on this datapack. Viewers can't write conversations or memories, call `memory_promote`, `artifact_put`, or `track_token_usage`, or delete a conversation someone else started. | Don't retry, and don't switch datapacks to get around it. Tell the user; an owner or maintainer can change their role. |
+| `role_lookup_failed` | The server couldn't read your role for this datapack, so it refused the write. | Retry. |
+| `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.3.1"
   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
 
@@ -63,7 +63,7 @@ This is once per turn, not once per call. Cache within the turn.
 Use a **temporary** conversation for browsing only. Call
 `conversation_create(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.
+datapack calls 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
@@ -71,12 +71,28 @@ 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.
 
+Check your tool list. If it has `datapack_search`, use it as below. If it
+doesn't (an older Meko server), use the fallback section at the end of step 3.
+
 ```
-datapack_list(conversation_id="<this conversation's id>")
+datapack_search(conversation_id="<this conversation's id>", limit=10, include_total=true)
+```
+
+The server sorts, filters and pages, so this works the same for 3 datapacks or
+1,000,000. The response is one page:
+
+```
+{"datapacks": [...], "has_more": true, "next_cursor": "<opaque token>", "total": 14}
 ```
 
-The response is an array; the fields you'll use are `datapack_id`,
-`datapack_name`, `created_at`, `account_id`, and `grant`.
+- `datapacks`: up to `limit` rows, newest first (`created_at DESC`). The
+  fields you'll use are `datapack_id`, `datapack_name`, `created_at`, and
+  `grant`.
+- `has_more`: `true` when another page exists.
+- `next_cursor`: pass it as `cursor` to get the next page. It is `""` on the
+  last page. Treat it as opaque: never build or edit one.
+- `total`: how many datapacks match, present because you passed
+  `include_total=true`.
 
 `grant` is the caller's actual authorization on the datapack — one of
 `"owner"`, `"maintainer"`, `"contributor"`, `"viewer"`. Display it verbatim in
@@ -85,13 +101,22 @@ 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 `total` is 0, 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 `total` is exactly **1**, **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).
+
+If `total` is missing or `null`, decide from the page instead: no rows and
+`has_more` false means zero datapacks; one row and `has_more` false means
+exactly one. Drop `of <total>` from the header in step 2.
 
-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).
+**Keep the paging state in the conversation.** Remember the current filter
+(none yet), the `total`, the page number, the `next_cursor`, and a list of the
+cursors you used for each page so far (page 1 used no cursor). `next` and
+`prev` in step 3 need them.
 
 ### 2. Render the table
 
-For 2+ datapacks, render a numbered table. **Page size 10.** Default sort: `created_at DESC` (newest first).
+For 2+ datapacks, render a numbered table of the current page. **Page size 10.** Row order is the server's (`created_at DESC`, newest first). Number rows by position in the whole list: page 1 shows 1-10, page 2 shows 11-20. The count line is `Your datapacks (showing <first>-<last> of <total>):`, for example:
 
 ```
 Your datapacks (showing 1-10 of 14):
@@ -112,17 +137,71 @@ The **Role** column shows each datapack's `grant` value verbatim (`owner`,
 datapacks legitimately carry other grants, and misreporting them (e.g. showing
 a `maintainer` grant as "Owner") misleads the user about their own access.
 
-Mark the currently-pinned row with `←  (pinned)` based on the `memory_search` result (if any).
+Mark the currently-pinned row with `←  (pinned)` based on the `memory_search` result (if any). If the pinned datapack is not on the current page, name it in one line above the table.
+
+In the legend, the number range is the rows on the current page (`11-20` on
+page 2). Offer `next` only when `has_more` is true and `next_cursor` is
+non-empty. An empty `next_cursor` with `has_more` still true means this
+server cannot page further: tell the user to narrow with a substring, and
+do not send an empty cursor. Offer `prev` only after page 1.
+
+For a search (step 3), the count line is
+`Datapacks matching "<text>" (showing <first>-<last> of <total>):`, numbered
+from 1.
 
 ### 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.
+- **Integer shown on the current page** → that row is the choice.
+- **Substring** → search on the server; do not filter the rows you already have:
+  ```
+  datapack_search(conversation_id="<this conversation's id>", query="<text>", limit=10, include_total=true)
+  ```
+  This starts a new listing: reset the page number and the cursor list, and
+  keep `<text>` as the filter so `next` / `prev` page through the matches. If
+  `total` is 0, say *"No datapacks match `<text>`."* and re-prompt with the
+  legend. If `total` is exactly 1, that's the choice. Otherwise render the
+  matches with the search count line from step 2.
+- **`next`** → if `has_more` is false, say this is the last page and
+  re-prompt. If `next_cursor` is empty, say this server cannot page further
+  and ask for a substring; do not send an empty cursor. Otherwise call
+  `datapack_search` with the same `query` (if any), `limit=10` and
+  `cursor="<next_cursor>"`, add that cursor to your list, and render the new
+  page. Reuse the `total` you already have.
+- **`prev`** → on page 1, say this is the first page and re-prompt. Otherwise
+  drop the last cursor from your list and call `datapack_search` again with
+  the same `query` and the cursor now at the end of the list (no cursor for
+  page 1).
 - **`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.
 
+If a call with a `cursor` returns an error, the cursor is no longer usable.
+Tell the user, then start again from the first page of the same filter.
+
+When the user names a datapack in the request itself ("pin prod-research"),
+skip the first listing and go straight to the substring search with that name.
+
+### Fallback: servers without `datapack_search`
+
+An older Meko server has only `datapack_list`. Run the same steps with these
+changes:
+
+```
+datapack_list(conversation_id="<this conversation's id>")
+```
+
+- The response is one array of every datapack, with the same row fields.
+  `total` is the array length.
+- Sort it `created_at DESC` yourself, show 10 rows per page, and page
+  `next` / `prev` over the array you already have.
+- Filter substrings client-side on `datapack_name` (case-insensitive) and
+  re-render the matching rows numbered from 1. If the filter narrows to one
+  row, that's the choice.
+
+If `datapack_list` returns `{"error": "too_many_datapacks", ...}`, the server
+does have `datapack_search`; your tool list is stale. Reload the Meko tools and
+use the main flow.
+
 ### 4. Persist
 
 **On first pin (no existing pin memory):**
@@ -192,7 +271,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.