@yugabytedb/meko-mcp 1.2.0 → 2.0.0

package/assets/skills/meko-mcp-tools-desktop/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.** 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.
 
 ---
 
@@ -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 — those are captured when you post the turn with `conversation_add_message` and the server extracts them. Reserve `memory_add` for the three cases per-turn capture can't reach: (1) the user explicitly says "remember this"; (2) a durable fact 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="claude_desktop",
+    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,82 @@ 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="claude_desktop"
+)
 ```
 
-**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.
+- `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="claude_desktop"
+)
 ```
 
-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",
+  "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",
+  "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 `local_path` to read the file. 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` — free-tier TTL has elapsed (30 days of no access).
 
 ---
 
@@ -385,22 +306,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-desktop/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,25 +42,19 @@ 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
+## Activation is model-judged on Desktop (no hooks)
 
-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
+Claude Desktop has no lifecycle hooks, so this skill activates only when the model judges it relevant from the skill's `description`. Reliable triggers: recall questions ("what do you know about me"), explicit save requests ("remember this"), and mentions of memory/Meko/datapacks. **Best-effort** triggers: task-shaped prompts where a durable fact appears only in passing ("I'm evaluating pnpm; I already use Turborepo") — the skill may not fire and the turn goes uncaptured. Also, when the model resolves a tool directly via tool search it may call `memory_add`/`memory_search` without reading this skill at all.
 
-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.
+The skill description is tuned to its 1024-char ceiling; broadening it further does not close the task-shaped-prompt gap (empirically confirmed in Phase-9 testing). Mitigations, in order of leverage:
 
-## 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.)
+1. **Personal-preferences snippet** (always-on) — paste the snippet from the Desktop setup README's "Make Desktop proactive" step into Claude's profile preferences; it is injected into every conversation regardless of prompt shape. This is the only true fix for task-shaped misses.
+2. **Server-side guidance** — the `agent_id` tool docstrings and the server's connect-time instructions name `claude_desktop` as this client's bucket, so even a skill-less tool-search call avoids the wrong-bucket (`claude_code`) write.
+3. Nothing is lost when the *user* explicitly recalls or saves — only passive capture of in-passing facts is best-effort.
 
 ## No conversation search
 

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

@@ -111,41 +111,38 @@ For a true fan-out across other clients' 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: capture the turn, don't proactively memory_add
 
-Don't wait for the user to say "remember this." Store context proactively when you detect:
+Do **not** proactively `memory_add` facts the user states. On Claude Desktop, post each substantive turn with `conversation_add_message` and the server extracts durable memories from it automatically — personal info, team conventions, domain knowledge, and corrections the user states are all captured that way. A separate `memory_add` just duplicates what extraction produces.
 
-- **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 per-turn capture can't reach:
+
+- **Explicit request** → the user says "remember this" / "save this."
+- **Output-only / tool-derived fact** → a durable fact only in your output or a tool result, never in a user turn (extraction reads the user side of the turn).
+- **Overwriting correction** → a prior fact was negated and the stale memory must not survive. Extraction is additive, so `memory_search` for the old memory and `memory_update` / `memory_delete_by_id`.
 
 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).
+Posting the turn does both jobs: it preserves the full conversation (structure) and feeds the extractor (searchable memory). Add an explicit `memory_add` only for the three cases above.
 
 ## Key Retrieval Difference
 
 - `memory_search`: **semantic similarity** across all memories via pgvector. Returns relevant facts regardless of when stored.
 - `conversation_get`: **ordered list of message turns** for a specific conversation. No semantic search. Requires `conversation_id`.
 
-## Automatic Conversation Capture
-
-The Meko plugin captures conversations automatically via three mechanisms:
+## Conversation Capture (Desktop: agent-driven)
 
-1. **Periodic checkpoint (~10 min)** — Agent-driven via CronCreate, uses `conversation_add_message` MCP tool directly
-2. **PreCompact hook** — Shell script that fires before Claude Code's auto-compaction, captures via MCP JSON-RPC
-3. **SessionEnd hook** — Shell script that fires at session termination, captures final exchanges
+Claude Desktop has **no capture hooks** — you are the capture mechanism. Post each substantive turn with `conversation_add_message`, and the server extracts memories from the posted turns automatically (extraction runs inside `conversation_add_message`). Coding clients like Claude Code get the same effect from SessionStart / PreCompact / SessionEnd hooks; on Desktop it's your responsibility per turn.
 
