@yugabytedb/meko-mcp 1.2.0 → 2.0.0

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

@@ -3,97 +3,6 @@
 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.** Where you see `agent_id="agent"` in an example, substitute **your** session's `agent_id` — the value the SessionStart hook injected into `additionalContext`. For Claude Code that's `claude_code:<repo-basename>` (e.g. `claude_code:meko-mcp-server`); for Cursor, `cursor:<repo-basename>`; for Claude Desktop, the bare client name `claude_desktop`. For genuinely cross-project facts (user identity, global preferences) write/read with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
->
-> **Note on availability on Cloud.** The `db_*` tools and the three KB ingestion tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) return `{"error": "not_available"}` on Cloud Meko today. This cookbook keeps their examples for reference but you can't call them from a Cloud client.
-
----
-
-## Database Tools
-
-### db_summarize_database
-
-**When to use:** First thing in a session to understand what's in the database. Prefer this over writing your own `information_schema` query.
-
-```
-db_summarize_database(scope="read", schema="public")
-```
-
-**Response:**
-```json
-[
-  {
-    "table_name": "customers",
-    "schema": [
-      {"column_name": "id", "data_type": "uuid"},
-      {"column_name": "name", "data_type": "text"}
-    ],
-    "row_count": 1523
-  }
-]
-```
-
-**With datapack:**
-```
-db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
-```
-
-**Common errors:**
-- `Insufficient scope: 'all'` — Use `scope="read"`, not `"all"`
-- Empty result — The schema may not exist, try `schema="public"`
-
----
-
-### db_run_read_only_query
-
-**When to use:** Any SELECT query. Always add `LIMIT` on exploratory queries.
-
-```
-db_run_read_only_query(scope="read", query="SELECT id, name FROM customers LIMIT 10")
-```
-
-**Response:** JSON array of row objects.
-```json
-[{"id": "abc-123", "name": "Alice"}, {"id": "def-456", "name": "Bob"}]
-```
-
-**Best practices:**
-- Always use `LIMIT` on unfamiliar tables to avoid flooding context
-- Select specific columns rather than `SELECT *` to keep responses small
-- For non-public schemas: `SELECT * FROM analytics."monthly_revenue" LIMIT 5`
-- Escape single quotes in values: `WHERE name = 'O''Brien'`
-
-**Common errors:**
-- `cannot execute INSERT in a read-only transaction` — Use `db_run_write_query` for writes
-- `permission denied for table X` — MCP user lacks access to this table (server-side config issue, not fixable via MCP)
-- `connection already closed` — Retry once. If persistent, the DB pool is unhealthy.
-
----
-
-### db_run_write_query
-
-**When to use:** INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE INDEX.
-
-```
-db_run_write_query(scope="write", query="INSERT INTO customers (id, name) VALUES ('abc-123', 'Alice')")
-```
-
-**Response:**
-```json
-{"rows_affected": 1}
-```
-
-**One statement per call.** This is wrong:
-```
-db_run_write_query(scope="write", query="CREATE TABLE a (id INT); CREATE TABLE b (id INT);")
-```
-Split into two separate calls.
-
-**Bulk inserts:** Maximum 1000 rows per INSERT VALUES. For more, use `INSERT ... SELECT` or batch into multiple calls.
-
-**Common errors:**
-- `Multi-statement queries not allowed` — Send one statement per call
-- `DROP SCHEMA is not allowed` — See `tools-write-guardrails.md` for blocked operations
-- `'dict' object has no attribute 'guardrail_config'` — Known server bug in some deployments. Write operations may be unavailable.
 
 ---
 
@@ -103,11 +12,11 @@ Split into two separate calls.
 
 ### memory_add
 
-**When to use:** Store facts, preferences, user profile info, org conventions, corrections, learnings. Use proactively — don't wait for the user to ask.
+**When to use:** NOT for facts the user states in conversation — those are saved automatically by conversation capture + server-side extraction. Reserve `memory_add` for the three cases extraction can't reach: (1) the user explicitly says "remember this"; (2) a durable fact that lives only in your output or a tool result, never in a user turn; (3) overwriting a negated/corrected fact (pair with `memory_delete_by_id`, since extraction is additive).
 
 ```
-memory_add(scope="write", agent_id="agent",
-    text="User Amiram is VP of Product at YugabyteDB. Prefers concise responses.")
+memory_add(scope="write", agent_id="<your-agent-id>",
+    text="Remember: deploy scripts must be run from the repo root, never a subdir.")
 ```
 
 **Response:**
