@yugabytedb/meko-mcp 2.2.0 → 2.5.0

package/assets/skills/meko-mcp-tools-desktop/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="claude_desktop",
+    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 call. For Claude Desktop that's `claude_desktop` for normal attribution, or `meko_agent` when writing genuinely cross-project facts. Writes retain that attribution, while personal memory reads span all of this user's agents.
@@ -16,6 +57,7 @@ Every tool example below shows the correct parameters, expected response, and co
 
 ```
 memory_add(agent_id="claude_desktop",
+    conversation_id="<id from conversation_create>",
     text="Remember: deploy scripts must be run from the repo root, never a subdir.")
 ```
 
@@ -24,15 +66,9 @@ memory_add(agent_id="claude_desktop",
 {"results": [{"id": "mem-uuid-123", "memory": "User Amiram is VP of Product at YugabyteDB. Prefers concise responses."}]}
 ```
 
-**With user scoping:**
-```
-memory_add(agent_id="agent", user_id="amiram",
-    text="Prefers Python for backend, Go for infrastructure.")
-```
-
 **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)
 
 **Common errors:**
 - `syntax error at or near "-"` — legacy error from the pre-multi-tenancy schema when `agent_id` became part of a PostgreSQL identifier. No longer applies on Cloud (agent_id is a TEXT column value, any string is accepted). If you hit it on a deployment that still uses the old schema, use underscores instead of hyphens.
@@ -46,35 +82,32 @@ memory_add(agent_id="agent", user_id="amiram",
 
 **Cross-conversation discovery.** `memory_search` returns hits across every stored conversation for the `(datapack_id, user_id)` pair, across all agents (the tool intentionally passes `meko_agent_id=None` to mem0, so the `agent_id` argument scopes the trace but does not filter 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. Pass `run_id` on the search itself to narrow to a single conversation up front.
 
-**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.
 
 ```
-memory_search(query="What programming language does the team use?", agent_id="agent")
+memory_search(query="What programming language does the team use?", agent_id="claude_desktop", conversation_id="<id>")
 ```
 
 **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", limit=5)
+memory_search(query="user preferences", agent_id="claude_desktop", conversation_id="<id>", limit=5)
 ```
 
 ---
 
 ### memory_get_all
 
-**When to use:** List everything stored for an agent. 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")
-```
-
-**With user scoping:**
-```
-memory_get_all(agent_id="agent", user_id="amiram")
+memory_get_all(agent_id="claude_desktop", conversation_id="<id>")
 ```
 
 ---
@@ -82,7 +115,7 @@ memory_get_all(agent_id="agent", user_id="amiram")
 ### memory_get_by_id
 
 ```
-memory_get_by_id(memory_id="mem-uuid-123", agent_id="agent")
+memory_get_by_id(memory_id="mem-uuid-123", agent_id="claude_desktop", conversation_id="<id>")
 ```
 
 ---
@@ -92,7 +125,7 @@ memory_get_by_id(memory_id="mem-uuid-123", agent_id="agent")
 **When to use:** Overwrite a specific memory's text. Requires the memory UUID.
 
 ```
-memory_update(memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="agent")
+memory_update(memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="claude_desktop", conversation_id="<id>")
 ```
 
 ---
@@ -100,17 +133,19 @@ memory_update(memory_id="mem-uuid-123", text="Updated: Team uses Go for all new
 ### memory_delete_by_id
 
 ```
-memory_delete_by_id(memory_id="mem-uuid-123", agent_id="agent")
+memory_delete_by_id(memory_id="mem-uuid-123", agent_id="claude_desktop", conversation_id="<id>")
 ```
 
+`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")
+memory_delete_all(agent_id="claude_desktop", conversation_id="<id>")
 ```
 
 ---
@@ -142,10 +177,13 @@ On 403, authentication, or permission failure, report the error and stop — do
 **When to use:** Start storing a multi-turn exchange. Do this when the session contains valuable dialog worth preserving.
 
 ```
-conversation_create(agent_id="agent", user_id="amiram",
-    title="Debugging the auth middleware")
+conversation_create(agent_id="claude_desktop",
+    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"}
@@ -186,8 +224,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)
@@ -216,7 +254,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.
 
@@ -244,6 +282,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.
+
+**`content_hash` and `content_head_base64` are both computed on the caller's own device, from the file's real bytes — this tool never computes either for you.** `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="claude_desktop",
+)
+```
+
+**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="claude_desktop"
+)
+```
+
+**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
@@ -323,24 +539,54 @@ For large files use `local_path` to read the file. S3 URLs are never exposed.
 
 ## 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="<this conversation's 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="<this conversation's id>", query="analytics")    # find an id by part of the name
+datapack_search(conversation_id="<this conversation's id>", name="analytics_prod") # exact name
+datapack_list(conversation_id="<this conversation's 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. At least one of `name` / `description` / `conversation_search_opt_out` must be provided (or the tool returns `nothing_to_update`). The server refuses to rename `meko_default_datapack` — the error is `"meko_default_datapack cannot be renamed"`. Passing `description=""` does NOT clear an existing description. `conversation_search_opt_out=True` stops future turns from being indexed 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)
@@ -350,4 +596,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-desktop/references/tools-known-limitations.md

@@ -2,7 +2,7 @@
 
 These are current limitations of the Meko MCP tools. Know them upfront to avoid wasted tool calls.
 
-## No delete tools for RAG artifacts
+## No MCP tools for index / source / pipeline lifecycle
 
 There are no MCP tools to:
 - Delete a vector index
@@ -10,13 +10,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
 
-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.
+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).
+
+**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.
 
@@ -32,7 +34,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:
    ```
