@yugabytedb/meko-mcp 1.2.0 → 2.1.0

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

@@ -7,13 +7,13 @@ 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. **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.
+4. **Use your session's `agent_id` consistently on writes.** Pass the value the SessionStart hook injected (e.g. `claude_code:<repo-basename>` for Claude Code; `claude_desktop` for Claude Desktop) on every write so rows are attributed correctly, and on `conversation_get` (which *does* enforce it — conversations are owned by the `agent_id` that created them; a wrong value returns `agent_id_mismatch`). Memory reads (`memory_search`/`memory_get_all`) and `conversation_list` are not affected — they return all your agents' rows for this user regardless of the `agent_id` passed. Don't switch write forms mid-session.
 
 ---
 
 ## Connection errors: "connection already closed"
 
-**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently. DB tools less often.
+**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently.
 
 **Why it happens:** The Python memory subsystem uses a connection cache that doesn't recover from dropped connections (unlike the Go API server which has retry logic with 5 retries and 3-second delays).
 
@@ -21,87 +21,11 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 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.
 
 ---
 
-## RAG pipeline stuck at INIT
-
-**Affects:** `knowledgebase_trigger_index_creation` — the build triggers but never completes.
-
-**Symptoms:**
-- `knowledgebase_check_index_status` returns empty `pipeline_details` and `pipeline_stats`
-- Documents remain at `INIT` status indefinitely
-- Work queue tasks are `IN_PROGRESS` with `lease_expires_at` in the past
-
-**Diagnosis:** Query the work queue directly:
-```
-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")
-```
-
-Look for tasks stuck `IN_PROGRESS` with expired leases — these indicate crashed or hung workers.
-
-**What to do:**
-
-1. Poll status **at most 3 times** with 1-2 minute intervals
-2. If no progress after 3 checks, **stop polling** — the pipeline is stuck
-3. There is **no way to reset or retry stuck tasks via MCP tools**
-4. Creating a new index with a different name (e.g., `_v2`) is a workaround, but if the workers themselves are down, this will also get stuck
-5. Recommend the user check worker logs or restart the pipeline service
-
-**Anti-pattern from real sessions:** Agent created indexes `v1`, `v2`, `v3` — all stuck with the same symptoms. Even making the S3 bucket public didn't help. The issue was worker infrastructure, not permissions.
-
----
-
-## db_run_write_query guardrail error
-
-**Error:** `'dict' object has no attribute 'guardrail_config'`
-
-**Affects:** `db_run_write_query` in some deployments.
-
-**What to do:**
-
-1. Try the call once. If it fails with this specific error, write operations are unavailable in this deployment.
-2. For reads, always use `db_run_read_only_query` (never `db_run_write_query` for SELECT).
-3. Report the issue — it's a server-side bug, not a parameter problem.
-
----
-
-## knowledgebase_add_source_to_index failure
-
-**Error shape:** `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`
-
-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.
-
-**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.
-
----
-
-## Scope parameter errors
-
-**Error:** `Insufficient scope: 'all'. This tool requires 'read' or higher.`
-
-The only valid scope values are: `"read"`, `"write"`, `"admin"`.
-
-- Use `"read"` for all read operations (default choice)
-- Use `"write"` for inserts, updates, creates, memory writes
-- Use `"admin"` only for destructive deletes
-
-**Never use:** `"all"`, `"readwrite"`, `"rw"`, or any other value.
-
----
-
 ## agent_id errors
 
 On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.
@@ -114,9 +38,9 @@ If you call `memory_add` with empty / None / whitespace `agent_id`, the server d
 
 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"
+### "My memory 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).
+`memory_search` and `memory_get_all` do **not** filter by `agent_id` — a single call returns all of your memories for this user across every agent, so a mismatched `agent_id` is not the cause. If results seem thin, check that you're on the right datapack (`datapack_id`), that the write actually landed (mem0 extraction is lossy — see `tools-memory-vs-conversation.md`), and that the query is semantically close to the stored text. `conversation_get`, by contrast, *is* agent-owned: pass the exact `agent_id` the conversation was created under, or you'll get `agent_id_mismatch`. `conversation_list` is not agent-filtered — it returns the datapack's conversations for your user regardless of the `agent_id` passed.
 
 ### "I'm seeing rows tagged with legacy agent_id values"
 
@@ -124,32 +48,14 @@ Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, o
 
 ---
 
-## Permission denied on data tables
-
-**Error:** `permission denied for table customer_complaints`
-
-**Why:** The MCP database user may not have read access to all tables, particularly data tables created by the provisioning system within a datapack.
-
-**What to do:**
-
-1. This is a server-side configuration issue — not fixable via MCP tools.
-2. Don't retry. Don't try different query formulations.
-3. Use `db_summarize_database` to see which tables you CAN access.
-4. Report the permission gap to the Meko admin.
-
----
-
 ## Safe-to-retry vs not
 
 | Tool | Safe to retry? | Why |
 |------|---------------|-----|
