@yugabytedb/meko-mcp 1.0.8 → 1.2.0

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

@@ -1,17 +1,21 @@
 # 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`
+
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
-1. `db_summarize_database(scope="read")` — Confirms DB connection is working. Also doubles as the `agent_id` discovery step (see the main SKILL.md) — look for `<x>_mem0_collection` tables with rows.
-2. `memory_search(scope="read", query="test", agent_id="<discovered>")` — Confirms memory subsystem is up. Substitute the `agent_id` you found in step 1. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-3. `datapack_list(scope="read")` — Confirms Meko API connectivity
-
-If memory tools fail but DB tools work, you can read memory data directly:
-```
-db_run_read_only_query(scope="read", query="SELECT id, payload FROM default_mem0_collection LIMIT 20")
-```
+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.
 
 ## Decision tree: which tool do I need?
 
@@ -21,21 +25,22 @@ User wants to...
 │   ├── 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)
-├── Build or check a knowledge base (RAG)?
-│   ├── Create a new index from sources? -> knowledgebase_trigger_index_creation (write)
-│   ├── Add source to existing index? ---> knowledgebase_add_source_to_index (write)
-│   └── Check build progress? -----------> knowledgebase_check_index_status (read)
+├── 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
 ├── 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)
 │   └── Retrieve a past conversation? -------------> conversation_get (read)
 └── Manage datapacks?