@@ -41,8 +43,7 @@ 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.
 
@@ -56,8 +57,29 @@ The skill description is tuned to its 1024-char ceiling; broadening it further d
 2. **Server-side guidance** — the `agent_id` tool docstrings and the server's connect-time instructions name `claude_desktop` as this client's bucket, so even a skill-less tool-search call avoids the wrong-bucket (`claude_code`) write.
 3. Nothing is lost when the *user* explicitly recalls or saves — only passive capture of in-passing facts is best-effort.
 
-## No semantic search over conversation content
+## 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. On Claude Desktop there are no capture hooks: when your own `conversation_add_message` call returns `read_only_access`, stop recording turns for this datapack and tell the user.
+
+## 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.
+
+## 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-desktop/references/tools-memory-vs-conversation.md

@@ -11,10 +11,10 @@
 Memory is backed by pgvector. Search is hybrid: semantic similarity, keyword matching, and a boost for memories that mention the entities named in your query (people, projects, tools). It retrieves relevant facts by meaning, not by conversation order.
 
 ```
-memory_add(agent_id="support_bot",
-    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.", user_id="alice_123")
+memory_add(agent_id="claude_desktop", conversation_id="<id>",
+    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.")
 
-memory_search(query="What plan does Alice have?", agent_id="support_bot")
+memory_search(query="What plan does Alice have?", agent_id="claude_desktop", conversation_id="<id>")
 ```
 
 ## Use `conversation_create` + `conversation_add_message` when storing:
@@ -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", user_id="alice_123", title="Pricing discussion")
+conversation_create(agent_id="claude_desktop", 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",
+conversation_add_message(conversation_id="conv-uuid-here", agent_id="claude_desktop",
+    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 @@ One `memory_search` already spans this user's memories across all agents; no per
 - **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 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,14 +93,13 @@ One `memory_search` already spans this user's memories across all agents; no per
 
 ### When the user asks "what do you know about X?"
 
-A full sweep is two calls (budget for it — each is 2-6 seconds):
+Call `context_search`:
 
 ```
-memory_search(agent_id="claude_desktop", query="X", conversation_id=..., ...)
-knowledgebase_search(agent_id="<anything>", datapack_id="<uuid>", query="X", conversation_id=..., ...)
+context_search(agent_id="claude_desktop", query="X", conversation_id=..., datapack_id="<uuid>")
 ```
 
-The single `memory_search` includes everything this user and their other agents wrote in the datapack.
+Its memory bucket includes everything this user and their other agents wrote in the datapack. The KB bucket holds team-shared knowledge, and the conversation bucket holds matching past 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, be explicit about scope so the user knows why something is or isn't there:
 
@@ -111,7 +114,7 @@ When you answer, be explicit about scope so the user knows why something is or i
 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: capture the turn, don't proactively memory_add
@@ -146,6 +149,7 @@ The full transcript including:
 - **Assistant responses** — all text blocks (the `output` field)
 - **Tool calls** — tool name + input parameters (the `reasoning` field)
 - **Tool results** — output from tool executions (appended to `reasoning`)
+- **Injected context** — skill bodies, background-task notifications, and subagent reports that the client writes into the transcript (appended to `reasoning` of the turn they belong to, never used as `input`)
 
 This is more than just text — tool calls and results are critical context for session replay, cross-agent sharing, and compaction.