@@ -122,9 +31,8 @@ memory_add(scope="write", agent_id="agent", user_id="amiram",
 ```
 
 **What NOT to store via memory_add:**
-- CSV rows or tabular data (use `db_run_write_query` instead)
 - Full conversations (use `conversation_create` + `conversation_add_message`)
-- Large documents (use knowledge base ingestion)
+- Large documents (use the UI's Datapack → Actions → Add Knowledge upload flow)
 
 **Common errors:**
 - `syntax error at or near "-"` — legacy error from the pre-multi-tenancy schema when `agent_id` became part of a PostgreSQL identifier. No longer applies on Cloud (agent_id is a TEXT column value, any string is accepted). If you hit it on a deployment that still uses the old schema, use underscores instead of hyphens.
@@ -225,11 +133,14 @@ conversation_create(scope="write", agent_id="agent", user_id="amiram",
 
 **When to use:** Add a user/assistant exchange to an existing conversation. **All fields must be verbatim** — never summarize or rephrase.
 
+Pass `index_for_search=True` on substantive turns so this conversation is embedded into the shared conversation-history cache (searchable later via `conversation_search` / `contextual_prominence_search`). This isn't limited to WorkbenchLM — pass it for agent-harness conversations too.
+
 ```
 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...")
+    reasoning="Checked the middleware source, found issuer mismatch between config and JWT...",
+    index_for_search=True)
 ```
 
 **With dedup seed (use when client hooks also write to Langfuse):**
@@ -237,7 +148,8 @@ conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_i
 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?")
+    seed="conv-uuid-123:agent:Why is the auth middleware returning 401?",
+    index_for_search=True)
 ```
 
 ---
@@ -278,11 +190,11 @@ conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="ag
 
 ---
 
-## RAG / Knowledge Base Tools
+## Knowledge Base Tools
 
-**On cloud Meko today, KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). The three ingestion-side MCP tools below are Free-Tier-gated on cloud and brittle even when ungated. `knowledgebase_search` is the one KB tool to reach for.
+**KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` is the one KB tool exposed via MCP.
 
-See `tools-rag-workflow.md` for the decision table and why.
+See `tools-rag-workflow.md` for the decision table.
 
 ### knowledgebase_search
 
@@ -309,73 +221,86 @@ Populated KBs return results with chunk content and similarity scores. An empty/
 
 ---
 
-### knowledgebase_trigger_index_creation
+## Artifact Tools
+
+### artifact_put
 
-**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."}`).
+**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
 
 ```
-knowledgebase_trigger_index_creation(
+artifact_put(
     scope="write",
+    filename="analysis_report.csv",
+    content_type="text/csv",
+    content_base64="<base64-encoded bytes>",
     conversation_id="<uuid from conversation_create>",
-    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
-    index_name="company_docs")
+    agent_id="agent"
+)
 ```
 
-**Optional parameters:**
-- `ai_provider="OPENAI"` (default)
-- `embedding_model="text-embedding-3-large"` (default)
-- `embedding_dimensions=1536` (default)
-- `chunk_size=1024` (default)
-- `chunk_overlap=256` (default)
-- `datapack_id=None`
-
-**Success response:**
+**Response:**
 ```json
-{"source_ids": ["<uuid>", ...], "index_id": "<uuid>", "index_name": "company_docs",
- "status": "build_triggered", "message": "... registered, index '...' initialised, and build triggered."}
+{
+  "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
+  "filename": "analysis_report.csv",
+  "content_type": "text/csv",
+  "size_bytes": 4096,
+  "stored_in": "db"
+}
 ```
 