-### What gets captured
+### What to capture
 
 The full transcript including:
 - **User prompts** — verbatim text (the `input` field)

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

@@ -1,62 +1,40 @@
 # 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`
+**22 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
 1. `memory_search(scope="read", query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-2. `datapack_list(scope="read")` — Confirms Meko API connectivity
-3. `db_summarize_database(scope="read")` — *Optional, paid-tier only.* On free-tier datapacks this returns `{"error": "not_available"}`. The old "use this for `agent_id` discovery" protocol is retired — use your client's bucket (`claude_desktop` for Claude Desktop) or `meko_agent` for the common bucket.
+2. `datapack_list(scope="read")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
 
 ## Decision tree: which tool do I need?
 
 ```
 User wants to...
-├── Query or explore the database?
-│   ├── See what tables exist? ---------> db_summarize_database (read)
-│   ├── Run a SELECT / read query? -----> db_run_read_only_query (read)
-│   └── INSERT / UPDATE / DELETE? -------> db_run_write_query (write)
-├── Query or build a knowledge base (RAG)?
-│   ├── Search chunks in an existing KB? -> knowledgebase_search (read) — WORKS on cloud today
-│   ├── Create a new index from sources? -> knowledgebase_trigger_index_creation (write) — Free-Tier gated, self-hosted only
-│   ├── Add source to existing index? ---> knowledgebase_add_source_to_index (write) — Free-Tier gated
-│   └── Check build progress? -----------> knowledgebase_check_index_status (read) — Free-Tier gated
+├── Search a knowledge base? ---------------> knowledgebase_search (read)
+├── Add documents to a knowledge base? -----> point user at Meko UI: Datapack → Actions → Add Knowledge
+│                                              (no MCP tool — Cloud uses UI ingestion only)
 ├── Store or recall information?
 │   ├── Store a fact/preference/entity? -----------> memory_add (write)
 │   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
 │   ├── Search past knowledge? --------------------> memory_search (read)
 │   └── Retrieve a past conversation? -------------> conversation_get (read)
+├── Persist or retrieve a file?
+│   ├── Upload a generated file (report, CSV, PDF)? -> artifact_put (write)
+│   └── Retrieve a previously uploaded file? -------> artifact_get (read)
 └── Manage datapacks?
-    └── CRUD datapack? -> datapack_create/list/describe/update/delete
+    └── CRUD datapack? --------------------> datapack_create/list/describe/update/delete
 ```
 
 Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typically in the Meko control-plane UI — and is not exposed as tools here.
 
-## Database Tools (3)
-
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `db_summarize_database(scope, schema="public", datapack_id=None)` | read | List tables with column schemas and row counts |
-| `db_run_read_only_query(scope, query, datapack_id=None)` | read | Run SELECT, returns JSON. Uses `BEGIN READ ONLY` + `ROLLBACK` |
-| `db_run_write_query(scope, query, datapack_id=None)` | write | Execute INSERT/UPDATE/DELETE/CREATE TABLE. Guardrail-validated. Auto-committed |
-
-## RAG / Knowledge Base Tools (4)
+## Knowledge Base Tools (1)
 
 | Tool | Scope | Purpose |
 |------|-------|---------|
