@yugabytedb/meko-mcp 1.2.0 → 2.1.0

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

@@ -1,113 +1,22 @@
 # Tool Cookbook — Complete Usage Examples
 
-Every tool example below shows the correct parameters, expected response, and common errors. Use `scope="read"` for reads and `scope="write"` for writes — never `"all"` or any other value.
+Every tool example below shows the correct parameters, expected response, and common errors.
 
-> **Note on `agent_id` in the examples below.** The string `"agent"` appears in these examples as a placeholder shorthand; it is NOT a required constant. Substitute **your** client's bucket: for Claude Desktop, the bare client name `claude_desktop`; for Claude Code/Cursor, `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts (user identity, global preferences) write/read with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
->
-> **Note on availability on Cloud.** The `db_*` tools and the three KB ingestion tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) return `{"error": "not_available"}` on Cloud Meko today. This cookbook keeps their examples for reference but you can't call them from a Cloud client.
-
----
-
-## Database Tools
-
-### db_summarize_database
-
-**When to use:** First thing in a session to understand what's in the database. Prefer this over writing your own `information_schema` query.
-
-```
-db_summarize_database(scope="read", schema="public")
-```
-
-**Response:**
-```json
-[
-  {
-    "table_name": "customers",
-    "schema": [
-      {"column_name": "id", "data_type": "uuid"},
-      {"column_name": "name", "data_type": "text"}
-    ],
-    "row_count": 1523
-  }
-]
-```
-
-**With datapack:**
-```
-db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
-```
-
-**Common errors:**
-- `Insufficient scope: 'all'` — Use `scope="read"`, not `"all"`
-- Empty result — The schema may not exist, try `schema="public"`
-
----
-
-### db_run_read_only_query
-
-**When to use:** Any SELECT query. Always add `LIMIT` on exploratory queries.
-
-```
-db_run_read_only_query(scope="read", query="SELECT id, name FROM customers LIMIT 10")
-```
-
-**Response:** JSON array of row objects.
-```json
-[{"id": "abc-123", "name": "Alice"}, {"id": "def-456", "name": "Bob"}]
-```
-
-**Best practices:**
-- Always use `LIMIT` on unfamiliar tables to avoid flooding context
-- Select specific columns rather than `SELECT *` to keep responses small
-- For non-public schemas: `SELECT * FROM analytics."monthly_revenue" LIMIT 5`
-- Escape single quotes in values: `WHERE name = 'O''Brien'`
-
-**Common errors:**
-- `cannot execute INSERT in a read-only transaction` — Use `db_run_write_query` for writes
-- `permission denied for table X` — MCP user lacks access to this table (server-side config issue, not fixable via MCP)
-- `connection already closed` — Retry once. If persistent, the DB pool is unhealthy.
-
----
-
-### db_run_write_query
-
-**When to use:** INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE INDEX.
-
-```
-db_run_write_query(scope="write", query="INSERT INTO customers (id, name) VALUES ('abc-123', 'Alice')")
-```
-
-**Response:**
-```json
-{"rows_affected": 1}
-```
-
-**One statement per call.** This is wrong:
-```
-db_run_write_query(scope="write", query="CREATE TABLE a (id INT); CREATE TABLE b (id INT);")
-```
-Split into two separate calls.
-
-**Bulk inserts:** Maximum 1000 rows per INSERT VALUES. For more, use `INSERT ... SELECT` or batch into multiple calls.
-
-**Common errors:**
-- `Multi-statement queries not allowed` — Send one statement per call
-- `DROP SCHEMA is not allowed` — See `tools-write-guardrails.md` for blocked operations
-- `'dict' object has no attribute 'guardrail_config'` — Known server bug in some deployments. Write operations may be unavailable.
+> **Note on `agent_id` in the examples below.** The string `"agent"` appears in these examples as a placeholder shorthand; it is NOT a required constant. Substitute **your** client's value: for Claude Desktop, use `claude_desktop`; for Claude Code/Cursor, use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Write genuinely cross-project facts with `agent_id="meko_agent"`. On memory reads, `agent_id` attributes the trace but does not filter results. See `tools-agent-id-conventions.md`.
 
 ---
 
 ## Memory Tools
 