-**Critical caveats:**
-- URIs must start with `s3://`. The worker (`aws_source_processor.py:86-117`) rejects any other scheme with `ValueError("Invalid source URI")` — async, not surfaced through the MCP response.
-- The worker uses the boto3 default credential chain (env vars, IAM role, `~/.aws/credentials` on the worker host). There is no way for the user to pass AWS credentials through the MCP tool. If the worker's identity can't read the bucket, the build stalls at INIT.
-- Each call creates a new index. Do NOT retry on failure — you'll get duplicate indexes.
-- Tracked as a gap: [yugabyte/meko-mcp-server#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96.
+Save the `content_hash` — it's the retrieval key for `artifact_get`.
+
+**Common errors:**
+- `invalid_base64` — `content_base64` is not valid base64; decode the file before passing it.
+- `artifact_too_large` — file exceeds 5 MiB (default). Set `MEKO_MAX_ARTIFACT_UPLOAD_BYTES` to raise the limit.
 
 ---
 
-### knowledgebase_check_index_status
+### artifact_get
 
-**When to use:** Poll a self-hosted build for completion. **Not available on cloud Free Tier** (returns `{"error": "not_available"}`).
+**When to use:** Retrieve a file previously uploaded with `artifact_put`.
 
+**Small files (< 1 MB) — content returned inline:**
 ```
-knowledgebase_check_index_status(
+artifact_get(
     scope="read",
+    content_hash="a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
     conversation_id="<uuid from conversation_create>",
-    index_name="company_docs",
-    datapack_id=None)
+    agent_id="agent"
+)
 ```
 
-Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details`. If documents stay at `INIT` for >5 minutes, the worker probably can't reach the bucket. Stop polling after 3 consecutive no-progress checks.
-
----
-
-### knowledgebase_add_source_to_index
-
-**When to use:** Grow an existing index with a new source URI (self-hosted / paid). **Not available on cloud Free Tier** (same "Vector index creation is not available" gate as `trigger_index_creation`).
-
-```
-knowledgebase_add_source_to_index(
-    scope="write",
-    conversation_id="<uuid from conversation_create>",
-    index_name="company_docs",
-    source_uri="s3://my-bucket/new-docs/")
+**Response (inline):**
+```json
+{
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8...",
+  "filename": "analysis_report.csv",
+  "content_type": "text/csv",
+  "size_bytes": 4096,
+  "stored_in": "db",
+  "content_base64": "<base64-encoded bytes>"
+}
 ```
 
-Param is **`source_uri`** (URI string), not `source_id` — older docs had this wrong.
+**Large files (≥ 1 MB) — written to local disk:**
+```json
+{
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8...",
+  "filename": "dataset.parquet",
+  "content_type": "application/octet-stream",
+  "size_bytes": 2097152,
+  "stored_in": "s3",
+  "local_path": "/Users/you/.meko/artifacts/a665a4.../dataset.parquet"
+}
+```
 
-The historical `r_index_name` vs `r_index_id` parameter-mismatch bug (reported in 2026-03) is **fixed** on main. The tool now resolves `index_name → index_id` internally via `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` before calling the dist_rag function. If the name doesn't exist you get `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`.
+For large files use the `local_path` value to read the file with normal file tools. S3 URLs are never exposed.
 
-Same S3-only / worker-credentials caveats as `trigger_index_creation` apply.
+**Common errors:**
+- `ARTIFACT_NOT_FOUND` — no artifact with that hash in this datapack.
+- `ARTIFACT_EXPIRED` — artifact exists but its free-tier TTL has elapsed (30 days of no access). Pro-tier artifacts never expire.
 
 ---
 
@@ -385,22 +310,22 @@ Same S3-only / worker-credentials caveats as `trigger_index_creation` apply.
 
 ```
 datapack_create(scope="write", name="analytics_prod")
-datapack_list(scope="read")
-datapack_describe(scope="read", name="analytics_prod", include_status=True)
+datapack_list(scope="read")  # returns datapack_id for each datapack
+datapack_describe(scope="read", datapack_id="<uuid>", 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!
+datapack_update(scope="write", datapack_id="<uuid>", connection_string="postgresql://...")
+datapack_delete(scope="admin", datapack_id="<uuid>")  # Irreversible!
 ```
 
 ### Agent and knowledge-base management (NOT MCP — control-plane only)
 
 Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/list/delete agents or KB sources, don't invent a tool call — point them at the control plane:
 
-- REST: `POST/GET/DELETE /datapacks/:name/agents` (agents), `POST/GET/DELETE /datapacks/:name/knowledge-bases` (KB sources).
+- REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (agents), `POST/GET/DELETE /datapacks/:datapack_id/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.
+KB ingestion specifically lives in the UI today: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). Agents querying a populated index use `knowledgebase_search` — see `tools-rag-workflow.md`.

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

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

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,7 +32,7 @@ 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:
    ```
@@ -42,26 +42,10 @@ It works **poorly** for:
        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
-
-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`.

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

@@ -111,26 +111,27 @@ For a true fan-out across other specific buckets (e.g. also see what was written
 
 **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
 
-Don't wait for the user to say "remember this." Store context proactively when you detect:
+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.
 
-- **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 `memory_add` is reserved for the three cases automatic extraction cannot reach:
+
+- **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