-    ├── CRUD datapack? -> datapack_create/list/describe/update/delete
-    ├── Manage agents? -> datapack_create_agent/list_agents/delete_agent
-    └── Manage KB sources? -> datapack_add_knowledge_base/list/delete_knowledge_base
+    └── 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 |
@@ -44,39 +49,40 @@ User wants to...
 | `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 (3)
+## RAG / Knowledge Base Tools (4)
 
 | Tool | Scope | Purpose |
 |------|-------|---------|
-| `knowledgebase_trigger_index_creation(scope, 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 |
-| `knowledgebase_add_source_to_index(scope, index_name, source_id, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Add a new source to an existing index |
-| `knowledgebase_check_index_status(scope, index_name, datapack_id=None)` | read | Check build progress via `dist_rag.vector_index_pipeline_details` |
+| `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. |
 
-## Memory Tools (7)
+## Memory Tools (8)
 
 | Tool | Scope | Purpose |
 |------|-------|---------|
-| `memory_add(scope, text, agent_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, user_id=None, limit=10, datapack_id=None)` | read | Semantic search across memories + graph relations |
-| `memory_get_by_id(scope, memory_id, agent_id, datapack_id=None)` | read | Retrieve a single memory by UUID |
-| `memory_get_all(scope, agent_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, datapack_id=None)` | write | Overwrite memory text |
-| `memory_delete_by_id(scope, memory_id, agent_id, datapack_id=None)` | write | Delete a single memory |
-| `memory_delete_all(scope, agent_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | admin | Delete all memories for agent (destructive) |
+| `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. |
 
-## Conversation Tools (7)
+## 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, user_id=None, limit=20, offset=0)` | read | List conversations for agent |
+| `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_message(scope, conversation_id, agent_id, trace_id)` | write | Delete a single message |
 | `conversation_delete(scope, conversation_id, agent_id)` | admin | Delete entire conversation (destructive) |
 
-## Datapack Management Tools (11)
+## Datapack Management Tools (5)
 
 | Tool | Scope | Purpose |
 |------|-------|---------|
@@ -85,12 +91,21 @@ User wants to...
 | `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) |
-| `datapack_create_agent(scope, datapack_name, agent_name, agent_metadata=None)` | write | Create agent in datapack |
-| `datapack_list_agents(scope, datapack_name)` | read | List agents in datapack |
-| `datapack_delete_agent(scope, datapack_name, agent_name)` | admin | Delete agent |
-| `datapack_add_knowledge_base(scope, datapack_name, url)` | write | Add KB source URL |
-| `datapack_list_knowledge_bases(scope, datapack_name)` | read | List KB sources |
-| `datapack_delete_knowledge_base(scope, datapack_name, url)` | admin | Delete KB source |
+
+## Platform capabilities NOT exposed via MCP
+
+Some things the Meko platform can do are not wired into the MCP tool surface today. If a user asks about them, do not invent MCP tool calls — point them at the appropriate control plane instead. Agents attempting these as MCP tools will hit "tool not found".
+
+| 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` |
+| 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.
 
 ## Common Parameter Patterns
 

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

@@ -1,63 +1,134 @@
-# End-to-End RAG Pipeline Workflow
+# Knowledge Base / RAG workflow
 
-**WRONG:** Calling `knowledgebase_check_index_status` before creating the index (returns empty), or `knowledgebase_add_source_to_index` for initial creation (fails — index doesn't exist yet).
+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.
 
-## Step 1: Create the index from sources
+This page tells you which tool to reach for, what's usable where, and where the current gaps are tracked.
 
-`knowledgebase_trigger_index_creation` registers sources, initializes the vector index, and triggers the build in one call:
+## 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 |
+
+## knowledgebase_search — the one you'll actually call
 
 ```
-knowledgebase_trigger_index_creation(
-    scope="write",
-    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
-    index_name="company_docs"
-)
--- Returns: {"source_ids": [...], "index_name": "company_docs", "status": "build_triggered"}
+knowledgebase_search(
+    scope="read",
+    query="natural-language question",
+    agent_id="<your agent_id>",
+    conversation_id="<uuid from conversation_create>",
+    datapack_id="<datapack UUID — REQUIRED on this tool>",
+    limit=10)
 ```
 
-## Step 2: Poll for build completion
+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):
 ```
-knowledgebase_check_index_status(scope="read", index_name="company_docs")
+{"results": [], "count": 0}
 ```
 
-Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details` to know when all documents are fully indexed.
+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.
 
-## Step 3: Add more sources later
+## MCP ingestion tools — what actually happens when you call them
 
-Once an index exists, use `knowledgebase_add_source_to_index` with a pre-registered `source_id` (UUID, not URI):
+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.
 
-```
-knowledgebase_add_source_to_index(scope="write", index_name="company_docs", source_id="new-source-uuid")
-```
+**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.
 
-## Tool selection guide
+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.
 
-| Situation | Tool |
-|-----------|------|
-| First time creating a RAG index | `knowledgebase_trigger_index_creation` |
-| Adding a source to an existing index | `knowledgebase_add_source_to_index` |
-| Checking if build is complete | `knowledgebase_check_index_status` |
+## Tracked gaps
 
-## Troubleshooting: Pipeline stuck at INIT
+- **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).
 
-If `knowledgebase_check_index_status` returns empty `pipeline_details` or documents remain at `INIT` status for more than 5 minutes, the build workers have likely stalled.
+When either lands, the free-tier-gate responses above will change and this page should be revisited.
 
-**Diagnosis:** Query the work queue directly:
+## Response-shape reference (for agents that need to parse)
+
+### knowledgebase_search
+
+Populated KB:
+```
+{
+  "results": [
+    {
+      "content": "<chunk text>",
+      "similarity": 0.87,
+      "source_uri": "<original source URI>",
+      "document_name": "<file key>",
+      ...
+    },
+    ...
+  ],
+  "count": <int>
+}
 ```
-db_run_read_only_query(scope="read",
-    query="SELECT task_type, status, lease_expires_at FROM dist_rag.work_queue WHERE index_name = 'your_index' ORDER BY created_at DESC LIMIT 10")
+
+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.
 
-Tasks stuck `IN_PROGRESS` with `lease_expires_at` in the past indicate crashed workers. **Stop polling after 3 consecutive no-progress checks** — continued polling wastes context. See `tools-troubleshooting.md` for full recovery strategies.
+### knowledgebase_check_index_status (when not gated)
 
-## Limitations
+Returns `pipeline_details` (per-document status) and `pipeline_stats` (aggregated). Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details`.
 
-- There is **no MCP tool to delete** a vector index, remove a source from an index, or reset stuck work queue tasks.
-- There is **no MCP tool to query** a built index — use `db_run_read_only_query` with `dist_rag` SQL functions directly.
-- `knowledgebase_add_source_to_index` has a **known parameter mismatch bug**. Prefer `knowledgebase_trigger_index_creation` with all sources at once.
-- Each `knowledgebase_trigger_index_creation` call creates a new index. **Do not retry on failure** — you'll create duplicates.
+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.
 
-## Prerequisite
+## Prerequisites (self-hosted)
 
-All RAG tools require the `dist_rag` PostgreSQL extension in the target database. Pass `datapack_id` to all calls when targeting a specific datapack.
+- `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

package/assets/skills/meko-mcp-tools/references/tools-scope-permissions.md

@@ -17,7 +17,7 @@ Higher scopes include lower scopes. An unrecognized scope string always fails.
 
 ## Per-Tool Requirements
 
-### read scope (12 tools)
+### read scope (11 tools)
 
 | Tool | Group |
 |------|-------|
@@ -27,14 +27,13 @@ Higher scopes include lower scopes. An unrecognized scope string always fails.
 | `memory_search` | Memory |
 | `memory_get_by_id` | Memory |
 | `memory_get_all` | Memory |
+| `flush_pending_memory_candidates` | Memory |
 | `conversation_get` | Conversation |
 | `conversation_list` | Conversation |
 | `datapack_list` | Datapack |
 | `datapack_describe` | Datapack |
-| `datapack_list_agents` | Datapack |
-| `datapack_list_knowledge_bases` | Datapack |
 
-### write scope (14 tools)
+### write scope (11 tools)
 
 | Tool | Group |
 |------|-------|
@@ -47,21 +46,18 @@ Higher scopes include lower scopes. An unrecognized scope string always fails.
 | `conversation_create` | Conversation |
 | `conversation_add_message` | Conversation |
 | `conversation_update` | Conversation |
-| `conversation_delete_message` | Conversation |
 | `datapack_create` | Datapack |
 | `datapack_update` | Datapack |
-| `datapack_create_agent` | Datapack |
-| `datapack_add_knowledge_base` | Datapack |
 
-### admin scope (5 tools — destructive, irreversible)
+### admin scope (3 tools — destructive, irreversible)
 
 | Tool | Group |
 |------|-------|
 | `memory_delete_all` | Memory |
 | `conversation_delete` | Conversation |
 | `datapack_delete` | Datapack |
-| `datapack_delete_agent` | Datapack |
-| `datapack_delete_knowledge_base` | Datapack |
+
+Agent and knowledge-base lifecycle tools are not MCP-exposed — see "Platform capabilities NOT exposed via MCP" in `tools-overview.md`.
 
 ## Best Practices
 

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

@@ -7,7 +7,7 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
 2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
 3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
-4. **Cache what you learn within a session.** Once you've discovered the user's `agent_id` via `db_summarize_database` (see the main SKILL.md), reuse it for every subsequent call in this session. Re-run discovery on the next session.
+4. **Use your session's `agent_id` consistently.** Pass the value the SessionStart hook injected (e.g. `claude_code:<repo-basename>` for Claude Code; `claude_desktop` for Claude Desktop) on every write and every personal read. Use `agent_id="meko_agent"` deliberately on `memory_search`/`memory_get_all` only when you want the cross-project common bucket — empty string also resolves to `meko_agent`, not a cross-agent fan-out. Don't switch between forms mid-session.
 
 ---
 
@@ -19,14 +19,9 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 **What to do:**
 
-1. Retry the same call **once**
-2. If it fails again, the memory subsystem is unhealthy for this session
-3. Fall back to direct SQL to read memory data:
-   ```
-   db_run_read_only_query(scope="read",
-       query="SELECT id, payload FROM default_mem0_collection LIMIT 20")
-   ```
-   Replace `default` with your `agent_id` prefix if using a custom agent.
+1. Retry the same call **once**.
+2. If it fails again, the memory subsystem is unhealthy for this session — stop trying memory calls and tell the user. Do not waste tokens re-sending the same payload.
+3. Direct-SQL fallback **does not apply** on cloud Free Tier (`db_run_read_only_query` returns `{"error": "not_available", "detail": "Free Tier: DB Tools access is not enabled. coming soon."}`). On self-hosted / paid deployments where DB tools are available, inspect memory rows via the multi-tenant schema — tables are namespaced by datapack, not by agent_id. The old `{agent_id}_mem0_collection` per-agent-table layout is gone.
 
 **Anti-pattern from real sessions:** Agent called `memory_add` with 500+ tokens of text, got "connection already closed", retried the identical call 3 more times (each 500+ tokens). Wasted ~2000 tokens on guaranteed failures.
 
@@ -77,12 +72,19 @@ Look for tasks stuck `IN_PROGRESS` with expired leases — these indicate crashe
 
 ## knowledgebase_add_source_to_index failure
 
-**Error:** SQL function signature mismatch — the tool passes `r_index_name` (string) but the DB function expects `r_index_id` (UUID).
+**Error shape:** `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`
 
-**What to do:**
+You're on cloud Free Tier; the ingestion tools are gated off. There is no retry that will succeed. Point the user at the Meko UI's **Add Knowledge** file-upload flow (Datapack → Actions → Add Knowledge) instead.
+
+**Error shape:** `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`
+
+The `index_name` doesn't exist in this datapack's `dist_rag.vector_indexes` table. Either you're targeting the wrong datapack (check `datapack_id`), or the index hasn't been created yet — call `knowledgebase_trigger_index_creation` first.
 
-1. Do NOT try different parameter formats (string name, UUID, etc.) — the bug is in the tool, not your parameters.
-2. **Workaround:** Use `knowledgebase_trigger_index_creation` with all sources included upfront instead of adding sources incrementally.
+**Error shape:** tool returns `"build_triggered"` but `knowledgebase_check_index_status` shows documents stuck at `INIT` for >5 minutes.
+
+Most common cause on self-hosted deployments: the worker can't reach the S3 bucket. `S3BucketCrawler()` uses boto3's default credential chain — check `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / IAM role / `~/.aws/credentials` on the worker host, not on the MCP server. Second cause: the URI isn't `s3://`-prefixed (`aws_source_processor.py` rejects other schemes with `ValueError("Invalid source URI")` async).
+
+**Historical note:** the old `r_index_name` vs `r_index_id` parameter-mismatch bug is fixed on main — the MCP tool now resolves `index_name → index_id` internally via a `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` step. Older docs referencing this bug are stale.
 
 ---
 
@@ -102,13 +104,23 @@ The only valid scope values are: `"read"`, `"write"`, `"admin"`.
 
 ## agent_id errors
 
-**Error:** `syntax error at or near "-"` in table creation.
+On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.
+
+`agent_id` is **not a constant**. Cloud Meko supports multiple agents on one datapack, and the Cloud UI renders every `agent_id` as a badge on each row regardless of value. The canonical shape for new writes is `<client>:<repo-basename>` for coding agents (e.g. `claude_code:meko-mcp-server`), a bare client name for non-coding clients (e.g. `claude_desktop`), or `meko_agent` for the cross-project common bucket — see `tools-agent-id-conventions.md`.
+
+### "My writes are landing in `meko_agent` instead of my agent's bucket"
+
+If you call `memory_add` with empty / None / whitespace `agent_id`, the server does NOT reject the write. It silently resolves the value to `meko_agent` (the cross-project common bucket) and the row lands there. The Cloud UI then shows a `meko_agent` badge instead of your client's badge.
+
+Fix: always pass a concrete non-empty `agent_id`. Fetch the value the SessionStart hook injected into `additionalContext` and pass it verbatim. Use `agent_id="meko_agent"` only when you genuinely want a fact in the cross-project pool (user identity, global preferences).
+
+### "My reads return fewer results than I expected"
+
+`memory_search` and `memory_get_all` filter strictly on your passed `agent_id`. A memory written by `claude-code:<slug-A>` is invisible to a search with `agent_id="cursor:<slug-B>"`. If you need a broader view, call repeatedly across the agent_ids you want to cover, or point the user at the UI's Memory Summary page (which shows every row regardless of agent_id).
 
-`agent_id` is used in PostgreSQL table names. Hyphens are invalid in unquoted identifiers.
+### "I'm seeing rows tagged with legacy agent_id values"
 
-**Rule:** Lowercase letters, digits, underscores only.
-- Good: `"claude_code"`, `"support_bot"`, `"agent_001"`
-- Bad: `"claude-code"`, `"my agent"`, `"agent.one"`
+Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, or similar ad-hoc values. All remain readable. New writes should follow the canonical `<client>:<project-slug>` form; don't try to retag old rows.
 
 ---