@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/assets/skills/meko-mcp-tools-desktop/references/tools-agent-id-conventions.md

@@ -0,0 +1,99 @@
+# agent_id — multi-agent identity on Cloud Meko
+
+`agent_id` identifies **which agent wrote a memory or created a conversation**. It is not a constant. Pick a value that represents the specific agent + project you're acting for, use it consistently for writes within this session, and use it to scope your own reads.
+
+The Cloud UI (`cloud.mekodata.ai`) renders `agent_id` as a badge on every memory and conversation row — so the value you pick is user-visible. Multiple different agents with different `agent_id` values can write into the same datapack; each one's personal view is scoped to itself, and the UI shows the full cross-agent picture.
+
+## The three buckets
+
+Memories segregate strictly by `agent_id`. Pick the right bucket up front:
+
+| Pattern | When to use | Example |
+|---|---|---|
+| Loose client name | Claude Desktop and other non-coding clients — there's no per-project concept, so the bare client name is the right granularity. | `claude_desktop` |
+| `<client>:<repo-basename>` | Coding agents (Claude Code, Cursor) writing project-scoped facts. **Not used by Claude Desktop**, but you'll see these values on rows written by other clients in the same datapack. | `claude_code:meko-mcp-server` |
+| `meko_agent` | Cross-project common bucket — facts any agent should see regardless of project (user identity, global preferences). The server stores empty/missing `agent_id` here automatically. | `meko_agent` |
+
+**For Claude Desktop, the practical default is `claude_desktop` for personal context and `meko_agent` for genuinely cross-client facts.** When the user's information is project-agnostic ("the user is named Amiram", "the user prefers vim"), prefer `meko_agent` so other clients (Claude Code, Cursor) can see it too.
+
+## Valid characters
+
+The server stores `agent_id` as a row-level column value — it never becomes a PostgreSQL identifier on Cloud. Any printable string works: colons, hyphens, dots, underscores, spaces. Stay within what's readable in the UI badge.
+
+Pre-existing data in real datapacks includes a mix of legacy shapes — `agent`, `claude-code`, `claude_code`, `cursor:<slug>`, `claude-code:-Users-...`, `claude-desktop` (hyphenated). None of them cause errors. To query those rows, pass the literal legacy value as `agent_id`. New writes should follow the table above.
+
+## How agent_id filters reads and writes
+
+### Writes — `memory_add`, `conversation_create`, `conversation_add_message`
+
+- The row stores `(meko_datapack_id, meko_user_id, meko_agent_id)` — the user_id comes from your cognito account; the datapack_id defaults or is explicit; the agent_id is what you pass.
+- If you pass an empty or whitespace-only `agent_id`, the server stores `meko_agent`. That's the common bucket — fine for cross-client facts; not what you want for desktop-personal writes.
+
+### Personal reads — `memory_search`, `memory_get_all`, `conversation_list`, `conversation_get`
+
+Filter tuple: `(datapack_id, user_id, agent_id)`.
+
+- `user_id` is **always enforced**: you can only see memories and conversations you wrote (or that other team members shared with you via promotion — see below). One user cannot read another team member's un-promoted memories directly from MCP.
+- `agent_id` is **strictly matched**: a search with `agent_id="claude_desktop"` returns only rows whose stored value is exactly that. Memories written from `agent_id="claude_code:foo"` are invisible to it.
+- An empty `agent_id` is rewritten to `meko_agent` server-side, so a "broad" read with empty string returns only common-bucket rows — **not** a cross-client fan-out. To search across multiple agent_ids, call once per known value.
+
+Empirically verified 2026-05-19 on Cloud prod (free-tier multitenant mode, segregation via row-level filter).
+
+### Team-shared reads — `knowledgebase_search`
+
+Filter tuple: `(datapack_id)` only. **`agent_id` on the request is ignored.** Whatever value you pass, `knowledgebase_search` returns every row on the datapack.
+
+This is the multi-user, multi-agent read path. Content in `knowledgebase_search` is shared across:
+- All agents on the datapack (any `agent_id` value)
+- All users with access to the datapack (`user_id` is not a column on the shared table)
+
+The originating `agent_id` is preserved in each result's `metadata_filters.agent_id` for provenance, but it does not affect which rows come back.
+
+## What lives where
+
+```
+memory_add(agent_id=X, text=...)
+   │
+   ▼
+mem0_collection  ── personal memories, scoped (datapack, user, agent)
+   │
+   │   UI "Promote to Knowledge" (Learnings tab)
+   │   ─────────────────────────────────────────
+   │   Strips user_id, keeps agent_id as metadata,
+   │   copies into team-shared table
+   ▼
+knowledge_base   ── team-shared, scoped (datapack) only
+   │
+   ▼
+knowledgebase_search(agent_id=anything, query=...)
+```
+
+- **Personal memories** are what you get from `memory_search` / `memory_get_all`. Private to you.
+- **Shared Knowledge** is what you get from `knowledgebase_search`. Visible to every user and every agent on the datapack.
+- **Promotion is UI-only.** There is no MCP tool for promoting a memory to Shared Knowledge — the user triggers it from the datapack's Learnings tab in the Cloud UI.
+
+## When to use what — broad-query guidance
+
+If the user asks "what do you know about X?" and you want to maximize recall:
+
+1. **First call**: `memory_search(agent_id="claude_desktop", query="X")` — returns your desktop-personal memories.
+2. **Second call**: `memory_search(agent_id="meko_agent", query="X")` — returns the common cross-project bucket: anything written with `agent_id="meko_agent"` from any client, plus rows the server stored under that name when called with empty `agent_id`.
+3. **Third call**: `knowledgebase_search(agent_id="<anything>", datapack_id="<datapack>", query="X")` — returns team-shared knowledge. Useful when the answer may have been promoted by the user or a teammate.
+
+For a true cross-agent fan-out (e.g. you also want to see what was written from `claude_code:some-repo` or `cursor:foo`), call `memory_search` once per known agent_id — the empty-string shortcut does not bypass the filter; the server rewrites empty to `meko_agent`.
+
+Always tell the user what scope you searched, so they understand why the answer is or isn't there. Example wording: "I found this in your desktop personal memories" vs. "I found this in your common cross-project bucket" vs. "I found this in your team's shared knowledge."
+
+## Sub-scoping within an agent
+
+Optional parameters narrow further within the same `agent_id`:
+- `user_id` — explicitly scope writes/reads to a specific end-user if your agent serves multiple (rare in Claude Desktop; more common in API products)
+- `run_id` — per-execution run
+
+Available on `memory_add`, `memory_search`, `memory_get_all`, `memory_delete_all`, `conversation_create`, `conversation_list`.
+
+## Things I checked and found in-data on real Cloud datapacks
+
+- `agent_id="agent"` appears on many legacy rows — it was the previous canonical constant. New writes should use the schema in the table above; query legacy rows with `agent_id="agent"` explicitly.
+- Memory Summary UI (`/datapacks/<name>/memory-summary`) is agent-id-agnostic — shows every row in the datapack, renders the stored `agent_id` as a badge. The filtering is MCP-side only.
+- Subagents spawned via the `Agent` tool in Claude Code do not automatically inherit the parent's `agent_id`. The parent must inject it into the spawn prompt. See the SKILL.md "When spawning subagents" section in the coding-agent skill.

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

