@yugabytedb/meko-mcp 1.2.0 → 2.1.0

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

@@ -1,113 +1,23 @@
 # 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.** Where you see `agent_id="agent"` in an example, substitute **your** session's `agent_id` — the value the SessionStart hook injected into `additionalContext`. For Claude Code that's `claude_code:<repo-basename>` (e.g. `claude_code:meko-mcp-server`); for Cursor, `cursor:<repo-basename>`; for Claude Desktop, the bare client name `claude_desktop`. 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.** Where you see `agent_id="agent"` in an example, substitute **your** session's `agent_id` — the value the SessionStart hook injected into `additionalContext`. For Claude Code that's `claude_code:<repo-basename>` (e.g. `claude_code:meko-mcp-server`); for Cursor, `cursor:<repo-basename>`; for Claude Desktop, the bare client name `claude_desktop`. For genuinely cross-project facts (user identity, global preferences) write with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
 
 ---
 
 ## Memory Tools
 
-**Critical:** Pass your session's `agent_id` on every memory call (the value from the SessionStart `additionalContext`, e.g. `claude_code:meko-mcp-server`). 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. For genuinely cross-project facts, write with `agent_id="meko_agent"` so any agent can pick them up.
+**Critical:** Pass your session's `agent_id` on every memory *write* (the value from the SessionStart `additionalContext`, e.g. `claude_code:meko-mcp-server`) — it is stored on the row and rendered as the UI badge. Note that `agent_id` labels writes but does **not** filter personal reads: a single `memory_search` / `memory_get_all` returns all of your memories for this user across every `agent_id` (see the `memory_search` note below). For genuinely cross-project facts, write with `agent_id="meko_agent"` so the row lands in the common bucket.
 
 ### 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 in conversation — those are saved automatically by conversation capture + server-side extraction. Reserve `memory_add` for the three cases extraction can't reach: (1) the user explicitly says "remember this"; (2) a durable fact that lives 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="<your-agent-id>",
+    conversation_id="<uuid from conversation_create or the SessionStart hook>",
+    text="Remember: deploy scripts must be run from the repo root, never a subdir.")
 ```
 
 **Response:**
@@ -115,16 +25,9 @@ memory_add(scope="write", agent_id="agent",
 {"results": [{"id": "mem-uuid-123", "memory": "User Amiram is VP of Product at YugabyteDB. Prefers concise responses."}]}
 ```
 
-**With user scoping:**
-```
-memory_add(scope="write", 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.
@@ -137,9 +40,11 @@ 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.
 
 ```
-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", conversation_id="<uuid>")
 ```
 
+**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.
+
 **Response:**
 ```json
 {"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
@@ -147,22 +52,17 @@ 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", conversation_id="<uuid>", limit=5)
 ```
 
 ---
 
 ### memory_get_all
 
-**When to use:** List everything stored for an agent. Useful at session start to load context.
+**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.
 
 ```
-memory_get_all(scope="read", agent_id="agent")
-```
-
-**With user scoping:**
-```
-memory_get_all(scope="read", agent_id="agent", user_id="amiram")
+memory_get_all(agent_id="agent", conversation_id="<uuid>")
 ```
 
 ---
@@ -170,7 +70,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", conversation_id="<uuid>")
 ```
 
 ---
@@ -180,7 +80,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", conversation_id="<uuid>")
 ```
 
 ---
@@ -188,21 +88,41 @@ 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", conversation_id="<uuid>")
 ```
 
 ---
 
 ### 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(scope="admin", agent_id="agent")
+memory_delete_all(agent_id="agent", conversation_id="<uuid>")
 ```
 
 ---
 
+### 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_promote(memory_ids=["mem-uuid-123", "mem-uuid-456"],
+    agent_id="agent", 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
 
 ### conversation_create
@@ -210,7 +130,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",
     title="Debugging the auth middleware")
 ```
 
@@ -225,8 +145,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 +156,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 +167,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 +175,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 +188,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 +196,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 +216,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 +234,84 @@ 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="agent"
+)
 ```
 
-**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; decode the file before passing it.
+- `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="agent"
+)
 ```
 
-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",
+  "content_type": "text/csv",
+  "size_bytes": 4096,
+  "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",
+  "content_type": "application/octet-stream",
+  "size_bytes": 2097152,
+  "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 the `local_path` value to read the file with normal file tools. 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` — artifact exists but its free-tier TTL has elapsed (30 days of no access). Pro-tier artifacts never expire.
 
 ---
 