-| `knowledgebase_search(scope, query, agent_id, conversation_id, datapack_id, limit=10)` | read | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). Works on cloud today. |
-| `knowledgebase_trigger_index_creation(scope, conversation_id, source_uris, index_name, ai_provider="OPENAI", embedding_model="text-embedding-3-large", embedding_dimensions=1536, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Register sources + init vector index + trigger build. **S3-only worker + no user creds; Free-Tier gated on cloud.** See `tools-rag-workflow.md`. |
-| `knowledgebase_add_source_to_index(scope, conversation_id, index_name, source_uri, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Add a new source (URI, not id) to an existing index. Free-Tier gated on cloud. |
-| `knowledgebase_check_index_status(scope, conversation_id, index_name, datapack_id=None)` | read | Check build progress via `dist_rag.vector_index_pipeline_details`. Free-Tier gated on cloud. |
+| `knowledgebase_search(scope, query, agent_id, conversation_id, datapack_id, limit=10)` | read | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
 
 ## Memory Tools (8)
 
@@ -69,7 +47,7 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 | `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. |
+| `flush_pending_memory_candidates(scope, agent_id)` | read | **Deprecated.** Superseded by automatic extraction from posted turns — post substantive turns with `conversation_add_message` and the server extracts memories from them. Now returns a `deprecated` payload pointing at `conversation_add_message`; kept one release for backward compatibility. |
 
 ## Conversation Tools (6)
 
@@ -88,9 +66,24 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 |------|-------|---------|
 | `datapack_create(scope, name)` | write | Create new datapack |
 | `datapack_list(scope)` | read | List all datapacks |
-| `datapack_describe(scope, name, include_status=False)` | read | Describe datapack |
-| `datapack_update(scope, name, connection_string)` | write | Update connection string |
-| `datapack_delete(scope, name)` | admin | Delete datapack (irreversible) |
+| `datapack_describe(scope, datapack_id, include_status=False)` | read | Describe datapack by UUID |
+| `datapack_update(scope, datapack_id, connection_string)` | write | Update connection string |
+| `datapack_delete(scope, datapack_id)` | admin | Delete datapack by UUID (irreversible) |
+
+## Artifact Tools (2)
+
+Content-addressed blob store scoped to a datapack. Files < 1 MB go inline in the DB; files ≥ 1 MB go to S3. Identity is SHA-256 — uploading the same bytes twice returns the same `content_hash`. Free-tier artifacts expire after 30 days of inactivity; pro-tier artifacts have no TTL.
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `artifact_put(scope, filename, content_base64, content_type, conversation_id, datapack_id=None, agent_id=None)` | write | Upload a file to the datapack. Returns `{artifact_id, content_hash, filename, size_bytes, stored_in}`. Max 5 MiB (configurable via `MEKO_MAX_ARTIFACT_UPLOAD_BYTES`). |
+| `artifact_get(scope, content_hash, conversation_id, datapack_id=None, agent_id=None)` | read | Retrieve a file by SHA-256 hash. Small files return `content_base64` inline; large files (S3) are written to `~/.meko/artifacts/<hash>/<filename>` and `local_path` is returned. |
+
+## Observability Tools (1)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `track_token_usage(scope, conversation_id, name, input_tokens=0, output_tokens=0, total_tokens=None, model=None, message_id=None, datapack_id=None)` | write | Record an LLM-cost GENERATION observation on the conversation's trace. Primarily called by first-party Meko services (e.g. inference_gateway) that know their LLM's exact token counts. Most end-agents (Cursor, Claude Desktop) don't have those counts at the MCP call layer, so this tool is rarely useful for third-party agents. |
 
 ## Platform capabilities NOT exposed via MCP
 
@@ -98,15 +91,15 @@ Some things the Meko platform can do are not wired into the MCP tool surface tod
 
 | Capability | Where it lives | How to reach it |
 |---|---|---|
-| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:name/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
-| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:name/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
-| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:name/langfuse/project-keys` |
+| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
+| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
+| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:datapack_id/langfuse/project-keys` |
 | Account / billing / tier management | Meko UI only | Not available via MCP or public REST |
 
 The MCP-exposed `datapack_create` / `datapack_list` / `datapack_describe` / `datapack_update` / `datapack_delete` tools above are a deliberate subset — the common CRUD that an agent reasonably needs mid-conversation. Anything involving agent or KB lifecycle is control-plane territory.
 
-For knowledge-base content on cloud today, the canonical path is **UI upload**: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` queries the resulting index from MCP. The MCP ingestion tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) exist but are Free-Tier gated and rely on an S3-only worker with no user-supplied credentials — see `tools-rag-workflow.md` for the full picture. Tracked upstream as [#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96.
+For knowledge-base content on Cloud, the canonical path is **UI upload**: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` queries the resulting index from MCP.
 
 ## Common Parameter Patterns
 
-Every tool accepts `scope` as the first parameter. All DB, RAG, and memory tools accept optional `datapack_id` to target a specific datapack's database. Memory and conversation tools require `agent_id` for namespace isolation (see `tools-agent-id-conventions.md`).
+Every tool accepts `scope` as the first parameter. Memory and KB tools accept optional `datapack_id` to target a specific datapack. Memory and conversation tools require `agent_id` for namespace isolation (see `tools-agent-id-conventions.md`).