-| All `read` scope tools | Yes | Reads are idempotent |
+| All read-only tools | Yes | Reads are idempotent |
 | `memory_add` | Yes (once) | Mem0 has dedup logic |
 | `memory_update` | Yes (once) | Overwrites same ID |
 | `memory_delete_by_id` | Yes | Deleting already-deleted is a no-op |
-| `db_run_write_query` (INSERT) | **No** | May double-insert rows |
-| `db_run_write_query` (CREATE TABLE) | **No** | "Table already exists" error |
-| `knowledgebase_trigger_index_creation` | **No** | Creates duplicate indexes |
 | `conversation_create` | **No** | Creates duplicate conversations |
 | `conversation_add_message` with `seed` | Yes | Seed-based dedup prevents duplicates |
 | `conversation_add_message` without `seed` | **No** | Creates duplicate messages |

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

@@ -1,6 +1,6 @@
 # user_id — identity scoping on Cloud Meko
 
-On Cloud Meko, every write and every personal read carries a `user_id` that identifies **who** (the cognito account) is calling. The filter tuple for personal memories and conversations is `(datapack_id, user_id, agent_id)` — you only ever see memories your own user_id wrote (or content other team members have explicitly promoted to Shared Knowledge, which is separate — see `tools-agent-id-conventions.md`).
+On Cloud Meko, every write and every personal read carries a `user_id` that identifies **who** (the cognito account) is calling. The read filter for personal **memories** is `(datapack_id, user_id)` — you see all your own memories for this user regardless of which agent wrote them (`agent_id` labels the writer but does not filter memory reads). Personal **conversation fetches** (`conversation_get`) additionally enforce `agent_id` — conversations are owned by the agent that created them; `conversation_list` does not filter by it. Either way you only ever see content your own user_id wrote (or content other team members have explicitly promoted to Shared Knowledge, which is separate — see `tools-agent-id-conventions.md`).
 
 ## The default behavior: automatic user_id from cognito
 
@@ -9,7 +9,7 @@ On Cloud, the server resolves your `user_id` automatically from the cognito acco
 This is the common case for Claude Code / Claude Desktop / Cursor:
 
 ```
-memory_add(scope="write",
+memory_add(
            text="User prefers concise responses, no emojis.",
            agent_id="claude_code:meko-mcp-server",
            conversation_id="<session conversation_id>")
@@ -24,21 +24,21 @@ Explicit `user_id` is an **optional sub-scope** for agents that serve multiple e
 
 ```
 # Serving Alice
-memory_add(scope="write",
+memory_add(
            text="Alice prefers email communication. Has Pro plan.",
            agent_id="support-bot",
            user_id="alice_123",
            conversation_id="<conv>")
 
 # Serving Bob — completely separate partition, same cognito account
-memory_add(scope="write",
+memory_add(
            text="Bob prefers Slack. On Enterprise plan.",
            agent_id="support-bot",
            user_id="bob_456",
            conversation_id="<conv>")
 
 # Search only returns Alice's memories
-memory_search(scope="read",
+memory_search(
               query="communication preference",
               agent_id="support-bot",
               user_id="alice_123",
@@ -60,11 +60,12 @@ Mixing creates invisible data.
 
 | Layer | Filter | Role of user_id |
 |---|---|---|
-| Personal memories (`memory_add`, `memory_search`, `memory_get_all`) | `(datapack_id, user_id, agent_id)` | Enforced on every read. One user cannot see another's un-promoted memories. |
-| Personal conversations (`conversation_list`, `conversation_get`) | Same tuple | Enforced. Cross-user reads require promotion. |
+| Personal memories (`memory_add`, `memory_search`, `memory_get_all`) | `(datapack_id, user_id)` | Enforced on every read. `agent_id` is not applied — one user sees all their own memories across every agent, but cannot see another user's un-promoted memories. |
+| Conversation listing (`conversation_list`) | `(datapack_id, user_id)` | Enforced. `agent_id` is not applied — you see all your own conversations across every agent. |
+| Conversation fetch (`conversation_get`) | `(datapack_id, user_id, agent_id)` | Enforced. Agent-owned: pass the creating `agent_id` or you get `agent_id_mismatch`. Cross-user reads require promotion. |
 | Team Shared Knowledge (`knowledgebase_search`) | `(datapack_id)` only | **Not used** — `user_id` is stripped when a memory is promoted to Knowledge. All team members on the datapack see the same Shared Knowledge. |
 
-The "Promote to Knowledge" action in the Cloud UI is the one way personal content crosses the user_id boundary. There is no MCP tool for promotion (user-initiated via UI only).
+Personal content crosses the `user_id` boundary through `memory_promote` or the Cloud UI's "Promote to Knowledge" action. The MCP path requires exact memory UUIDs, explicit user confirmation, and an owner/maintainer role; it moves the records into team-visible Shared Knowledge and evicts the private copies.
 
 ## Parameter summary