@@ -0,0 +1,406 @@
+# 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.
+
+> **Note on `agent_id` in the examples below.** The string `"agent"` appears in these examples as a placeholder shorthand; it is NOT a required constant. Substitute **your** client's bucket: for Claude Desktop, the bare client name `claude_desktop`; for Claude Code/Cursor, `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts (user identity, global preferences) write/read with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
+>
+> **Note on availability on Cloud.** The `db_*` tools and the three KB ingestion tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) return `{"error": "not_available"}` on Cloud Meko today. This cookbook keeps their examples for reference but you can't call them from a Cloud client.
+
+---
+
+## Database Tools
+
+### db_summarize_database
+
+**When to use:** First thing in a session to understand what's in the database. Prefer this over writing your own `information_schema` query.
+
+```
+db_summarize_database(scope="read", schema="public")
+```
+
+**Response:**
+```json
+[
+  {
+    "table_name": "customers",
+    "schema": [
+      {"column_name": "id", "data_type": "uuid"},
+      {"column_name": "name", "data_type": "text"}
+    ],
+    "row_count": 1523
+  }
+]
+```
+
+**With datapack:**
+```
+db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
+```
+
+**Common errors:**
+- `Insufficient scope: 'all'` — Use `scope="read"`, not `"all"`
+- Empty result — The schema may not exist, try `schema="public"`
+
+---
+
+### db_run_read_only_query
+
+**When to use:** Any SELECT query. Always add `LIMIT` on exploratory queries.
+
+```
+db_run_read_only_query(scope="read", query="SELECT id, name FROM customers LIMIT 10")
+```
+
+**Response:** JSON array of row objects.
+```json
+[{"id": "abc-123", "name": "Alice"}, {"id": "def-456", "name": "Bob"}]
+```
+
+**Best practices:**
+- Always use `LIMIT` on unfamiliar tables to avoid flooding context
+- Select specific columns rather than `SELECT *` to keep responses small
+- For non-public schemas: `SELECT * FROM analytics."monthly_revenue" LIMIT 5`
+- Escape single quotes in values: `WHERE name = 'O''Brien'`
+
+**Common errors:**
+- `cannot execute INSERT in a read-only transaction` — Use `db_run_write_query` for writes
+- `permission denied for table X` — MCP user lacks access to this table (server-side config issue, not fixable via MCP)
+- `connection already closed` — Retry once. If persistent, the DB pool is unhealthy.
+
+---
+
+### db_run_write_query
+
+**When to use:** INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE INDEX.
+
+```
+db_run_write_query(scope="write", query="INSERT INTO customers (id, name) VALUES ('abc-123', 'Alice')")
+```
+
+**Response:**
+```json
+{"rows_affected": 1}
+```
+
+**One statement per call.** This is wrong:
+```
+db_run_write_query(scope="write", query="CREATE TABLE a (id INT); CREATE TABLE b (id INT);")
+```
+Split into two separate calls.
+
+**Bulk inserts:** Maximum 1000 rows per INSERT VALUES. For more, use `INSERT ... SELECT` or batch into multiple calls.
+
+**Common errors:**
+- `Multi-statement queries not allowed` — Send one statement per call
+- `DROP SCHEMA is not allowed` — See `tools-write-guardrails.md` for blocked operations
+- `'dict' object has no attribute 'guardrail_config'` — Known server bug in some deployments. Write operations may be unavailable.
+
+---
+
+## Memory Tools
+
+**Critical:** Pass your session's `agent_id` on every memory call. For Claude Desktop that's `claude_desktop` for client-personal context, or `meko_agent` for genuinely cross-project facts (user identity, global preferences). Personal writes are scoped strictly by `agent_id` — other agents won't see your writes on personal reads unless they pass the same exact value.
+
+### 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.
+
+```
+memory_add(scope="write", agent_id="agent",
+    text="User Amiram is VP of Product at YugabyteDB. Prefers concise responses.")
+```
+
+**Response:**
+```json
+{"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)
+
+**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.
+- `connection already closed` — Retry once. If it fails again, the memory subsystem is down.
+
+---
+
+### memory_search
+
+**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")
+```
+
+**Response:**
+```json
+{"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
+```
+
+**With limit:**
+```
+memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
+```
+
+---
+
+### memory_get_all
+
+**When to use:** List everything stored for an agent. 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_by_id
+
+```
+memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
+```
+
+---
+
+### memory_update
+
+**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_delete_by_id
+
+```
+memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="agent")
+```
+
+---
+
+### memory_delete_all
+
+**Destructive. Requires admin scope.** Deletes all memories for the agent.
+
+```
+memory_delete_all(scope="admin", agent_id="agent")
+```
+
+---
+
+## Conversation Tools
+
+### conversation_create
+
+**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",
+    title="Debugging the auth middleware")
+```
+
+**Response:**
+```json
+{"id": "conv-uuid-123", "title": "Debugging the auth middleware"}
+```
+
+---
+
+### conversation_add_message
+
+**When to use:** Add a user/assistant exchange to an existing conversation. **All fields must be verbatim** — never summarize or rephrase.
+
+```
+conversation_add_message(scope="write", 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...")
+```
+
+**With dedup seed (use when client hooks also write to Langfuse):**
+```
+conversation_add_message(scope="write", 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?")
+```
+
+---
+
+### conversation_get
+
+```
+conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="agent",
+    include_messages=True, limit=50)
+```
+
+---
+
+### conversation_list
+
+```
+conversation_list(scope="read", agent_id="agent", limit=20)
+```
+
+---
+
+### conversation_update
+
+```
+conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    title="Resolved: Auth middleware issuer mismatch")
+```
+
+---
+
+### conversation_delete
+
+**Destructive. Requires admin scope.**
+
+```
+conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="agent")
+```
+
+---
+
+## RAG / 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.
+
+See `tools-rag-workflow.md` for the decision table and why.
+
+### knowledgebase_search
+
+**When to use:** Retrieve chunks from a populated KB. Works on cloud today.
+
+```
+knowledgebase_search(
+    scope="read",
+    query="natural-language question",
+    agent_id="agent",
+    conversation_id="<uuid from conversation_create>",
+    datapack_id="<datapack UUID — REQUIRED here, no default>",
+    limit=10)
+```
+
+Unlike memory tools, `datapack_id` has no default — you must pass it explicitly.
+
+**Response (empty KB, verified 2026-05-07):**
+```json
+{"results": [], "count": 0}
+```
+
+Populated KBs return results with chunk content and similarity scores. An empty/nonexistent KB is not an error — just `count: 0`.
+
+---
+
+### knowledgebase_trigger_index_creation
+
+**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."}`).
+
+```
+knowledgebase_trigger_index_creation(
+    scope="write",
+    conversation_id="<uuid from conversation_create>",
+    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
+    index_name="company_docs")
+```
+
+**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:**
+```json
+{"source_ids": ["<uuid>", ...], "index_id": "<uuid>", "index_name": "company_docs",
+ "status": "build_triggered", "message": "... registered, index '...' initialised, and build triggered."}
+```
+
+**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.
+
+---
+
+### knowledgebase_check_index_status
+
+**When to use:** Poll a self-hosted build for completion. **Not available on cloud Free Tier** (returns `{"error": "not_available"}`).
+
+```
+knowledgebase_check_index_status(
+    scope="read",
+    conversation_id="<uuid from conversation_create>",
+    index_name="company_docs",
+    datapack_id=None)
+```
+
+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/")
+```
+
+Param is **`source_uri`** (URI string), not `source_id` — older docs had this wrong.
+
+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 '...'"}`.
+
+Same S3-only / worker-credentials caveats as `trigger_index_creation` apply.
+
+---
+
+## Datapack Management Tools
+
+### 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_update / datapack_delete
+
+```
+datapack_update(scope="write", name="analytics_prod", connection_string="postgresql://...")
+datapack_delete(scope="admin", name="analytics_prod")  # 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.
+
+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.

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

@@ -0,0 +1,69 @@
+# Known Limitations
+
+These are current limitations of the Meko MCP tools. Know them upfront to avoid wasted tool calls.
+
+## No delete tools for RAG artifacts
+
+There are no MCP tools to:
+- Delete a vector index
+- Remove a source from an index
+- 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.
+
+**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
+
+The RAG tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) handle index **creation and monitoring** only.
+
+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.
+
+## Memory tools unreliable for structured/tabular data
+
+`memory_add` passes text through Mem0's fact extraction pipeline. This works well for:
+- Facts: "Alice works at Acme Corp"
+- Preferences: "User prefers dark mode"
+- Entity relationships: "Amiram reports to Karthik"
+
+It works **poorly** for:
+- CSV rows or tabular data — columns and rows get dropped
+- 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:
+
+1. **Write a single narrative summary** as a memory — one call, not row-by-row:
+   ```
+   memory_add(scope="write",
+       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.
+
+Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
+
+## MCP user permission gaps
+
+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
+
+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.