@yugabytedb/meko-mcp 1.2.0 → 2.1.0

package/assets/skills/meko-mcp-tools/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,22 @@ 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
+## No semantic search over conversation content
 
-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
+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`.
 
-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.
-
-## Currently broken tools
-
-**`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.
-
-**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.
-
-(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.

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

@@ -11,10 +11,10 @@
 Memory is backed by pgvector (semantic search) and Apache AGE (entity-relationship graph). It retrieves relevant facts by meaning, not by conversation order.
 
 ```
-memory_add(scope="write", agent_id="support_bot",
-    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.", user_id="alice_123")
+memory_add(agent_id="support_bot",
+    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.")
 
-memory_search(scope="read", query="What plan does Alice have?", agent_id="support_bot")
+memory_search(query="What plan does Alice have?", agent_id="support_bot")
 ```
 
 ## Use `conversation_create` + `conversation_add_message` when storing:
@@ -26,10 +26,10 @@ memory_search(scope="read", query="What plan does Alice have?", agent_id="suppor
 Conversations are backed by Langfuse sessions and traces. They preserve full structure: who said what, in what order, with what reasoning.
 
 ```
-conversation_create(scope="write", agent_id="support_bot", user_id="alice_123", title="Pricing discussion")
+conversation_create(agent_id="support_bot", title="Pricing discussion")
 -- Returns: {"id": "conv-uuid-here"}
 
-conversation_add_message(scope="write", conversation_id="conv-uuid-here", agent_id="support_bot",
+conversation_add_message(conversation_id="conv-uuid-here", agent_id="support_bot",
     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.")
@@ -65,72 +65,68 @@ All three fields — `input`, `output`, and `reasoning` — must contain the **e
 
 The purpose of conversation storage is to create a faithful, replayable record. A rephrased summary loses the original wording, tone, and detail — making the stored conversation useless for review, debugging, or audit.
 
-## Personal memory vs. team-shared knowledge — the three read paths
+## Personal memory vs. team-shared knowledge — the two read paths
 
-Agents on Cloud Meko have three distinct read surfaces. Pick the right one for the question.
+Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the question.
 
 | Read path | What it returns | How to call |
 |---|---|---|
-| Your own project memories | Memories you wrote under this `agent_id`, filtered by `(datapack_id, user_id, agent_id)` | `memory_search(agent_id="<your agent_id>", query="...", ...)` |
-| Cross-project common bucket | Memories any agent (including this one) wrote with `agent_id="meko_agent"` — the empty-default bucket for genuinely cross-project facts | `memory_search(agent_id="meko_agent", query="...", ...)` |
+| Your personal memories | Everything you and any of your agents wrote for this user — filtered by `(datapack_id, user_id)`, **not** by `agent_id`. One call covers your project bucket, the `meko_agent` common bucket, and every other project's rows. | `memory_search(agent_id="<your agent_id>", query="...", ...)` — `agent_id` scopes the Langfuse trace, not the results |
 | Team's shared knowledge | Promoted memories + uploaded documents, visible to every member of the datapack | `knowledgebase_search(agent_id="<anything>", datapack_id="<datapack UUID>", query="...")` — `agent_id` is ignored |
 
-For a true fan-out across multiple specific agent_ids (e.g. also see what was written from `claude_code:other-repo` or `cursor:foo`), call `memory_search` once per agent_id — there's no single-call shortcut. Empty string is rewritten to `meko_agent` server-side; it does not drop the filter.
+`agent_id` does not filter memory reads, so a single `memory_search` already spans all of your agents; there is no per-agent fan-out to do.
 
 ### How content gets into each surface
 
-- **Personal memories** — written by `memory_add`. Scoped per-user and per-agent from the moment of write. Only the writer sees them via MCP reads.
+- **Personal memories** — written by `memory_add`. The `agent_id` records the writer but does not restrict reads; memories are scoped **per-user**, so any of that user's agents can read them via MCP, and no other user can.
 - **Team-shared Shared Knowledge** — arrives two ways:
-  1. The **user** (never the agent) promotes a personal memory to Knowledge via the Cloud UI's Learnings tab. That copies the row into the shared `knowledge_base` table with the `user_id` stripped, making it team-wide. Originating `agent_id` is preserved in metadata for provenance.
+  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 and graph context 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.
 
   Both show up in `knowledgebase_search`, tagged `metadata_filters.source: "memory"` vs other values so the agent can distinguish provenance in responses.
 
-**No MCP tool promotes to Shared Knowledge.** The agent can flag memories it thinks are worth promoting and suggest the user do it from the UI — but the action is user-initiated.
+`memory_promote` is a one-way, destructive MCP path. Before calling it, retrieve exact UUIDs with `memory_search` or `memory_get_all`, show the exact candidates, explain team visibility and private-record eviction, and obtain explicit user confirmation. Only owners and maintainers may promote; report 403/auth failures without escalating scope or switching datapacks. The Cloud UI remains an alternative.
 
 ### When the user asks "what do you know about X?"
 
-A full sweep is three calls (budget for it — each is 2-6 seconds):
+A full sweep is two calls (budget for it — each is 0.6-6 seconds):
 
 ```
-memory_search(agent_id="<your-agent-id>", query="X", conversation_id=..., ...)
-memory_search(agent_id="meko_agent", query="X", conversation_id=..., ...)  # cross-project common bucket
+memory_search(agent_id="<your-agent-id>", query="X", conversation_id=..., ...)   # all your personal memories, every agent
 knowledgebase_search(agent_id="<anything>", datapack_id="<uuid>", query="X", conversation_id=..., ...)
 ```
 
-When you answer, be explicit about scope so the user knows why something is or isn't there:
+The single `memory_search` already returns everything you and any other agent wrote for this user (`agent_id` doesn't filter memory reads) — no per-agent fan-out. When you answer, be explicit about scope so the user knows why something is or isn't there:
 
-- "I found this in your own project memories…"
-- "I found this in your common cross-project bucket (something you or another agent wrote under `meko_agent`)…"
+- "I found this in your personal memories (something you or another of your agents saved earlier)…"
 - "I found this in your team's Shared Knowledge — someone (you or a teammate) promoted it earlier…"
-- "I couldn't find anything in your personal memories. You might want to check the Cloud UI's Memory Summary tab for a cross-agent view."
-
-For a true fan-out across other specific buckets (e.g. also see what was written from `claude_code:other-repo` or `cursor:foo`), call `memory_search` once per known agent_id — empty string just resolves to `meko_agent`, not a fan-out.
+- "I couldn't find anything in your personal memories. You might want to check the Cloud UI's Memory Summary tab."
 
 ## Memory limitations for structured data
 
 **WRONG:** Using `memory_add` to ingest CSV rows, data dictionaries, or tabular schemas — Mem0 extracts individual facts and may drop columns, rows, or structural relationships.
 
-On Cloud Meko today the `db_run_write_query` path isn't available (returns `{"error": "not_available"}`), so there's no MCP-side "just put it in a database table" option. Workarounds:
+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).
 3. **Never ingest CSV row-by-row** into memory — each row becomes a fragmented fact with lost context.
 
-## Proactive Memory Storage
+## Memory Storage: automatic, not proactive
+
+On Claude Code, do **not** proactively `memory_add` facts the user states. Conversation capture is automatic (see below) and the server extracts durable memories from the captured turns on its own — personal info, team conventions, domain knowledge the user states, and corrections are all saved without a tool call. Re-storing them with `memory_add` just duplicates what extraction already holds.
 
-Don't wait for the user to say "remember this." Store context proactively when you detect:
+Explicit `memory_add` is reserved for the three cases automatic extraction cannot reach:
 
-- **Personal info** → `memory_add`: "User is VP of Product, prefers concise responses"
-- **Team conventions** → `memory_add`: "Team uses Python for backend, Go for infrastructure"
-- **Domain knowledge** → `memory_add`: "Meko traces are decision traces that capture how and why decisions were made"
-- **Corrections** → `memory_add`: "User corrected: always use 'resilience' instead of 'high availability'"
+- **Explicit request** → the user says "remember this" / "save this."
+- **Output-only / tool-derived fact** → a durable fact that lives only in your output or a tool result, never in a user turn. Extraction reads only the user turn, so it never sees these.
+- **Overwriting correction** → a prior fact was negated and the stale memory must not survive. Extraction is additive (it adds the new fact but leaves the old one live), so `memory_search` for the stale memory and `memory_update` / `memory_delete_by_id` it.
 
 Use `memory_search` at the start of sessions to recall what you already know before asking the user to repeat themselves.
 
 ## Using Both Together
 
-A common pattern: store the full conversation (preserves structure) AND extract key facts with `memory_add` (enables semantic search later).
+Capture stores the full conversation (preserves structure) and extraction derives searchable memories from it — both happen automatically. Add an explicit `memory_add` only for the three cases above.
 
 ## Key Retrieval Difference
 

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

@@ -1,96 +1,90 @@
 # Complete Tool Catalog and Decision Tree
 
-**26 tools on cloud Meko** (verified against `https://mcp.mekodata.ai/mcp` on 2026-05-07). Earlier counts of 25 or 31 in other docs are stale. Grouped: Memory (8), Conversation (6), Knowledge Base (4), Datapack (5), Database (3).
-
-## Cloud Free-Tier gating at a glance
-
-Some tools return `{"error": "not_available", "detail": "..."}` on cloud Free Tier. This is a server-side tier block — don't retry.
-
-- **Gated on Free Tier**: `db_summarize_database`, `db_run_read_only_query`, `db_run_write_query`, `knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`
-- **Works on Free Tier**: all memory tools, all conversation tools, `knowledgebase_search`, all datapack tools, `flush_pending_memory_candidates`
+**23 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
-1. `memory_search(scope="read", query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-2. `datapack_list(scope="read")` — Confirms Meko API connectivity
-3. `db_summarize_database(scope="read")` — *Optional, paid-tier only.* On free-tier datapacks this returns `{"error": "not_available"}`. The old "use this for `agent_id` discovery" protocol is retired — use the session-injected `agent_id` for project-scoped calls, or `meko_agent` for the common bucket.
+1. `memory_search(query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
+2. `datapack_list()` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
 
 ## Decision tree: which tool do I need?
 
 ```
 User wants to...
-├── Query or explore the database?
-│   ├── See what tables exist? ---------> db_summarize_database (read)
-│   ├── Run a SELECT / read query? -----> db_run_read_only_query (read)
-│   └── INSERT / UPDATE / DELETE? -------> db_run_write_query (write)
-├── Query or build a knowledge base (RAG)?
-│   ├── Search chunks in an existing KB? -> knowledgebase_search (read) — WORKS on cloud today
-│   ├── Create a new index from sources? -> knowledgebase_trigger_index_creation (write) — Free-Tier gated, self-hosted only
-│   ├── Add source to existing index? ---> knowledgebase_add_source_to_index (write) — Free-Tier gated
-│   └── Check build progress? -----------> knowledgebase_check_index_status (read) — Free-Tier gated
+├── Search a knowledge base? ---------------> knowledgebase_search (read)
+├── Add documents to a knowledge base? -----> point user at Meko UI: Datapack → Actions → Add Knowledge
+│                                              (no MCP tool — Cloud uses UI ingestion only)
 ├── Store or recall information?
 │   ├── Store a fact/preference/entity? -----------> memory_add (write)
 │   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
 │   ├── Search past knowledge? --------------------> memory_search (read)
+│   ├── Share private memories with the team? -----> memory_promote (write; owner/maintainer only)
 │   └── Retrieve a past conversation? -------------> conversation_get (read)
+├── Persist or retrieve a file?
+│   ├── Upload a generated file (report, CSV, PDF)? -> artifact_put (write)
+│   └── Retrieve a previously uploaded file? -------> artifact_get (read)
 └── Manage datapacks?
-    └── CRUD datapack? -> datapack_create/list/describe/update/delete
+    └── CRUD datapack? --------------------> datapack_create/list/describe/update/delete
 ```
 
 Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typically in the Meko control-plane UI — and is not exposed as tools here.
 
-## Database Tools (3)
-
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `db_summarize_database(scope, schema="public", datapack_id=None)` | read | List tables with column schemas and row counts |
-| `db_run_read_only_query(scope, query, datapack_id=None)` | read | Run SELECT, returns JSON. Uses `BEGIN READ ONLY` + `ROLLBACK` |
-| `db_run_write_query(scope, query, datapack_id=None)` | write | Execute INSERT/UPDATE/DELETE/CREATE TABLE. Guardrail-validated. Auto-committed |
-
-## RAG / Knowledge Base Tools (4)
+## Knowledge Base Tools (1)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `knowledgebase_search(scope, query, agent_id, conversation_id, datapack_id, limit=10)` | read | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). Works on cloud today. |
-| `knowledgebase_trigger_index_creation(scope, conversation_id, source_uris, index_name, ai_provider="OPENAI", embedding_model="text-embedding-3-large", embedding_dimensions=1536, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Register sources + init vector index + trigger build. **S3-only worker + no user creds; Free-Tier gated on cloud.** See `tools-rag-workflow.md`. |
-| `knowledgebase_add_source_to_index(scope, conversation_id, index_name, source_uri, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Add a new source (URI, not id) to an existing index. Free-Tier gated on cloud. |
-| `knowledgebase_check_index_status(scope, conversation_id, index_name, datapack_id=None)` | read | Check build progress via `dist_rag.vector_index_pipeline_details`. Free-Tier gated on cloud. |
+| Tool | Purpose |
+|------|---------|
+| `knowledgebase_search(query, agent_id, conversation_id, datapack_id, limit=10)` | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
 
 ## Memory Tools (8)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `memory_add(scope, text, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | write | Store fact/preference/entity as long-term memory |
-| `memory_search(scope, query, agent_id, conversation_id="", user_id=None, limit=10, datapack_id=None)` | read | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
-| `memory_get_by_id(scope, memory_id, agent_id, conversation_id, datapack_id=None)` | read | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
-| `memory_get_all(scope, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | read | List all memories for agent |
-| `memory_update(scope, memory_id, text, agent_id, conversation_id, datapack_id=None)` | write | Overwrite memory text |
-| `memory_delete_by_id(scope, memory_id, agent_id, conversation_id, datapack_id=None)` | write | Delete a single memory |
-| `memory_delete_all(scope, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | admin | Delete all memories for agent (destructive) |
-| `flush_pending_memory_candidates(scope, agent_id)` | read | Desktop-skill helper: returns an instruction payload telling the agent to scan recent user turns and `memory_add` unsaved facts. No server-side DB write. |
+| Tool | Purpose |
+|------|---------|
+| `memory_add(text, agent_id, conversation_id, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
+| `memory_search(query, agent_id, conversation_id="", limit=10, datapack_id=None)` | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
+| `memory_get_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
+| `memory_get_all(agent_id, conversation_id, run_id=None, datapack_id=None)` | List all of the user's memories (every agent — `agent_id` does not filter) |
+| `memory_update(memory_id, text, agent_id, conversation_id, datapack_id=None)` | Overwrite memory text |
+| `memory_delete_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Delete a single memory |
+| `memory_delete_all(agent_id, conversation_id, run_id=None, datapack_id=None)` | Delete all memories for agent (destructive) |
+| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them + graph context out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403. |
 
 ## Conversation Tools (6)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `conversation_create(scope, agent_id, user_id=None, app_id=None, run_id=None, title=None, metadata=None, session_id="")` | write | Create conversation container (Langfuse session) |
-| `conversation_add_message(scope, conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None, trace_id="")` | write | Add a message turn (Langfuse trace) |
-| `conversation_get(scope, conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | read | Retrieve conversation, optionally with messages |
-| `conversation_list(scope, agent_id, conversation_id="", user_id=None, limit=20, offset=0)` | read | List conversations for agent. `conversation_id` optional (omit for browse). |
-| `conversation_update(scope, conversation_id, agent_id, title=None, metadata=None)` | write | Update title or metadata |
-| `conversation_delete(scope, conversation_id, agent_id)` | admin | Delete entire conversation (destructive) |
+| Tool | Purpose |
+|------|---------|
+| `conversation_create(agent_id, run_id=None, title=None, metadata=None, session_id="")` | Create conversation container (Langfuse session) |
+| `conversation_add_message(conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None)` | Add a message turn (Langfuse trace) |
+| `conversation_get(conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | Retrieve conversation, optionally with messages |
+| `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List the user's conversations within a datapack (`agent_id` does not filter — trace attribution only). `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_list` to look it up. `conversation_id` optional (omit for browse). |
+| `conversation_update(conversation_id, agent_id, title=None, metadata=None)` | Update title or metadata |
+| `conversation_delete(conversation_id, agent_id)` | Delete entire conversation (destructive) |
 
 ## Datapack Management Tools (5)
 
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `datapack_create(scope, name)` | write | Create new datapack |
-| `datapack_list(scope)` | read | List all datapacks |
-| `datapack_describe(scope, name, include_status=False)` | read | Describe datapack |
-| `datapack_update(scope, name, connection_string)` | write | Update connection string |
-| `datapack_delete(scope, name)` | admin | Delete datapack (irreversible) |
+| Tool | Purpose |
+|------|---------|
+| `datapack_create(name)` | Create new datapack |
+| `datapack_list()` | List all datapacks |
+| `datapack_describe(datapack_id, include_status=False)` | Describe datapack by UUID |
+| `datapack_update(datapack_id, name=None, description=None)` | Rename a datapack and/or update its description. Pass at least one of `name` / `description`. |
+| `datapack_delete(datapack_id)` | Delete datapack by UUID (irreversible) |
+
+## Artifact Tools (2)
+
+Content-addressed blob store scoped to a datapack. Files < 1 MB go inline in the DB; files ≥ 1 MB go to S3. Identity is SHA-256 — uploading the same bytes twice returns the same `content_hash`. Free-tier artifacts expire after 30 days of inactivity; pro-tier artifacts have no TTL.
+
+| Tool | Purpose |
+|------|---------|
+| `artifact_put(filename, content_base64, content_type, conversation_id, datapack_id=None, agent_id=None)` | Upload a file to the datapack. Returns `{artifact_id, content_hash, filename, size_bytes, stored_in}`. Max 5 MiB (configurable via `MEKO_MAX_ARTIFACT_UPLOAD_BYTES`). |
+| `artifact_get(content_hash, conversation_id, datapack_id=None, agent_id=None)` | Retrieve a file by SHA-256 hash. Small files return `content_base64` inline; large files (S3) are written to `~/.meko/artifacts/<hash>/<filename>` and `local_path` is returned. |
+
+## Observability Tools (1)
+
+| Tool | Purpose |
+|------|---------|
+| `track_token_usage(conversation_id, name, input_tokens=0, output_tokens=0, total_tokens=None, model=None, message_id=None, datapack_id=None)` | Record an LLM-cost GENERATION observation on the conversation's trace. Primarily called by first-party Meko services (e.g. inference_gateway) that know their LLM's exact token counts. Most end-agents (Cursor, Claude Desktop) don't have those counts at the MCP call layer, so this tool is rarely useful for third-party agents. |
 
 ## Platform capabilities NOT exposed via MCP
 
@@ -98,15 +92,15 @@ Some things the Meko platform can do are not wired into the MCP tool surface tod
 
 | Capability | Where it lives | How to reach it |
 |---|---|---|
-| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:name/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
-| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:name/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
-| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:name/langfuse/project-keys` |
+| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
+| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
+| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:datapack_id/langfuse/project-keys` |
 | Account / billing / tier management | Meko UI only | Not available via MCP or public REST |
 
 The MCP-exposed `datapack_create` / `datapack_list` / `datapack_describe` / `datapack_update` / `datapack_delete` tools above are a deliberate subset — the common CRUD that an agent reasonably needs mid-conversation. Anything involving agent or KB lifecycle is control-plane territory.
 
-For knowledge-base content on cloud today, the canonical path is **UI upload**: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` queries the resulting index from MCP. The MCP ingestion tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) exist but are Free-Tier gated and rely on an S3-only worker with no user-supplied credentials — see `tools-rag-workflow.md` for the full picture. Tracked upstream as [#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96.
+For knowledge-base content on Cloud, the canonical path is **UI upload**: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` queries the resulting index from MCP.
 
 ## Common Parameter Patterns
 
-Every tool accepts `scope` as the first parameter. All DB, RAG, and memory tools accept optional `datapack_id` to target a specific datapack's database. Memory and conversation tools require `agent_id` for namespace isolation (see `tools-agent-id-conventions.md`).
+Memory and KB tools accept optional `datapack_id` to target a specific datapack. `agent_id` attributes writes and is enforced only on `conversation_get` (agent-owned — a wrong value returns `agent_id_mismatch`); it does **not** filter memory reads (`memory_search`/`memory_get_all`) or `conversation_list`, which return all your agents' rows for the user. See `tools-agent-id-conventions.md`.

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

@@ -1,25 +1,21 @@
 # Knowledge Base / RAG workflow
 
-As of 2026-05-07, **knowledge-base ingestion on cloud Meko is a UI-only activity**. The MCP ingestion tools exist but are gated off on cloud and rely on an S3-only worker that has no mechanism to read user-supplied buckets. `knowledgebase_search` is the only KB tool agents can rely on today.
-
-This page tells you which tool to reach for, what's usable where, and where the current gaps are tracked.
+`knowledgebase_search` is the only KB tool exposed via MCP. Index
+creation and ingestion happen out of band — through the **Meko UI**
+(`cloud.mekodata.ai`).
 
 ## Decision table
 
 | Situation | Use this | Why |
 |---|---|---|
-| Search an existing KB | `knowledgebase_search` | The one KB tool that works on cloud Free Tier and prod today |
-| Add documents to a KB on cloud | **Meko UI** — Datapack → Actions menu → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). The MCP ingestion path is not usable on cloud |
-| Create a new vector index (self-hosted / paid) | `knowledgebase_trigger_index_creation` | Only works when the ingestion worker has IAM access to the S3 bucket you pass |
-| Add a source to an existing index (self-hosted / paid) | `knowledgebase_add_source_to_index` | Same caveat as above |
-| Poll a build (self-hosted / paid) | `knowledgebase_check_index_status` | Gated on cloud Free Tier |
-| Anything that needs KB lifecycle management (list, delete, rename) | **UI** | No MCP tools for KB lifecycle |
+| Search an existing KB | `knowledgebase_search` | The one KB tool exposed via MCP |
+| Add documents to a KB | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). No MCP equivalent |
+| Anything else (list / delete / rename / re-index) | **UI** | No MCP tools for KB lifecycle |
 
 ## knowledgebase_search — the one you'll actually call
 
 ```
 knowledgebase_search(
-    scope="read",
     query="natural-language question",
     agent_id="<your agent_id>",
     conversation_id="<uuid from conversation_create>",
@@ -27,60 +23,16 @@ knowledgebase_search(
     limit=10)
 ```
 
-Required: `scope`, `query`, `agent_id`, `conversation_id`, `datapack_id`. Unlike the memory tools, `datapack_id` has no default here — you must pass it explicitly. `agent_id` is **ignored for filtering** on this tool (KB results are team-shared on the datapack), but you still pass it — your session's value is fine.
-
-Response shape (verified 2026-05-07 against prod):
-```
-{"results": [], "count": 0}
-```
-
-On a populated KB each result carries chunk content and similarity scores. On an empty or nonexistent KB you get an empty array and `count: 0` — not an error.
-
-## MCP ingestion tools — what actually happens when you call them
-
-This applies to `knowledgebase_trigger_index_creation` and `knowledgebase_add_source_to_index`. Understanding the two-layer architecture is the only way to predict whether a call will succeed.
-
-**MCP layer (`src/tools.py`):** takes `source_uris`, splits on `,`, passes each string to `dist_rag.create_source(<uri>)` with **zero validation**. No scheme check, no reachability probe. Returns `"build_triggered"` immediately.
-
-**Worker layer (`yugabyte-db/python/ai/rag_agent/rag_pipeline/aws_source_processor.py`):** only handles `s3://` URIs. Any other scheme raises `ValueError("Invalid source URI")` inside the worker — **async, never surfaced to the MCP caller**. The S3 crawler is instantiated with no credentials; it relies on boto3's default chain (env vars, IAM role, `~/.aws/credentials` on the worker host). So the worker can only read buckets its own AWS identity has access to.
-
-**Implication:** pointing the MCP tool at a user-owned S3 bucket from cloud will return `"build_triggered"` and silently stall at INIT forever. There is no way for the user to supply AWS credentials through the MCP tool.
-
-## Free-Tier cloud gating (verified 2026-05-07 against `https://mcp.mekodata.ai/mcp`)
-
-| Tool | Verbatim response |
-|---|---|
-| `knowledgebase_trigger_index_creation` | `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}` |
-| `knowledgebase_add_source_to_index` | Same as above |
-| `knowledgebase_check_index_status` | `{"error": "not_available", "detail": "Index status check is not available on the free tier."}` |
-| `knowledgebase_search` | Works: `{"results": [], "count": 0}` |
-
-`{"error": "not_available"}` is a server-side tier block. Don't retry.
-
-## UI ingestion (cloud Meko) — what the user sees
-
-From `cloud.mekodata.ai`:
-
-1. Open a datapack (`/datapacks/<name>`).
-2. Click **Actions** → **Add Knowledge**.
-3. Drag-and-drop or browse for files. Supported: PDF, TXT, MD, JSON, MP4. Per-file limit 5 MB. Up to 10 files per batch.
-4. The UI handles upload, storage, and index build. The user does not pick a bucket or provide credentials.
-5. Search results from `knowledgebase_search` become available once indexing completes.
-
-If a user asks you "how do I add a document to my knowledge base?", point them at this flow. Do not suggest `knowledgebase_trigger_index_creation` with an S3 URI — on cloud that path does not work.
+Required: `query`, `agent_id`, `conversation_id`, `datapack_id`.
+Unlike the memory tools, `datapack_id` has no default here — you must
+pass it explicitly. `agent_id` is **ignored for filtering** on this
+tool (KB results are team-shared on the datapack), but you still pass
+it — your session's value is fine.
 
-## Tracked gaps
-
-- **Upstream GitHub**: [yugabyte/meko-mcp-server#89](https://github.com/yugabyte/meko-mcp-server/issues/89) — disable or gate KB ingestion tools on cloud until the S3 path works end-to-end; return a clearer error than "not_available"; validate schemes at MCP-call time.
-- **Upstream Jira**: MEKO-96 (same issue, cross-linked).
-
-When either lands, the free-tier-gate responses above will change and this page should be revisited.
-
-## Response-shape reference (for agents that need to parse)
-
-### knowledgebase_search
+## Response shape
 
 Populated KB:
+
 ```
 {
   "results": [
@@ -97,38 +49,21 @@ Populated KB:
 }
 ```
 
-Empty or nonexistent KB: `{"results": [], "count": 0}` (no error).
-
-### knowledgebase_trigger_index_creation (when not gated)
-
-Success shape:
-```
-{
-  "source_ids": ["<uuid>", ...],
-  "index_id": "<uuid>",
-  "index_name": "<name>",
-  "status": "build_triggered",
-  "message": "N source(s) registered, index '...' initialised, and build triggered."
-}
-```
-
-Do NOT retry this on failure. Each call creates a new index.
-
-### knowledgebase_add_source_to_index (when not gated)
-
-The historical `r_index_name` vs `r_index_id` parameter-mismatch bug is fixed on main (`src/tools.py` resolves `index_name → index_id` via `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` before calling the dist_rag function). If `index_name` doesn't exist you get `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`.
-
-Param is `source_uri` (URI string like `s3://bucket/path/`), **not** `source_id` as older docs may claim.
+Empty or nonexistent KB: `{"results": [], "count": 0}` (no error,
+just an empty array).
 
-### knowledgebase_check_index_status (when not gated)
+## UI ingestion — what the user sees
 
-Returns `pipeline_details` (per-document status) and `pipeline_stats` (aggregated). Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details`.
-
-Stuck at INIT for >5 minutes under self-hosted usually means the worker couldn't reach the bucket — check AWS credentials on the worker host, not the MCP server.
-
-## Prerequisites (self-hosted)
+From `cloud.mekodata.ai`:
 
-- `dist_rag` PostgreSQL extension enabled on the target YugabyteDB database
-- Ingestion workers running (`yugabyte-db/python/ai/rag_agent/`)
-- AWS credentials on the worker host for any S3 bucket you intend to ingest from
-- `datapack_id` passed on every call when targeting a non-default datapack
+1. Open a datapack (`/datapacks/<name>`).
+2. Click **Actions** → **Add Knowledge**.
+3. Drag-and-drop or browse for files. Supported: PDF, TXT, MD, JSON,
+   MP4. Per-file limit 5 MB. Up to 10 files per batch.
+4. The UI handles upload, storage, and index build. The user does not
+   pick a bucket or provide credentials.
+5. Search results from `knowledgebase_search` become available once
+   indexing completes.
+
+If a user asks you "how do I add a document to my knowledge base?",
+point them at this flow.