@yugabytedb/meko-mcp 2.2.0 → 2.5.0

package/assets/skills/meko-mcp-tools/references/tools-cookbook.md

@@ -6,6 +6,47 @@ Every tool example below shows the correct parameters, expected response, and co
 
 ---
 
+## Retrieval
+
+### context_search
+
+Default first call for open-ended recall ("what do you know about X?"). One call queries memory, the knowledge base, and the conversation-history cache in parallel.
+
+```
+context_search(
+    query="auth migration decisions",
+    agent_id="<your agent_id>",
+    conversation_id="<session conversation id>",
+    datapack_id="<datapack UUID>")
+```
+
+Required: `query`, `conversation_id`. `datapack_id` is optional (default datapack if omitted); pass the pinned id when you have one.
+
+Response:
+
+```
+{
+  "results": {
+    "memory": [{"id": "...", "memory": "...", "score": 0.51, ...}],
+    "knowledge_base": [{"id": "...", "chunk_text": "...", "document_id": "...", "distance": 0.31, "match_type": "hybrid", ...}],
+    "conversation": {"hits": [...], "thread": [...]}
+  },
+  "token_savings": {"total_tokens": 49000, "memory": {"tokens_sent": 600, "tokens_saved": 48400}, "tokens_saved": 48400}
+}
+```
+
+- 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.
+- 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.
+- `limit` bounds the memory and KB buckets only; the conversation bucket returns up to 10 hits plus a thread of whole turns.
+- The memory bucket has no similarity floor on the default path. The KB bucket drops chunks above an absolute distance cutoff, so it can be empty even when `knowledgebase_search` would return a weak best match.
+- `force_source="memory" | "knowledge_base" | "conversation"` queries only that source. `force_source="memory"` reapplies the `memory_search` similarity floor.
+- `token_savings` is an estimate for reporting. Don't base decisions on it.
+
+**Errors:** `conversation_id_required`, `invalid_force_source`, `datapack_access_denied`, and `free_tier_limit_reached` (Free tier: 1,000 lifetime calls). Treat any error as a failed search (SKILL.md operating contract 1).
+
+---
+
 ## Memory Tools
 
 **Critical:** Pass your session's `agent_id` on every memory *write* (from the SessionStart `additionalContext`) — it is stored on the row as attribution. It does **not** filter reads: one `memory_search` / `memory_get_all` returns all of your memories across every `agent_id`. For cross-project facts, write with `agent_id="meko_agent"`.