@@ -384,23 +320,29 @@ 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 the description of a datapack. Both `name` and `description` are optional; pass at least one. If both are omitted the tool returns `nothing_to_update` without hitting the API.
+
+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.
+
 ```
-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/references/tools-datapack-workflow.md

@@ -1,64 +1,58 @@
 # Datapack Lifecycle and datapack_id Routing
 
-**WRONG:** Creating a datapack then calling `db_summarize_database(scope="read")` without `datapack_id` — this queries the DEFAULT database, not the datapack.
-
-## Always pass datapack_id for datapack-scoped operations
-
-```
-datapack_create(scope="write", name="analytics_prod")
--- Returns: {"id": "dp-uuid-123", ...}
-
-db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
-db_run_read_only_query(scope="read", query="SELECT * FROM customers LIMIT 10", datapack_id="dp-uuid-123")
-```
-
-## How datapack_id routing works
-
-1. When `datapack_id` is **omitted**: uses the default pool from `YUGABYTEDB_URL`
-2. When `datapack_id` is **provided**: resolves connection string via Meko API, creates/reuses a cached pool for that datapack
+Datapacks are isolated workspaces — each has its own memory store and knowledge-base index. Many MCP tools accept an optional `datapack_id` to target a specific workspace; omit it to use the default.
 
 ## Which tools accept datapack_id?
 
-All **Database**, **RAG**, and **Memory** tools accept `datapack_id`.
-
-**Conversation** tools do NOT — they always use Langfuse.
-**Datapack management** tools do NOT — they operate on the Meko API itself.
+| Tool group | Accepts `datapack_id`? |
+|---|---|
+| **Memory** (`memory_*`) | Yes — optional, defaults to the caller's default datapack |
+| **Knowledge Base** (`knowledgebase_search`) | Yes — **required** (no default) |
+| **Conversation** (`conversation_*`) | Yes — optional; routes the call's Langfuse trace to that datapack's project (data is Langfuse-stored, not in the datapack DB itself) |
+| **Datapack management** (`datapack_*`) | Yes — `datapack_describe`/`datapack_update`/`datapack_delete` address the datapack by its `datapack_id` (the Meko API routes are `/datapacks/{datapack_id}`); it also routes the call's Langfuse trace to that datapack's project |
 
 ## How to obtain a datapack_id
 
-- From `datapack_create` response (`"id"` field)
-- From `datapack_list` (each entry has `"id"`)
-- From `datapack_describe` response
+- 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_describe` response (same field names)
 
 ## Datapack lifecycle
 
-### Creation and setup (MCP)
+### Creation
 
 ```
-datapack_create(scope="write", name="sales_analytics")
-db_run_write_query(scope="write", query="CREATE TABLE leads (...)", datapack_id="dp-uuid-from-step-1")
+datapack_create(name="sales_analytics",
+    conversation_id="<uuid>")
+-- Returns: {"datapack_id": "dp-uuid-123", "datapack_name": "sales_analytics", ...}
 ```
 
-Provisioning agents and knowledge-base sources on the datapack is **not** MCP-exposed — do that in the Meko control plane (UI at `app.mekodev.com` → Datapacks, or directly via the REST API:
-`POST /datapacks/:name/agents`, `POST /datapacks/:name/knowledge-bases`). If the user asks the agent to set those up mid-session, tell them where to go rather than inventing an MCP call that will fail.
+Provisioning agents and knowledge-base sources on a new 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)
+
+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.
 
-For RAG indexes inside the datapack's database, use the MCP-exposed RAG tools:
+### Targeting a specific datapack on subsequent calls
 
 ```
-knowledgebase_trigger_index_creation(scope="write", source_uris=[...], index_name="leads_docs", datapack_id="dp-uuid-from-step-1")
-knowledgebase_check_index_status(scope="read", index_name="leads_docs", datapack_id="dp-uuid-from-step-1")
+memory_search(agent_id="<your-agent-id>",
+    conversation_id="<uuid>", query="...", datapack_id="dp-uuid-123")
+knowledgebase_search(agent_id="<your-agent-id>",
+    conversation_id="<uuid>", datapack_id="dp-uuid-123", query="...")
 ```
 
-### Teardown (requires admin scope)
+### Teardown
 
 Delete child resources first (agents and KB sources via the control plane), then the datapack:
 
 ```
-# Control-plane (REST or UI): DELETE /datapacks/sales_analytics/knowledge-bases
-# Control-plane (REST or UI): DELETE /datapacks/sales_analytics/agents/sales_agent
-datapack_delete(scope="admin", name="sales_analytics")  # MCP-exposed, destructive
+# 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
 ```
 
-## Common mistake: mixing default and datapack databases
+## Common mistake: forgetting datapack_id on memory tools
 
-If you created a table with a `datapack_id`, always query it with the same `datapack_id`. Creating in default DB and querying in a datapack (or vice versa) will fail with "table not found".
+Memory writes without `datapack_id` land in the default datapack, not the one you just created. If you `datapack_create` and then `memory_add` without passing the new datapack's id, you'll be searching the wrong store later.