-**Critical:** Pass your session's `agent_id` on every memory call. For Claude Desktop that's `claude_desktop` for client-personal context, or `meko_agent` for genuinely cross-project facts (user identity, global preferences). Personal writes are scoped strictly by `agent_id` — other agents won't see your writes on personal reads unless they pass the same exact value.
+**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.
 
 ### memory_add
 
-**When to use:** Store facts, preferences, user profile info, org conventions, corrections, learnings. Use proactively — don't wait for the user to ask.
+**When to use:** NOT for facts the user states — those are captured when you post the turn with `conversation_add_message` and the server extracts them. Reserve `memory_add` for the three cases per-turn capture can't reach: (1) the user explicitly says "remember this"; (2) a durable fact only in your output or a tool result, never in a user turn; (3) overwriting a negated/corrected fact (pair with `memory_delete_by_id`, since extraction is additive).
 
 ```
-memory_add(scope="write", agent_id="agent",
-    text="User Amiram is VP of Product at YugabyteDB. Prefers concise responses.")
+memory_add(agent_id="claude_desktop",
+    text="Remember: deploy scripts must be run from the repo root, never a subdir.")
 ```
 
 **Response:**
@@ -117,14 +26,13 @@ memory_add(scope="write", agent_id="agent",
 
 **With user scoping:**
 ```
-memory_add(scope="write", agent_id="agent", user_id="amiram",
+memory_add(agent_id="agent", user_id="amiram",
     text="Prefers Python for backend, Go for infrastructure.")
 ```
 
 **What NOT to store via memory_add:**
-- CSV rows or tabular data (use `db_run_write_query` instead)
 - Full conversations (use `conversation_create` + `conversation_add_message`)
-- Large documents (use knowledge base ingestion)
+- Large documents (use 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.
@@ -136,8 +44,10 @@ memory_add(scope="write", agent_id="agent", user_id="amiram",
 
 **When to use:** Find relevant memories by meaning. Always try this before asking the user to repeat information.
 
+**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.
+
 ```
-memory_search(scope="read", query="What programming language does the team use?", agent_id="agent")
+memory_search(query="What programming language does the team use?", agent_id="agent")
 ```
 
 **Response:**
@@ -147,7 +57,7 @@ memory_search(scope="read", query="What programming language does the team use?"
 
 **With limit:**
 ```
-memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
+memory_search(query="user preferences", agent_id="agent", limit=5)
 ```
 
 ---
@@ -157,12 +67,12 @@ memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
 **When to use:** List everything stored for an agent. Useful at session start to load context.
 
 ```
-memory_get_all(scope="read", agent_id="agent")
+memory_get_all(agent_id="agent")
 ```
 
 **With user scoping:**
 ```
-memory_get_all(scope="read", agent_id="agent", user_id="amiram")
+memory_get_all(agent_id="agent", user_id="amiram")
 ```
 
 ---
@@ -170,7 +80,7 @@ memory_get_all(scope="read", agent_id="agent", user_id="amiram")
 ### memory_get_by_id
 
 ```
-memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
+memory_get_by_id(memory_id="mem-uuid-123", agent_id="agent")
 ```
 
 ---
@@ -180,7 +90,7 @@ memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
 **When to use:** Overwrite a specific memory's text. Requires the memory UUID.
 
 ```
-memory_update(scope="write", 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="agent")
 ```
 
 ---
@@ -188,19 +98,39 @@ memory_update(scope="write", memory_id="mem-uuid-123", text="Updated: Team uses
 ### memory_delete_by_id
 
 ```
-memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="agent")
+memory_delete_by_id(memory_id="mem-uuid-123", agent_id="agent")
 ```
 
 ---
 
 ### memory_delete_all
 
-**Destructive. Requires admin scope.** Deletes all memories for the agent.
+**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.
+
+```
+memory_delete_all(agent_id="agent")
+```
+
+---
+
+### memory_promote
+
+**When to use:** The user asks to share or promote specific memories to the team's knowledge base — the MCP counterpart of the Cloud UI's "Promote to Knowledge" flow. One-way: promoted memories become team-visible via `knowledgebase_search` and are evicted from the private memory store. Requires the caller to be a datapack **owner or maintainer**; viewers and contributors get a 403 permission error.
 
 ```
-memory_delete_all(scope="admin", agent_id="agent")
+memory_promote(memory_ids=["mem-uuid-123", "mem-uuid-456"],
+    agent_id="claude_desktop", conversation_id="<uuid from conversation_create>")
 ```
 
+**Response:**
+```json
+{"inserted_ids": ["mem-uuid-123"], "updated_ids": ["mem-uuid-456"], "not_found_ids": []}
+```
+
+Get exact UUIDs from the `id` field of `memory_search` / `memory_get_all` results; never use graph relation IDs. Before the call, show the user each exact memory and UUID, explain that promotion is team-visible, one-way, and evicts the private records, then obtain explicit confirmation for those candidates. Pass the active `conversation_id` and intended `agent_id` / `datapack_id`; on legacy schemas that expose `scope`, use `write`, not `admin`.
+
+On 403, authentication, or permission failure, report the error and stop — do not escalate scope, change datapacks, or alter identity. After a successful call, `knowledgebase_search` may verify shared visibility, but it is not a rollback mechanism.
+
 ---
 
 ## Conversation Tools
@@ -210,7 +140,7 @@ memory_delete_all(scope="admin", agent_id="agent")
 **When to use:** Start storing a multi-turn exchange. Do this when the session contains valuable dialog worth preserving.
 
 ```
-conversation_create(scope="write", agent_id="agent", user_id="amiram",
+conversation_create(agent_id="agent", user_id="amiram",
     title="Debugging the auth middleware")
 ```
 
@@ -225,8 +155,10 @@ conversation_create(scope="write", agent_id="agent", user_id="amiram",
 
 **When to use:** Add a user/assistant exchange to an existing conversation. **All fields must be verbatim** — never summarize or rephrase.
 
+Leave `index_for_search` at its default (`False`). Conversation-cache embedding is currently a WorkbenchLM-only feature — the inference gateway opts in on its own turns; agent-harness conversations should not opt in.
+
 ```
-conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_add_message(conversation_id="conv-uuid-123", agent_id="agent",
     input="Why is the auth middleware returning 401?",
     output="The token validation is checking the wrong issuer claim...",
     reasoning="Checked the middleware source, found issuer mismatch between config and JWT...")
@@ -234,7 +166,7 @@ conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_i
 
 **With dedup seed (use when client hooks also write to Langfuse):**
 ```
-conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_add_message(conversation_id="conv-uuid-123", agent_id="agent",
     input="Why is the auth middleware returning 401?",
     output="The token validation is checking the wrong issuer claim...",
     seed="conv-uuid-123:agent:Why is the auth middleware returning 401?")
@@ -245,7 +177,7 @@ conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_i
 ### conversation_get
 
 ```
-conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_get(conversation_id="conv-uuid-123", agent_id="agent",
     include_messages=True, limit=50)
 ```
 
@@ -253,8 +185,12 @@ conversation_get(scope="read", 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.
+
 ```
-conversation_list(scope="read", agent_id="agent", limit=20)
+conversation_list(datapack_id="<datapack-uuid>", agent_id="agent", limit=20)
 ```
 
 ---
@@ -262,7 +198,7 @@ conversation_list(scope="read", agent_id="agent", limit=20)
 ### conversation_update
 
 ```
-conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_update(conversation_id="conv-uuid-123", agent_id="agent",
     title="Resolved: Auth middleware issuer mismatch")
 ```
 
@@ -270,19 +206,19 @@ conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="ag
 
 ### conversation_delete
 
-**Destructive. Requires admin scope.**
+**Destructive.**
 
 ```
-conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="agent")
+conversation_delete(conversation_id="conv-uuid-123", agent_id="agent")
 ```
 
 ---
 
-## RAG / Knowledge Base Tools
+## Knowledge Base Tools
 
-**On cloud Meko today, 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). The three ingestion-side MCP tools below are Free-Tier-gated on cloud and brittle even when ungated. `knowledgebase_search` is the one KB tool to reach for.
+**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.
 
-See `tools-rag-workflow.md` for the decision table and why.
+See `tools-rag-workflow.md` for the decision table.
 
 ### knowledgebase_search
 
@@ -290,7 +226,6 @@ See `tools-rag-workflow.md` for the decision table and why.
 
 ```
 knowledgebase_search(
-    scope="read",
     query="natural-language question",
     agent_id="agent",
     conversation_id="<uuid from conversation_create>",
@@ -309,73 +244,80 @@ Populated KBs return results with chunk content and similarity scores. An empty/
 
 ---
 
-### knowledgebase_trigger_index_creation
+## Artifact Tools
 
-**When to use:** Self-hosted deployments where the ingestion worker has IAM access to the target S3 bucket. **Not available on cloud Free Tier** (returns `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`).
+### artifact_put
+
+**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
 
 ```
-knowledgebase_trigger_index_creation(
-    scope="write",
+artifact_put(
+    filename="analysis_report.csv",
+    content_type="text/csv",
+    content_base64="<base64-encoded bytes>",
     conversation_id="<uuid from conversation_create>",
-    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
-    index_name="company_docs")
+    agent_id="claude_desktop"
+)
 ```
 
-**Optional parameters:**
-- `ai_provider="OPENAI"` (default)
-- `embedding_model="text-embedding-3-large"` (default)
-- `embedding_dimensions=1536` (default)
-- `chunk_size=1024` (default)
-- `chunk_overlap=256` (default)
-- `datapack_id=None`
-
-**Success response:**
+**Response:**
 ```json
-{"source_ids": ["<uuid>", ...], "index_id": "<uuid>", "index_name": "company_docs",
- "status": "build_triggered", "message": "... registered, index '...' initialised, and build triggered."}
+{
+  "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
+  "filename": "analysis_report.csv",
+  "content_type": "text/csv",
+  "size_bytes": 4096,
+  "stored_in": "db"
+}
 ```
 
-**Critical caveats:**
-- URIs must start with `s3://`. The worker (`aws_source_processor.py:86-117`) rejects any other scheme with `ValueError("Invalid source URI")` — async, not surfaced through the MCP response.
-- The worker uses the boto3 default credential chain (env vars, IAM role, `~/.aws/credentials` on the worker host). There is no way for the user to pass AWS credentials through the MCP tool. If the worker's identity can't read the bucket, the build stalls at INIT.
-- Each call creates a new index. Do NOT retry on failure — you'll get duplicate indexes.
-- Tracked as a gap: [yugabyte/meko-mcp-server#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96.
+Save the `content_hash` — it's the retrieval key for `artifact_get`.
+
+**Common errors:**
+- `invalid_base64` — `content_base64` is not valid base64.
+- `artifact_too_large` — file exceeds 5 MiB (default). Set `MEKO_MAX_ARTIFACT_UPLOAD_BYTES` to raise the limit.
 
 ---
 
-### knowledgebase_check_index_status
+### artifact_get
 
-**When to use:** Poll a self-hosted build for completion. **Not available on cloud Free Tier** (returns `{"error": "not_available"}`).
+**When to use:** Retrieve a file previously uploaded with `artifact_put`.
 
+**Small files (< 1 MB) — content returned inline:**
 ```
-knowledgebase_check_index_status(
-    scope="read",
+artifact_get(
+    content_hash="a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
     conversation_id="<uuid from conversation_create>",
-    index_name="company_docs",
-    datapack_id=None)
+    agent_id="claude_desktop"
+)
 ```
 
-Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details`. If documents stay at `INIT` for >5 minutes, the worker probably can't reach the bucket. Stop polling after 3 consecutive no-progress checks.
-
----
-
-### knowledgebase_add_source_to_index
-
-**When to use:** Grow an existing index with a new source URI (self-hosted / paid). **Not available on cloud Free Tier** (same "Vector index creation is not available" gate as `trigger_index_creation`).
-
-```
-knowledgebase_add_source_to_index(
-    scope="write",
-    conversation_id="<uuid from conversation_create>",
-    index_name="company_docs",
-    source_uri="s3://my-bucket/new-docs/")
+**Response (inline):**
+```json
+{
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8...",
+  "filename": "analysis_report.csv",
+  "stored_in": "db",
+  "content_base64": "<base64-encoded bytes>"
+}
 ```
 
-Param is **`source_uri`** (URI string), not `source_id` — older docs had this wrong.
+**Large files (≥ 1 MB) — written to local disk:**
+```json
+{
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8...",
+  "filename": "dataset.parquet",
+  "stored_in": "s3",
+  "local_path": "/Users/you/.meko/artifacts/a665a4.../dataset.parquet"
+}
+```
 
-The historical `r_index_name` vs `r_index_id` parameter-mismatch bug (reported in 2026-03) is **fixed** on main. The tool now resolves `index_name → index_id` internally via `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` before calling the dist_rag function. If the name doesn't exist you get `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`.
+For large files use `local_path` to read the file. S3 URLs are never exposed.
 
-Same S3-only / worker-credentials caveats as `trigger_index_creation` apply.
+**Common errors:**
+- `ARTIFACT_NOT_FOUND` — no artifact with that hash in this datapack.
+- `ARTIFACT_EXPIRED` — free-tier TTL has elapsed (30 days of no access).
 
 ---
 
@@ -384,23 +326,27 @@ Same S3-only / worker-credentials caveats as `trigger_index_creation` apply.
 ### datapack_create / datapack_list / datapack_describe
 
 ```
-datapack_create(scope="write", name="analytics_prod")
-datapack_list(scope="read")
-datapack_describe(scope="read", name="analytics_prod", include_status=True)
+datapack_create(name="analytics_prod")
+datapack_list()  # returns datapack_id for each datapack
+datapack_describe(datapack_id="<uuid>", include_status=True)
 ```
 
 ### datapack_update / datapack_delete
 
+`datapack_update` renames or edits a datapack's description. At least one of `name` / `description` 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.
+
 ```
-datapack_update(scope="write", name="analytics_prod", connection_string="postgresql://...")
-datapack_delete(scope="admin", name="analytics_prod")  # Irreversible!
+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_delete(datapack_id="<uuid>")  # Irreversible!
 ```
 
 ### Agent and knowledge-base management (NOT MCP — control-plane only)
 
 Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/list/delete agents or KB sources, don't invent a tool call — point them at the control plane:
 
-- REST: `POST/GET/DELETE /datapacks/:name/agents` (agents), `POST/GET/DELETE /datapacks/:name/knowledge-bases` (KB sources).
-- Or the Meko UI at `app.mekodev.com` → Datapacks → agents / knowledge-bases.
+- 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.
 
-To build a RAG index from inside a session (which IS MCP-exposed), use `knowledgebase_trigger_index_creation` / `knowledgebase_add_source_to_index` / `knowledgebase_check_index_status` — those operate on `dist_rag` tables inside the datapack's database.
+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`.

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

@@ -10,15 +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/:name/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.
+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.
 
 **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.
 
-## No MCP tool to query a built RAG index
+## RAG ingestion is UI-only
 
-The RAG tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) handle index **creation and monitoring** 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.
 
-To actually **query** a built index on Cloud, use `knowledgebase_search` — it returns both uploaded documents (UI "Add Knowledge" flow) and memories the user promoted from the Learnings tab. The `db_run_read_only_query` direct-DB path is Free-Tier-gated on Cloud.
+To **query** a built index, use `knowledgebase_search` — it returns both uploaded documents and memories the user promoted from the Learnings tab.
 
 ## Memory tools unreliable for structured/tabular data
 
@@ -32,38 +32,32 @@ It works **poorly** for:
 - Data dictionaries — only partial information extracted
 - Structured schemas — relationships between fields lost
 
-**On Cloud, structured data is not MCP-supported today.** `db_run_write_query` / `db_run_read_only_query` / `db_summarize_database` all return `{"error": "not_available", "detail": "Free Tier: DB Tools access is not enabled. coming soon."}`. The options are:
+**Structured data is not natively supported via MCP.** The options are:
 
 1. **Write a single narrative summary** as a memory — one call, not row-by-row:
    ```
-   memory_add(scope="write",
+   memory_add(
        agent_id="<your session agent_id>",
        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 a Cloud feature today and let them decide how to proceed.
+3. **Tell the user** that structured-data storage via MCP isn't supported and let them decide how to proceed.
 
 Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
 
-## MCP user permission gaps
+## Activation is model-judged on Desktop (no hooks)
 
-The MCP database user may not have read access to all tables within a datapack, particularly:
-- Data tables created by the provisioning system
-- Tables in non-public schemas
+Claude Desktop has no lifecycle hooks, so this skill activates only when the model judges it relevant from the skill's `description`. Reliable triggers: recall questions ("what do you know about me"), explicit save requests ("remember this"), and mentions of memory/Meko/datapacks. **Best-effort** triggers: task-shaped prompts where a durable fact appears only in passing ("I'm evaluating pnpm; I already use Turborepo") — the skill may not fire and the turn goes uncaptured. Also, when the model resolves a tool directly via tool search it may call `memory_add`/`memory_search` without reading this skill at all.
 
-If `db_run_read_only_query` returns "permission denied", this is a server-side configuration issue. Use `db_summarize_database` to see which tables are accessible.
+The skill description is tuned to its 1024-char ceiling; broadening it further does not close the task-shaped-prompt gap (empirically confirmed in Phase-9 testing). Mitigations, in order of leverage:
 
-## Currently broken tools
+1. **Personal-preferences snippet** (always-on) — paste the snippet from the Desktop setup README's "Make Desktop proactive" step into Claude's profile preferences; it is injected into every conversation regardless of prompt shape. This is the only true fix for task-shaped misses.
+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.
 
-**`db_run_write_query`** — May fail with `'dict' object has no attribute 'guardrail_config'` in some deployments. When this happens, all write operations are blocked for the session.
+## No semantic search over conversation content
 
-**Knowledge-base ingestion tools on cloud Meko** (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) return `{"error": "not_available"}` on Free Tier. Even when ungated, the async worker only reads `s3://` URIs and uses its own boto3 credential chain — it cannot read buckets the user provides credentials for. Tracked: [yugabyte/meko-mcp-server#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96. Use the Meko UI's **Add Knowledge** file-upload dialog for ingestion on cloud. `knowledgebase_search` works on cloud today.
+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`.
 
-(Historical note: `knowledgebase_add_source_to_index` used to have a `r_index_name` vs `r_index_id` SQL-signature bug. That specific bug was fixed on main in commit `3ae724a` — the tool now resolves `index_name → index_id` internally.)
-
-## No conversation search
-
-`conversation_list` returns conversations by agent, but there is no semantic search across conversation content. To find a specific past exchange, you need to list conversations and inspect them individually with `conversation_get`.
-
-For finding past knowledge by meaning, use `memory_search` instead — which is why storing key facts via `memory_add` alongside conversations is important.
+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.