@@ -27,7 +68,7 @@ memory_add(agent_id="<your-agent-id>",
 
 **What NOT to store via memory_add:**
 - Full conversations (use `conversation_create` + `conversation_add_message`)
-- Large documents (use the UI's Datapack → Actions → Add Knowledge upload flow)
+- Large documents (use `knowledgebase_upload_document`, or the UI's Datapack → Actions → Add Knowledge upload flow)
 - Multi-topic dumps (transcripts, mixed logs + decisions) — store **one coherent fact per memory**, with the identifiers a later search will use
 
 **Common errors:**
@@ -46,13 +87,15 @@ memory_search(query="What programming language does the team use?", agent_id="ag
 
 **Cross-conversation discovery.** `memory_search` returns hits across every stored conversation for the `(datapack_id, user_id)` pair, across all agents (`agent_id` scopes the call's trace, not the results). When a hit references an interesting conversation, follow up with `conversation_list` to browse the associated threads and `conversation_get` to read a specific one — the memory hit's `meko_conversation_id` field is the id to fetch. For a deliberately cross-conversation search leave `run_id` off; to scope a search to a single conversation instead, pass `run_id=<conversation_id>` (it filters on `meko_conversation_id` — see `tools-known-limitations.md`).
 
-**Relevance floor.** Vector-matched `results` below `MEMORY_SEARCH_MIN_SCORE` (mem0's cosine-similarity score, default `0.5`) are dropped as weak matches rather than returned. A query can come back with fewer results than `limit`, or an empty list, when nothing clears the bar; that means no sufficiently relevant memory, not a broken call.
+**Relevance floor.** `memory_search` drops results whose raw cosine similarity is below the server's `memory_search_min_score` setting (default `0.2`, tunable at runtime). A query can return fewer results than `limit`, or an empty list, when nothing clears the bar. That means no sufficiently relevant memory, not a broken call.
 
 **Response:**
 ```json
-{"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
+{"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89, "raw_similarity_score": 0.72}]}
 ```
 
+`score` is the fused hybrid rank (semantic + keyword + entity boost) used to order results; `raw_similarity_score` is the unfused cosine value. A similarity threshold like `MEMORY_SEARCH_MIN_SCORE` gates on `raw_similarity_score` when it is not null, and falls back to `score` when the raw field is absent or null.
+
 **With limit:**
 ```
 memory_search(query="user preferences", agent_id="agent", conversation_id="<uuid>", limit=5)
@@ -64,7 +107,7 @@ memory_search(query="user preferences", agent_id="agent", conversation_id="<uuid
 
 ### memory_get_all
 
-**When to use:** List all of your memories for this user — across every `agent_id` (`agent_id` does not filter the result). Useful at session start to load context.
+**When to use:** See the most recent memories (about 20 rows) across every `agent_id`, plus the true `total`. It is not a complete listing and takes no paging arguments (SKILL.md operating contract 2). Use `memory_search` or `memory_get_by_id` for anything older or specific.
 
 ```
 memory_get_all(agent_id="agent", conversation_id="<uuid>")
@@ -96,11 +139,13 @@ memory_update(memory_id="mem-uuid-123", text="Updated: Team uses Go for all new
 memory_delete_by_id(memory_id="mem-uuid-123", agent_id="agent", conversation_id="<uuid>")
 ```
 
+`memory_update` and `memory_delete_by_id` return `memory_is_promoted` for a promoted memory, and `not_found` for an id that is missing or belongs to another account.
+
 ---
 
 ### memory_delete_all
 
-**Destructive.** Deletes all memories for the agent. For removing a single memory, prefer `memory_delete_by_id` — `memory_delete_all` wipes the entire agent scope in the datapack.
+**Destructive.** Deletes all memories in the passed `agent_id`'s bucket in the datapack. It does not touch other agents' rows, even though `memory_search` shows them; omitting `agent_id` deletes only the `meko_agent` bucket. Pass `run_id=<conversation_id>` to limit it to one conversation. For removing a single memory, prefer `memory_delete_by_id`.
 
 ```
 memory_delete_all(agent_id="agent", conversation_id="<uuid>")
@@ -134,9 +179,12 @@ Get exact UUIDs from the `id` field of `memory_search` / `memory_get_all` result
 
 ```
 conversation_create(agent_id="agent",
-    title="Debugging the auth middleware")
+    title="Debugging the auth middleware",
+    datapack_id="<uuid from datapack_search>")
 ```
 
+`datapack_id` is required whenever no server-side default resolves for the caller. Omitting it in that state returns `{"error": "datapack_id_required"}` and persists nothing; the same contract applies to `conversation_add_message`, `conversation_get`, `conversation_update`, and `conversation_delete`.
+
 **Response:**
 ```json
 {"id": "conv-uuid-123", "title": "Debugging the auth middleware"}
@@ -177,8 +225,8 @@ conversation_get(conversation_id="conv-uuid-123", agent_id="agent",
 ### conversation_list
 
 Target the datapack by `datapack_id` (UUID). It's optional — omit it to use the
-pinned/default datapack, or pass the pinned `datapack_id`. Use `datapack_list`
-to look up the id.
+pinned/default datapack, or pass the pinned `datapack_id`. Use
+`datapack_search(query="<part of the name>")` to look up the id.
 
 ```
 conversation_list(datapack_id="<datapack-uuid>", agent_id="agent", limit=20)
@@ -207,7 +255,7 @@ conversation_delete(conversation_id="conv-uuid-123", agent_id="agent")
 
 ## Knowledge Base Tools
 
-**KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` is the one KB tool exposed via MCP.
+Agents upload files via `knowledgebase_upload_document` and poll `knowledgebase_document_status` for indexing progress; a human uploading through the Cloud UI still uses the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/CSV/XML/HTML, 5MB Free / 50MB Standard / 60MB Pro+ each, 10/batch) — both paths feed the same index. `knowledgebase_search` queries whatever the KB currently holds. MCP also exposes `knowledgebase_delete_document` for removing a single uploaded file.
 
 See `tools-rag-workflow.md` for the decision table.
 
@@ -235,6 +283,184 @@ Populated KBs return results with chunk content and similarity scores. An empty/
 
 ---
 
+### knowledgebase_delete_document
+
+Permanently deletes ONE knowledge-base file — its chunks and metadata in one transaction, plus a best-effort delete of the stored file. Irreversible: confirm with the user before calling, and take `document_id` from `knowledgebase_search` hits — hits carry `document_id` but NOT a filename, so confirm by echoing the id and the matched chunk text (the documents list API / Meko UI is the authoritative name source). Never guess an id; non-UUID values are rejected.
+
+```
+knowledgebase_delete_document(document_id="<uuid from a search hit>",
+                              conversation_id="<session conversation id>")
+```
+
+Returns `{"document_id", "chunks_deleted", "s3_deleted"}` — if `s3_deleted` is `false`, say so: the index entries are gone but the stored file may remain. Errors include a numeric `status`: `403` means the user is not the datapack owner, a maintainer, or the file's uploader — report it, don't retry; `409` (`DOCUMENT_PROCESSING`) means the file is still being indexed — wait for indexing to finish, then retry.
+
+### knowledgebase_upload_document
+
+**When to use:** Get a file's bytes into the datapack's KB for later `knowledgebase_search` retrieval — a file already on disk, or one generated mid-conversation. This tool never touches the file's bytes itself; it only requests a presigned S3 URL. Meko registers the file once it lands, so there's no separate confirm call. **The caller POSTs the file to the returned `url` directly** — multipart/form-data, every key in `fields` as a form field (in order), then the file's bytes last as a field named `"file"`.
+
+**Confirm first.** The file goes into the datapack's shared knowledge base, which every member can read. Before calling the tool, tell the user which file and datapack, say the team will see it, and wait for a yes.
+
+**You need a shell that can make the POST** (Python, curl, or PowerShell, below). Without one, as in Claude Desktop by default, don't call the tool: point the user at Datapack → Actions → **Add Knowledge**. An issued URL holds its `size` against the storage quota for up to 15 minutes even if nothing is uploaded.
+
+**After the user confirms and the tool returns, POST the file in the same turn.** The upload is only half-done once you have `url`/`fields`; nothing else completes it for you.
+
+**First, compute `content_hash` and `content_head_base64` — both required — *before* calling the tool at all. `content_head_base64` is compulsory: the tool refuses with `content_head_base64_required` if it's missing or blank, so there's no path that skips the sniff.**
+
+Linux:
+```bash
+CONTENT_HASH=$(sha256sum report.pdf | cut -d' ' -f1)
+CONTENT_HEAD_B64=$(head -c 3072 report.pdf | base64 -w0)
+```
+
+macOS (no `sha256sum` by default — use `shasum`; BSD `base64` has no `-w0`, so strip newlines with `tr` instead):
+```bash
+CONTENT_HASH=$(shasum -a 256 report.pdf | cut -d' ' -f1)
+CONTENT_HEAD_B64=$(head -c 3072 report.pdf | base64 | tr -d '\n')
+```
+
+Windows PowerShell:
+```powershell
+$ContentHash = (Get-FileHash -Algorithm SHA256 -Path "report.pdf").Hash.ToLower()
+$bytes = [System.IO.File]::ReadAllBytes("report.pdf")
+$head = $bytes[0..([Math]::Min(3071, $bytes.Length - 1))]
+$ContentHeadB64 = [Convert]::ToBase64String($head)
+```
+
+Windows cmd.exe (`certutil` ships built in for the hash — prints it on its own line, strip the header/footer lines before use; cmd.exe has **no** built-in way to take just the first 3072 bytes *and* base64-encode them in one step, so use the PowerShell or Python snippet for `content_head_base64` even in a cmd.exe-driven workflow):
+```bat
+certutil -hashfile report.pdf SHA256
+```
+
+Python (cross-platform; streams the file so a large one isn't fully loaded into memory, and reuses the same read to build `content_head_base64` too):
+```python
+import hashlib, base64
+
+h = hashlib.sha256()
+with open(LOCAL_PATH, "rb") as f:
+    head = f.read(3072)                      # also the content_head_base64 sample
+    h.update(head)
+    for chunk in iter(lambda: f.read(1 << 20), b""):
+        h.update(chunk)
+
+content_hash = h.hexdigest()
+content_head_base64 = base64.b64encode(head).decode()
+```
+
+**Then, after the tool call returns `{url, fields}` — a portable snippet (identical on Linux/macOS/Windows, needs `python3` + `requests`), because it loops over whatever `fields` came back instead of hand-enumerating field names, so it can't drift out of sync with what the response actually contains:**
+
+```python
+import json, requests
+resp = json.loads(RESPONSE_JSON)        # the tool's raw JSON string
+if not resp.get("already_uploaded"):
+    with open(LOCAL_PATH, "rb") as f:
+        r = requests.post(resp["url"], data=resp["fields"], files={"file": (FILENAME, f)})
+        r.raise_for_status()
+```
+
+**Linux/macOS, curl (needs `jq`; builds the `-F` flags dynamically from whatever `fields` actually contains — a signer using temporary credentials adds `x-amz-security-token`, and extra policy conditions add their own fields, so a hardcoded field list drops them and S3 answers 403 on a form missing a signed field):**
+
+```bash
+if [ "$(echo "$RESPONSE_JSON" | jq -r '.already_uploaded')" != "true" ]; then
+    URL=$(echo "$RESPONSE_JSON" | jq -r '.url')
+    FIELDS=()
+    while IFS= read -r -d '' key && IFS= read -r -d '' value; do
+        FIELDS+=(-F "${key}=${value}")
+    done < <(echo "$RESPONSE_JSON" | jq -j '.fields | to_entries[] | (.key, "\u0000", .value, "\u0000")')
+    curl -sS --fail "${FIELDS[@]}" -F file=@/local/path/report.pdf "$URL"
+fi
+```
+
+**Windows PowerShell 7+ (`Invoke-RestMethod -Form` takes the whole `fields` object as a hashtable — no per-field enumeration needed at all; use `[ordered]@{}`, not a plain `@{}`, since S3 requires `file` to be the *last* form field and a plain hashtable has no guaranteed enumeration order):**
+
+```powershell
+$resp = $json | ConvertFrom-Json
+if (-not $resp.already_uploaded) {
+    $form = [ordered]@{}
+    $resp.fields.PSObject.Properties | ForEach-Object { $form[$_.Name] = $_.Value }
+    $form["file"] = Get-Item "C:\path\to\report.pdf"
+    Invoke-RestMethod -Uri $resp.url -Method Post -Form $form
+}
+```
+
+**Windows cmd.exe:** cmd.exe has no built-in JSON parsing, so there's no safe way to build the `-F` flags dynamically from whatever `fields` contains without an extra tool. Rather than hardcode a field list that silently drops fields (e.g. `x-amz-security-token` on temporary credentials, or extra policy conditions) and fail with a confusing S3 403, use the PowerShell or Python snippet above even from a cmd.exe-driven workflow.
+
+`size` must be the file's exact length in bytes, and the URL only accepts a body of exactly that size and SHA-256, for 5 minutes. Accepted extensions: pdf, txt, text, md, json, csv, xml, html, htm. `content_head_base64` — the file's first 3072 bytes, or the whole file if shorter, base64-encoded — is **required**: the tool sniffs it against the extension before requesting the URL and rejects an obvious mismatch (e.g. a renamed file) at once as `VALIDATION_ERROR`; a missing or blank one is `content_head_base64_required`. Text files must be UTF-8, because indexing reads UTF-8 only: a Latin-1 or Excel "CSV (Windows)" file is refused with a message to save it as UTF-8 (Excel: "CSV UTF-8"). Samples up to 4096 bytes are accepted and trimmed, so older snippets that send 4096 still work. A mismatch the server catches later surfaces as `state: "abandoned"` from `knowledgebase_document_status`. Idempotent — uploading the same content twice (by SHA-256) returns `already_uploaded: true` with an empty `url` and no `fields`; if that file's indexing never started or failed, the repeat queues it again.
+
+```
+knowledgebase_upload_document(
+    filename="report.pdf",
+    size=42000,
+    content_hash="<sha256 hex of the file's bytes>",
+    conversation_id="<uuid from conversation_create>",
+    content_head_base64="<base64 of the file's first 3072 bytes>",
+    agent_id="agent",
+)
+```
+
+**Response (fresh upload):**
+```json
+{
+  "datapack_id": "...",
+  "url": "https://<bucket>.s3.amazonaws.com/",
+  "fields": {"key": "...", "policy": "...", "...": "..."},
+  "key": "user/datapack/hash/report.pdf",
+  "already_uploaded": false
+}
+```
+
+**Response (identical content already uploaded):**
+```json
+{
+  "datapack_id": "...",
+  "url": "",
+  "key": "user/datapack/hash/report.pdf",
+  "already_uploaded": true,
+  "existing_filename": "report.pdf"
+}
+```
+
+After a fresh upload, POST the file to `url` yourself (see above), then save `key` (as `document_key`) and poll `knowledgebase_document_status` until `state` is terminal. S3 answers a successful POST with `204`. `400 EntityTooSmall` or `EntityTooLarge` means `size` wasn't the file's exact byte count: call the tool again with the right size and upload through the new URL. The earlier URL can never succeed (it only accepts the wrong size) and expires on its own within 5 minutes.
+
+**Common errors:**
+- `conversation_id_required` — `conversation_id` was missing or blank.
+- `datapack_id_required` — no `datapack_id` was given and no tenant default could be resolved.
+- `content_head_base64_required` — `content_head_base64` was missing or blank. Checked after the `filename`/`size`/`content_hash` `VALIDATION_ERROR` checks, but always before a URL is requested — there is no way to skip it.
+- `VALIDATION_ERROR` — missing filename, unsupported extension, missing/malformed `content_hash`, size ≤ 0, invalid or oversized `content_head_base64`, a sample shorter than `min(size, 3072)` bytes or longer than `size` (so `size` is wrong), or the sampled content doesn't match its extension.
+- `FREE_TIER_KB_STORAGE_LIMIT` / `STANDARD_TIER_KB_STORAGE_LIMIT` (`status` 402) — no room left in the storage quota. Tell the user to free space or upgrade instead of retrying: every issued URL holds its `size` against the quota until the file is registered, or for up to 15 minutes if it is never uploaded.
+
+Every error from the server also carries `status`, its HTTP status code.
+- `knowledgebase_upload_document_failed` — unexpected error (see `detail`).
+- The actual S3 POST isn't made through this tool, so its own failures (e.g. the body exceeding the cap the URL was signed under) surface to whatever made that call directly, not from this tool.
+
+---
+
+### knowledgebase_document_status
+
+**When to use:** Track a file uploaded via `knowledgebase_upload_document` from "waiting for bytes" through to indexed.
+
+```
+knowledgebase_document_status(
+    document_key="user/datapack/hash/report.pdf",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="agent"
+)
+```
+
+**Response (still indexing):**
+```json
+{
+  "document_key": "user/datapack/hash/report.pdf",
+  "filename": "report.pdf",
+  "state": "indexing",
+  "message": "The file is registered and being indexed.",
+  "document": {"status": "PROCESSING", "chunks_processed": 3}
+}
+```
+
+Poll until `state` is `completed` or `failed` (or the pre-registration terminals `abandoned`/`oversized`). `NOT_FOUND` means `document_key` is unknown to this datapack — check it was copied verbatim from the upload response. `datapack_id_required` means no `datapack_id` was given and no tenant default could be resolved.
+
+---
+
 ## Artifact Tools
 
 ### artifact_put
@@ -319,14 +545,44 @@ For large files use the `local_path` value to read the file with normal file too
 
 ## Datapack Management Tools
 
-### datapack_create / datapack_list / datapack_describe
+### datapack_create / datapack_search / datapack_list / datapack_describe
 
 ```
-datapack_create(name="analytics_prod")
-datapack_list(conversation_id="<session conversation id>")  # returns datapack_id for each datapack
-datapack_describe(datapack_id="<uuid>", include_status=True)
+datapack_create(name="analytics_prod", conversation_id="<conversation id>")
+datapack_search(conversation_id="<session conversation id>", query="analytics")    # find an id by part of the name
+datapack_search(conversation_id="<session conversation id>", name="analytics_prod") # exact name
+datapack_list(conversation_id="<session conversation id>")  # small accounts: every datapack in one array
+datapack_describe(datapack_id="<uuid>", include_status=True, conversation_id="<conversation id>")
 ```
 
+Find a datapack id with `datapack_search(query=...)`. It returns one page:
+`{"datapacks": [...], "has_more": true, "next_cursor": "<token>", "total": null}`.
+To get the next page, call it again with the same filters and
+`cursor="<next_cursor>"`. `next_cursor` is `""` on the last page, and also
+when an older server has more matches than this page but cannot continue.
+Do not send an empty cursor; ask for a narrower `query` instead. Treat the
+cursor as opaque. Pass `include_total=True` only when you must show "N of M".
+
+`datapack_list` still returns one array and is fine for an account with a
+handful of datapacks. For an account that can see more than 1000 datapacks
+(the server default limit) it returns `{"error": "too_many_datapacks", ...}`
+instead; switch to `datapack_search`. If the server has no `datapack_search`
+tool (an older server), use `datapack_list`.
+
+
+`datapack_describe` returns these counts:
+
+| Field | Meaning |
+|---|---|
+| `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 (for debugging retrieval) |
+| `shared_knowledge_count` | `collective_memory_count + knowledge_base_file_count`; `null` when the file count is `null` |
+
+`knowledge_count` is a deprecated alias of `knowledge_chunk_count`. Neither `datapack_search` nor `datapack_list` computes counts; call `datapack_describe` for them.
+
 ### datapack_update / datapack_delete
 
 `datapack_update` renames a datapack, edits its description, and/or opts it in/out of conversation-search embedding. `name`, `description`, and `conversation_search_opt_out` are all optional; pass at least one. If none are provided the tool returns `nothing_to_update` without hitting the API.
@@ -334,11 +590,11 @@ datapack_describe(datapack_id="<uuid>", include_status=True)
 The server refuses to rename the caller's `meko_default_datapack` — a rename call against that datapack returns `"meko_default_datapack cannot be renamed"`. Description edits on the default datapack are still allowed. Passing `description=""` does NOT clear an existing description; clearing is not supported via MCP. Conversation-search embedding is on by default; `conversation_search_opt_out=True` stops future turns from being indexed (already-cached turns are unaffected) and is restricted to the datapack's owner or a maintainer. This is best-effort, not a hard guarantee — a transient database error on the live embed path's opt-out check fails open, so a turn can occasionally still get embedded for an opted-out datapack.
 
 ```
-datapack_update(datapack_id="<uuid>", name="renamed-datapack")
-datapack_update(datapack_id="<uuid>", description="new description")
-datapack_update(datapack_id="<uuid>", name="x", description="y")
-datapack_update(datapack_id="<uuid>", conversation_search_opt_out=True)
-datapack_delete(datapack_id="<uuid>")  # Irreversible!
+datapack_update(datapack_id="<uuid>", name="renamed-datapack", conversation_id="<conversation id>")
+datapack_update(datapack_id="<uuid>", description="new description", conversation_id="<conversation id>")
+datapack_update(datapack_id="<uuid>", name="x", description="y", conversation_id="<conversation id>")
+datapack_update(datapack_id="<uuid>", conversation_search_opt_out=True, conversation_id="<conversation id>")
+datapack_delete(datapack_id="<uuid>", conversation_id="<conversation id>")  # Irreversible!
 ```
 
 ### Agent and knowledge-base management (NOT MCP — control-plane only)
@@ -348,4 +604,4 @@ Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/li
 - REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (agents), `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases` (KB sources).
 - Or the Meko Cloud UI at `cloud.mekodata.ai` → Datapacks → agents / knowledge-bases.
 
-KB ingestion specifically lives in the UI today: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). Agents querying a populated index use `knowledgebase_search` — see `tools-rag-workflow.md`.
+Uploading a *file* into an existing KB is not part of that lifecycle restriction — use `knowledgebase_upload_document` (see above) rather than the UI for anything driven from MCP. Agents querying a populated index use `knowledgebase_search`, and can remove a single uploaded file with `knowledgebase_delete_document` — see `tools-rag-workflow.md`.

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

@@ -14,7 +14,8 @@ Datapacks are isolated workspaces — each has its own memory store and knowledg
 ## How to obtain a datapack_id
 
 - From `datapack_create` response (`"datapack_id"` field; `"datapack_name"` is also returned)
-- From `datapack_list` (each entry has `"datapack_id"` and `"datapack_name"`)
+- From `datapack_search(query="<part of the name>")` or `datapack_search(name="<exact name>")`: each row in `"datapacks"` has `"datapack_id"` and `"datapack_name"`. Page with `cursor="<next_cursor>"` only when that value is non-empty. An empty `next_cursor` means stop and narrow with `query`.
+- From `datapack_list` on a small account, or on an older server without `datapack_search` (each entry has `"datapack_id"` and `"datapack_name"`). An account that can see more than 1000 datapacks (the server default limit) gets `too_many_datapacks` from an unfiltered `datapack_list`; use `datapack_search`.
 - From `datapack_describe` response (same field names)
 
 ## Datapack lifecycle
@@ -27,13 +28,15 @@ datapack_create(name="sales_analytics",
 -- Returns: {"datapack_id": "dp-uuid-123", "datapack_name": "sales_analytics", ...}
 ```
 
-Provisioning agents and knowledge-base sources on a new datapack is **not** MCP-exposed. Use the Meko control plane:
+Provisioning agents and knowledge-base *sources* (registering/indexing a new source against a datapack) is **not** MCP-exposed. Use the Meko control plane:
 
 - **UI**: `app.mekodata.ai` → Datapacks → select datapack → Agents / Knowledge Bases
-- **REST**: `POST /datapacks/:datapack_id/agents`, `POST /datapacks/:datapack_id/knowledge-bases` (and the Add Knowledge UI for file uploads)
+- **REST**: `POST /datapacks/:datapack_id/agents`, `POST /datapacks/:datapack_id/knowledge-bases`
 
 If the user asks to set those up mid-session, point them at the control plane rather than inventing an MCP call that will fail.
 
+Uploading a *file* into an existing KB is a different, already-MCP-exposed operation — use `knowledgebase_upload_document` (see `tools-cookbook.md`) rather than routing the user to the Add Knowledge UI.
+
 ### Targeting a specific datapack on subsequent calls
 
 ```
@@ -50,7 +53,7 @@ Delete child resources first (agents and KB sources via the control plane), then
 ```
 # Control-plane (REST or UI): DELETE /datapacks/:datapack_id/knowledge-bases
 # Control-plane (REST or UI): DELETE /datapacks/:datapack_id/agents/sales_agent
-datapack_delete(datapack_id="dp-uuid-123")  # MCP-exposed, destructive, irreversible
+datapack_delete(datapack_id="dp-uuid-123", conversation_id="<conversation id>")  # MCP-exposed, destructive, irreversible
 ```
 
 ## Common mistake: forgetting datapack_id on memory tools

package/assets/skills/meko-mcp-tools/references/tools-known-limitations.md

@@ -12,6 +12,10 @@ These are current limitations of the Meko MCP tools. Know them upfront to avoid
 | Standard | 5,000 | 5,000 | 30,000 |
 | Pro / Enterprise | uncapped | uncapped | uncapped |
 
+The Free tier also caps `context_search` and `conversation_add_message` at 1,000 calls each. Embedding turns into the conversation-search cache has its own cap: 2,000 turns on Free and 10,000 on Pro; Standard and Enterprise are uncapped. When that cap is reached, `conversation_add_message` still stores the turn and reports `conversation_search_skipped: "quota_exceeded"`; the turn just won't appear in `context_search`'s conversation bucket.
+
+A quota error can arrive with HTTP 403. It is not an authentication failure; don't reconfigure credentials because of it.
+
 When the cap is reached the tool returns an error object with code `free_tier_limit_reached` (on every tier; the `tier` field names the capped tier) and **no `results` key**.
 
 - **Do not retry** — the cap is lifetime.
@@ -24,9 +28,23 @@ One call returns roughly the **20 most recent rows**; the response's `total` rep
 
 ## run_id is a read/delete filter on the conversation id, not a write key
 
-`memory_search(run_id=<conversation_id>)` and the memory delete tools filter on the row's `meko_conversation_id`, so passing a conversation id there correctly scopes the call to that one conversation — a supported, reliable way to read a single conversation's memories (read/write/delete scoping was made consistent in MEKO-473/MEKO-474, #271). The one gotcha is on the write side: `memory_add`'s own `run_id` is Langfuse trace metadata only and is **not** persisted as the row's conversation id, so a row written with `memory_add(run_id=X)` is not findable via `memory_search(run_id=X)`. Scope writes with `conversation_id`, then filter the matching read by that same id.
+`memory_search(run_id=<conversation_id>)` and `memory_delete_all(run_id=<conversation_id>)` filter on the row's `meko_conversation_id`, so passing a conversation id there correctly scopes the call to that one conversation — a supported, reliable way to read a single conversation's memories (read/write/delete scoping was made consistent in MEKO-473/MEKO-474, #271). The one gotcha is on the write side: `memory_add`'s own `run_id` is Langfuse trace metadata only and is **not** persisted as the row's conversation id, so a row written with `memory_add(run_id=X)` is not findable via `memory_search(run_id=X)`. Scope writes with `conversation_id`, then filter the matching read by that same id.
+
+`memory_get_all` accepts `run_id` but ignores it, and `conversation_list` has no `run_id`.
+
+## memory_delete_all is agent-scoped; memory reads are not
+
+`memory_search` and `memory_get_all` return every agent's rows for the user. `memory_delete_all` deletes only rows in the `agent_id` you pass, and an omitted `agent_id` means the `meko_agent` bucket. A `memory_search(run_id=X)` preview can therefore list rows that `memory_delete_all(run_id=X)` leaves in place. To clear rows written by several agents, delete them by id with `memory_delete_by_id`, or call `memory_delete_all` once per `agent_id` shown in the preview.
+
+## Viewers can read but not write
+
+On a datapack shared with you as a viewer, every conversation and memory write returns `read_only_access` and writes nothing: `conversation_create`, `conversation_add_message`, `conversation_update`, `memory_add`, `memory_update`, `memory_promote`, `artifact_put`, and `track_token_usage`. You can still delete your own memories with `memory_delete_by_id` and `memory_delete_all`, and delete a conversation you started. Searches work as for any other role. `context_search` covers every member's conversations, but for a viewer its conversation results and `conversation_get` return `user_id: null`, so they don't say who wrote a turn. Automatic capture holds a viewer's session and reports `read_only_access` at the next session start.
 
-## No delete tools for RAG artifacts
+## Promoted memories are read-only through MCP
+
+`memory_update` and `memory_delete_by_id` return `memory_is_promoted` for a memory that has been promoted to shared knowledge. Edit or remove promoted content in the Cloud UI Learnings tab.
+
+## No MCP tools for index / source / pipeline lifecycle
 
 There are no MCP tools to:
 - Delete a vector index
@@ -34,13 +52,15 @@ There are no MCP tools to:
 - Clear stuck work queue entries
 - Reset a failed pipeline
 
-KB-source deletion happens via the Meko control plane (REST: `DELETE /datapacks/:datapack_id/knowledge-bases`, or the UI), which removes the registration from the Meko API — but does **not** touch the actual `dist_rag` index, source records, or vector data in the datapack's database.
+The one exception is a single uploaded **file**: `knowledgebase_delete_document` removes that file's chunks and metadata. KB-**source** deletion (the registered source, not one file) happens via the Meko control plane (REST: `DELETE /datapacks/:datapack_id/knowledge-bases`, or the UI): it unregisters the source from the Meko API but does **not** touch the actual `dist_rag` index, source records, or vector data in the datapack's database.
 
 **Workaround:** For stuck or failed indexes, create a new index with a different name. Stale indexes remain in the database until manually cleaned up by an admin.
 
-## RAG ingestion is UI-only
+## KB index/source management is UI-only
+
+Manually creating a vector index, adding a source to an existing one, or polling raw build status is not exposed via MCP. Use the Cloud UI for those (Datapack → Actions → Add Knowledge).
 
-KB ingestion (creating an index, adding sources, polling build status) is not exposed via MCP. Documents go in through the Cloud UI's **Add Knowledge** flow (Datapack → Actions → Add Knowledge) — PDF/TXT/MD/JSON/MP4 up to 5 MB each, 10 per batch.
+**Adding a file** is a registered MCP tool: call `knowledgebase_upload_document` directly (accepted extensions PDF/TXT/MD/JSON/CSV/XML/HTML, up to 5 MB Free / 50 MB Standard / 60 MB Pro+ per file) to get a presigned URL, then POST the bytes to it yourself; Meko registers and indexes the file once it lands, so no separate index-management call is needed. Confirm with the user first, because every datapack member can read the knowledge base. The Cloud UI's **Add Knowledge** flow (10 files per batch) remains the human-facing path for the same upload.
 
 To **query** a built index, use `knowledgebase_search` — it returns both uploaded documents and memories the user promoted from the Learnings tab.
 
@@ -56,7 +76,7 @@ It works **poorly** for:
 - Data dictionaries — only partial information extracted
 - Structured schemas — relationships between fields lost
 
-**Structured data is not natively supported via MCP.** The options are:
+**Don't store structured data as memories.** The options are:
 
 1. **Write a single narrative summary** as a memory — one call, not row-by-row:
    ```
@@ -65,13 +85,21 @@ It works **poorly** for:
        conversation_id="<session conversation_id>",
        text="Customer Complaints dataset has fields: Complaint ID (int PK), Date Submitted (date), Product (text, e.g. Mortgage/Credit Card), Sub-product (text), Issue (text), Company Response (text), State (text, 2-letter code), ZIP Code (text)")
    ```
-2. **Upload the schema doc** through the Cloud UI's **Add Knowledge** flow (Datapack → Actions → Add Knowledge). Accepts PDF/TXT/MD/JSON — convert CSV to MD or JSON first. That makes it queryable via `knowledgebase_search`.
-3. **Tell the user** that structured-data storage via MCP isn't supported and let them decide how to proceed.
+2. **Upload the file itself to the knowledge base** with `knowledgebase_upload_document` — `.csv`, `.json` and the other accepted types go in as they are — and query it with `knowledgebase_search`. (The Cloud UI's **Add Knowledge** flow does the same for a person.)
 
 Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
 
-## No semantic search over conversation content
+## Conversation search covers embedded turns only
+
+`context_search` searches past conversation turns by meaning in its `conversation` bucket. Only turns embedded into the conversation-search cache are searchable. Turns are embedded by default, except when:
+
+- the datapack opted out with `datapack_update(datapack_id=..., conversation_search_opt_out=True, conversation_id=...)`;
+- the account hit the embedding quota (`conversation_search_skipped: "quota_exceeded"`); or
+- the turn was too short to carry content (the server skips trivial turns); or
+- the turn was stored before conversation search was enabled.
+
+To find a conversation by other attributes, browse with `conversation_list` and inspect candidates with `conversation_get`.
 
-Semantic (meaning-based) search across stored conversation content is not part of the public tool surface today. To find a past conversation, browse with `conversation_list` (by datapack) and inspect candidates with `conversation_get`.
+## Very long conversations can't be read back
 
-For finding past knowledge by meaning, `memory_search` remains the most reliable path — which is why storing key facts via `memory_add` alongside conversations is important.
+When a conversation's trace grows too large for Langfuse, `conversation_get` and `conversation_update` return `{"error": "not_found", "detail": "Conversation <id> not found"}` or time out for that conversation, even though `conversation_add_message` and `conversation_delete` still work. Servers without the MEKO-714 fix instead return `not_found` from `conversation_add_message` on these conversations. If read-back or a write fails with `not_found` on a long conversation that you know exists, report the failure as a server-side limit on that conversation. Don't recreate the conversation under the same id or replay its messages; that makes the trace larger.

package/assets/skills/meko-mcp-tools/references/tools-memory-vs-conversation.md

@@ -26,22 +26,26 @@ memory_search(query="What plan does Alice have?", agent_id="support_bot")
 Conversations are backed by Langfuse sessions and traces. They preserve full structure: who said what, in what order, with what reasoning.
 
 ```
-conversation_create(agent_id="support_bot", title="Pricing discussion")
+conversation_create(agent_id="support_bot", title="Pricing discussion",
+    datapack_id="<uuid from datapack_search>")
 -- Returns: {"id": "conv-uuid-here"}
 
 conversation_add_message(conversation_id="conv-uuid-here", agent_id="support_bot",
+    datapack_id="<uuid from datapack_search>",
     input="What are your pricing tiers?",
     output="We offer Starter ($10/mo), Pro ($50/mo), and Enterprise (custom).",
     reasoning="Retrieved pricing page data. No special discounts apply.")
 ```
 
+`datapack_id` is required for both calls whenever no server-side default resolves for the caller. Omitting it in that state returns `{"error": "datapack_id_required"}` and persists nothing.
+
 ## Decision Matrix
 
 | Signal | Tool |
 |--------|------|
 | "remember that...", "note that...", "keep in mind..." | `memory_add` |
 | "store this conversation", "save this chat" | `conversation_create` + `conversation_add_message` |
-| "what do you know about X?", "recall..." | `memory_search` |
+| "what do you know about X?", "recall..." | `context_search` |
 | "show me our past conversation about..." | `conversation_list` + `conversation_get` |
 | "the user prefers...", "their budget is..." | `memory_add` |
 | "save my query and your response" | `conversation_add_message` |
@@ -81,7 +85,7 @@ Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the
 - **Personal memories** — written by `memory_add`. The `agent_id` records the writer but does not restrict reads; memories are scoped **per-user**, so any of that user's agents can read them via MCP, and no other user can.
 - **Team-shared Shared Knowledge** — arrives two ways:
   1. An agent calls `memory_promote` for exact, user-confirmed memory UUIDs, or the user promotes them from the Cloud UI's Learnings tab. Promotion moves the memories into shared knowledge, strips `user_id`, preserves originating `agent_id` as provenance, and evicts the private mem0 records.
-  2. The user uploads a file via Datapack → Actions → **Add Knowledge** in the Cloud UI. PDF/TXT/MD/JSON/MP4 up to 5MB each.
+  2. The user uploads a file via Datapack → Actions → **Add Knowledge** in the Cloud UI. PDF/TXT/MD/JSON/CSV/XML/HTML up to 5MB (Free) / 50MB (Standard) / 60MB (Pro+) each.
 
   Both show up in `knowledgebase_search`, tagged `metadata_filters.source: "memory"` vs other values so the agent can distinguish provenance in responses.
 
@@ -89,7 +93,7 @@ Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the
 
 ### When the user asks "what do you know about X?"
 
-A full sweep is two calls: `memory_search` (all your personal memories, every agent — no per-agent fan-out) then `knowledgebase_search` (team-shared knowledge). When you answer, name which surface each finding came from, so the user knows why something is or isn't there.
+Call `context_search`. One call returns your personal memories (every agent, no per-agent fan-out), team-shared knowledge, and matching past-conversation turns from anyone on the datapack. If the memory or KB bucket is empty, confirm with `memory_search` or `knowledgebase_search` before saying nothing is there, because `context_search` returns an empty list for a failed source. When you answer, name which surface each finding came from, so the user knows why something is or isn't there.
 
 ## Memory limitations for structured data
 
@@ -98,7 +102,7 @@ A full sweep is two calls: `memory_search` (all your personal memories, every ag
 There is no MCP-side "just put it in a database table" option — raw SQL access isn't part of the MCP surface. Workarounds:
 
 1. **Write a single narrative summary** as a memory: `"The Customer Complaints dataset has fields: Complaint ID (int), Date Submitted (date), Product (text), Sub-product (text), Issue (text)..."` — one call, not row-by-row.
-2. **Suggest the user upload the file** via the Cloud UI's Add Knowledge flow if it's a document (CSV files aren't in the supported list — PDF/TXT/MD/JSON/MP4 are; for CSV, convert to MD or JSON first).
+2. **Suggest the user upload the file** via the Cloud UI's Add Knowledge flow if it's a document (PDF/TXT/MD/JSON/CSV/XML/HTML are supported).
 3. **Never ingest CSV row-by-row** into memory — each row becomes a fragmented fact with lost context.
 
 ## Memory Storage: automatic, not proactive
@@ -112,7 +116,7 @@ On Claude Code, do **not** proactively `memory_add` facts the user states — ca
 
 ## Automatic Conversation Capture
 
-The plugin captures conversations via three mechanisms — a periodic checkpoint (~10 min), a PreCompact hook, and a SessionEnd hook — storing the full transcript verbatim (user prompts as `input`, assistant text as `output`, tool calls and results as `reasoning`).
+The plugin captures conversations via three mechanisms — a periodic checkpoint (~10 min), a PreCompact hook, and a SessionEnd hook — storing the full transcript verbatim (user prompts as `input`, assistant text as `output`, tool calls and results as `reasoning`). Skill bodies, background-task notifications, and subagent reports that Claude Code writes into the transcript go to `reasoning` of the turn they belong to, never to `input`. A typed `/skill args` is captured with that command as its `input`.
 
 Each message's seed is `<conversation_id>:<user_message_uuid>`; all three mechanisms derive the same deterministic trace ID from it, so overlapping captures are idempotent. A shared watermark file tracks what has been saved.