@yugabytedb/meko-mcp 1.0.8 → 1.2.0

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

@@ -2,7 +2,9 @@
 
 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 examples use `agent_id="claude_code"` for readability, but `agent_id` is a **per-user namespace**, not a per-tool label. At runtime, use the value you discovered via `db_summarize_database` at session start (see the main SKILL.md). Substitute it anywhere you see `claude_code` in the examples. Issue [#10](https://github.com/amiramm/meko-mcp-server/issues/10) tracks the eventual schema fix.
+> **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.
 
 ---
 
@@ -97,14 +99,14 @@ Split into two separate calls.
 
 ## Memory Tools
 
-**Critical:** `agent_id` must not contain hyphens. Use `"claude_code"`, not `"claude-code"`.
+**Critical:** Pass your session's `agent_id` on every memory call (the value from the SessionStart `additionalContext`, e.g. `claude_code:meko-mcp-server`). 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. For genuinely cross-project facts, write with `agent_id="meko_agent"` so any agent can pick them up.
 
 ### 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="claude_code",
+memory_add(scope="write", agent_id="agent",
     text="User Amiram is VP of Product at YugabyteDB. Prefers concise responses.")
 ```
 
@@ -115,7 +117,7 @@ memory_add(scope="write", agent_id="claude_code",
 
 **With user scoping:**
 ```
-memory_add(scope="write", agent_id="claude_code", user_id="amiram",
+memory_add(scope="write", agent_id="agent", user_id="amiram",
     text="Prefers Python for backend, Go for infrastructure.")
 ```
 
@@ -125,7 +127,7 @@ memory_add(scope="write", agent_id="claude_code", user_id="amiram",
 - Large documents (use knowledge base ingestion)
 
 **Common errors:**
-- `syntax error at or near "-"` — Your `agent_id` contains a hyphen. Use underscores.
+- `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.
 
 ---
@@ -135,7 +137,7 @@ memory_add(scope="write", agent_id="claude_code", user_id="amiram",
 **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="claude_code")
+memory_search(scope="read", query="What programming language does the team use?", agent_id="agent")
 ```
 
 **Response:**
@@ -145,7 +147,7 @@ memory_search(scope="read", query="What programming language does the team use?"
 
 **With limit:**
 ```
-memory_search(scope="read", query="user preferences", agent_id="claude_code", limit=5)
+memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
 ```
 
 ---
@@ -155,12 +157,12 @@ memory_search(scope="read", query="user preferences", agent_id="claude_code", li
 **When to use:** List everything stored for an agent. Useful at session start to load context.
 
 ```
-memory_get_all(scope="read", agent_id="claude_code")
+memory_get_all(scope="read", agent_id="agent")
 ```
 
 **With user scoping:**
 ```
-memory_get_all(scope="read", agent_id="claude_code", user_id="amiram")
+memory_get_all(scope="read", agent_id="agent", user_id="amiram")
 ```
 
 ---
@@ -168,7 +170,7 @@ memory_get_all(scope="read", agent_id="claude_code", user_id="amiram")
 ### memory_get_by_id
 
 ```
-memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="claude_code")
+memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
 ```
 
 ---
@@ -178,7 +180,7 @@ memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="claude_code")
 **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="claude_code")
+memory_update(scope="write", memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="agent")
 ```
 
 ---
@@ -186,7 +188,7 @@ memory_update(scope="write", memory_id="mem-uuid-123", text="Updated: Team uses
 ### memory_delete_by_id
 
 ```
-memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="claude_code")
+memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="agent")
 ```
 
 ---
@@ -196,7 +198,7 @@ memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="claude_co
 **Destructive. Requires admin scope.** Deletes all memories for the agent.
 
 ```
-memory_delete_all(scope="admin", agent_id="claude_code")
+memory_delete_all(scope="admin", agent_id="agent")
 ```
 
 ---
@@ -208,7 +210,7 @@ memory_delete_all(scope="admin", agent_id="claude_code")
 **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="claude_code", user_id="amiram",
+conversation_create(scope="write", agent_id="agent", user_id="amiram",
     title="Debugging the auth middleware")
 ```
 
@@ -224,7 +226,7 @@ conversation_create(scope="write", agent_id="claude_code", user_id="amiram",
 **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="claude_code",
+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...")
@@ -232,10 +234,10 @@ conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_i
 
 **With dedup seed (use when client hooks also write to Langfuse):**
 ```
-conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="claude_code",
+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:claude_code:Why is the auth middleware returning 401?")
+    seed="conv-uuid-123:agent:Why is the auth middleware returning 401?")
 ```
 
 ---
@@ -243,7 +245,7 @@ conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_i
 ### conversation_get
 
 ```
-conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="claude_code",
+conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="agent",
     include_messages=True, limit=50)
 ```
 
@@ -252,7 +254,7 @@ conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="claude
 ### conversation_list
 
 ```
-conversation_list(scope="read", agent_id="claude_code", limit=20)
+conversation_list(scope="read", agent_id="agent", limit=20)
 ```
 
 ---
@@ -260,48 +262,65 @@ conversation_list(scope="read", agent_id="claude_code", limit=20)
 ### conversation_update
 
 ```
-conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="claude_code",
+conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
     title="Resolved: Auth middleware issuer mismatch")
 ```
 
 ---
 
-### conversation_delete_message
+### conversation_delete
+
+**Destructive. Requires admin scope.**
 
 ```
-conversation_delete_message(scope="write", conversation_id="conv-uuid-123",
-    agent_id="claude_code", trace_id="trace-uuid-456")
+conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="agent")
 ```
 
 ---
 
-### conversation_delete
+## RAG / Knowledge Base Tools
 
-**Destructive. Requires admin scope.**
+**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.
 
 ```
-conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="claude_code")
+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.
 
-## RAG / Knowledge Base Tools
+**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:** Create a new vector index from source URIs. This is the only way to start a RAG pipeline.
+**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",
+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")
 ```
 
-**Response:**
-```json
-{"source_ids": ["src-uuid-1", "src-uuid-2"], "index_name": "company_docs", "status": "build_triggered"}
-```
-
 **Optional parameters:**
 - `ai_provider="OPENAI"` (default)
 - `embedding_model="text-embedding-3-large"` (default)
@@ -310,31 +329,54 @@ knowledgebase_trigger_index_creation(scope="write",
 - `chunk_overlap=256` (default)
 - `datapack_id=None`
 
-**Warning:** Each call creates a new index. Do NOT retry on failure — you'll get duplicate indexes (e.g., `docs_v1`, `docs_v2`, `docs_v3`).
+**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 for build completion after triggering creation.
+**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", index_name="company_docs")
+knowledgebase_check_index_status(
+    scope="read",
+    conversation_id="<uuid from conversation_create>",
+    index_name="company_docs",
+    datapack_id=None)
 ```
 
-**Polling strategy:** Check every 1-2 minutes. If `pipeline_details` is empty or documents remain at `INIT` for more than 5 minutes, the pipeline is likely stuck. Stop polling after 3 consecutive no-progress checks — see `tools-troubleshooting.md`.
+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
 
-**Known bug:** This tool has a parameter mismatch (`r_index_name` vs `r_index_id`) and may fail. Prefer `knowledgebase_trigger_index_creation` with all sources at once instead.
+**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", index_name="company_docs",
-    source_id="src-uuid-new")
+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
@@ -354,20 +396,11 @@ datapack_update(scope="write", name="analytics_prod", connection_string="postgre
 datapack_delete(scope="admin", name="analytics_prod")  # Irreversible!
 ```
 
-### Agent management within datapacks
+### Agent and knowledge-base management (NOT MCP — control-plane only)
 
-```
-datapack_create_agent(scope="write", datapack_name="analytics_prod", agent_name="analytics_bot")
-datapack_list_agents(scope="read", datapack_name="analytics_prod")
-datapack_delete_agent(scope="admin", datapack_name="analytics_prod", agent_name="analytics_bot")
-```
+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:
 
-### Knowledge base source management within datapacks
-
-```
-datapack_add_knowledge_base(scope="write", datapack_name="analytics_prod", url="s3://data/reports/")
-datapack_list_knowledge_bases(scope="read", datapack_name="analytics_prod")
-datapack_delete_knowledge_base(scope="admin", datapack_name="analytics_prod", url="s3://data/reports/")
-```
+- 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.
 
-**Note:** `datapack_delete_knowledge_base` removes the source registration from the Meko API. It does NOT delete the actual vector index, source records, or vector data from the database.
+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/references/tools-datapack-workflow.md

@@ -32,23 +32,31 @@ All **Database**, **RAG**, and **Memory** tools accept `datapack_id`.
 
 ## Datapack lifecycle
 
-### Creation and setup
+### Creation and setup (MCP)
 
 ```
 datapack_create(scope="write", name="sales_analytics")
-datapack_create_agent(scope="write", datapack_name="sales_analytics", agent_name="sales_agent")
-datapack_add_knowledge_base(scope="write", datapack_name="sales_analytics", url="s3://company-docs/sales/")
 db_run_write_query(scope="write", query="CREATE TABLE leads (...)", datapack_id="dp-uuid-from-step-1")
 ```
 
+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.
+
+For RAG indexes inside the datapack's database, use the MCP-exposed RAG tools:
+
+```
+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")
+```
+
 ### Teardown (requires admin scope)
 
-Delete child resources before the datapack:
+Delete child resources first (agents and KB sources via the control plane), then the datapack:
 
 ```
-datapack_delete_knowledge_base(scope="admin", datapack_name="sales_analytics", url="s3://company-docs/sales/")
-datapack_delete_agent(scope="admin", datapack_name="sales_analytics", agent_name="sales_agent")
-datapack_delete(scope="admin", name="sales_analytics")
+# 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
 ```
 
 ## Common mistake: mixing default and datapack databases

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

@@ -10,7 +10,7 @@ There are no MCP tools to:
 - Clear stuck work queue entries
 - Reset a failed pipeline
 
-The `datapack_delete_knowledge_base` tool only removes the KB source **registration** from the Meko API. It does NOT touch the actual `dist_rag` index, source records, or vector data in the database.
+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.
 
@@ -18,7 +18,7 @@ The `datapack_delete_knowledge_base` tool only removes the KB source **registrat
 
 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, use `db_run_read_only_query` with `dist_rag` SQL functions directly. The specific query syntax depends on the `dist_rag` extension API.
+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
 
@@ -32,13 +32,19 @@ It works **poorly** for:
 - Data dictionaries — only partial information extracted
 - Structured schemas — relationships between fields lost
 
-**Use instead:** `db_run_write_query` to CREATE TABLE and INSERT the data as proper database rows. Then query it with `db_run_read_only_query`.
+**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:
 
-If you must store a schema overview in memory, write a single narrative summary:
-```
-memory_add(scope="write", agent_id="claude_code",
-    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)")
-```
+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
 
@@ -52,7 +58,9 @@ If `db_run_read_only_query` returns "permission denied", this is a server-side c
 
 **`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.
 
-**`knowledgebase_add_source_to_index`** — SQL parameter mismatch: tool passes `r_index_name` (string) but the DB function expects `r_index_id` (UUID). Workaround: use `knowledgebase_trigger_index_creation` with all sources at once.
+**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
 

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

@@ -65,14 +65,57 @@ All three fields — `input`, `output`, and `reasoning` — must contain the **e
 
 The purpose of conversation storage is to create a faithful, replayable record. A rephrased summary loses the original wording, tone, and detail — making the stored conversation useless for review, debugging, or audit.
 
-## Memory Limitations for Structured Data
+## Personal memory vs. team-shared knowledge — the three read paths
+
+Agents on Cloud Meko have three distinct read surfaces. Pick the right one for the question.
+
+| Read path | What it returns | How to call |
+|---|---|---|
+| Your own project memories | Memories you wrote under this `agent_id`, filtered by `(datapack_id, user_id, agent_id)` | `memory_search(agent_id="<your agent_id>", query="...", ...)` |
+| Cross-project common bucket | Memories any agent (including this one) wrote with `agent_id="meko_agent"` — the empty-default bucket for genuinely cross-project facts | `memory_search(agent_id="meko_agent", query="...", ...)` |
+| Team's shared knowledge | Promoted memories + uploaded documents, visible to every member of the datapack | `knowledgebase_search(agent_id="<anything>", datapack_id="<datapack UUID>", query="...")` — `agent_id` is ignored |
+
+For a true fan-out across multiple specific agent_ids (e.g. also see what was written from `claude_code:other-repo` or `cursor:foo`), call `memory_search` once per agent_id — there's no single-call shortcut. Empty string is rewritten to `meko_agent` server-side; it does not drop the filter.
+
+### How content gets into each surface
+
+- **Personal memories** — written by `memory_add`. Scoped per-user and per-agent from the moment of write. Only the writer sees them via MCP reads.
+- **Team-shared Shared Knowledge** — arrives two ways:
+  1. The **user** (never the agent) promotes a personal memory to Knowledge via the Cloud UI's Learnings tab. That copies the row into the shared `knowledge_base` table with the `user_id` stripped, making it team-wide. Originating `agent_id` is preserved in metadata for provenance.
+  2. The user uploads a file via Datapack → Actions → **Add Knowledge** in the Cloud UI. PDF/TXT/MD/JSON/MP4 up to 5MB each.
+
+  Both show up in `knowledgebase_search`, tagged `metadata_filters.source: "memory"` vs other values so the agent can distinguish provenance in responses.
+
+**No MCP tool promotes to Shared Knowledge.** The agent can flag memories it thinks are worth promoting and suggest the user do it from the UI — but the action is user-initiated.
+
+### When the user asks "what do you know about X?"
+
+A full sweep is three calls (budget for it — each is 2-6 seconds):
+
+```
+memory_search(agent_id="<your-agent-id>", query="X", conversation_id=..., ...)
+memory_search(agent_id="meko_agent", query="X", conversation_id=..., ...)  # cross-project common bucket
+knowledgebase_search(agent_id="<anything>", datapack_id="<uuid>", query="X", conversation_id=..., ...)
+```
+
+When you answer, be explicit about scope so the user knows why something is or isn't there:
+
+- "I found this in your own project memories…"
+- "I found this in your common cross-project bucket (something you or another agent wrote under `meko_agent`)…"
+- "I found this in your team's Shared Knowledge — someone (you or a teammate) promoted it earlier…"
+- "I couldn't find anything in your personal memories. You might want to check the Cloud UI's Memory Summary tab for a cross-agent view."
+
+For a true fan-out across other specific buckets (e.g. also see what was written from `claude_code:other-repo` or `cursor:foo`), call `memory_search` once per known agent_id — empty string just resolves to `meko_agent`, not a fan-out.
+
+## Memory limitations for structured data
 
 **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.
 
-For tabular data, prefer:
-1. **Create a table** via `db_run_write_query` and insert the data as rows — preserves all structure
-2. **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
-3. **Never ingest CSV row-by-row** into memory — each row becomes a fragmented fact with lost context
+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:
+
+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
 
@@ -126,3 +169,49 @@ Automatic capture handles the raw exchange. You should still manually use `conve
 ### Watermark coordination
 
 A shared watermark file at `~/.claude/meko-capture/<session-id>.watermark.json` tracks what has been saved. Both hooks and the agent's periodic checkpoint use this to avoid reprocessing already-captured exchanges.
+
+## Observability: conversation_id IS the Langfuse trace ID
+
+This is the feature agents tend to miss. Verified live 2026-05-07 in the Meko UI's Observe hub.
+
+- `conversation_create` returns a `conversation_id` (e.g. `d71fc8b61a7f45d585eea9a6436e0c3f`).
+- That ID is also the **Langfuse trace_id** for the conversation. Not a separate trace — literally the same identifier.
+- Every subsequent MCP tool call made while passing that `conversation_id` becomes a **span under that trace**, named after the tool: `Memory Add (Meko MCP)`, `Memory Search (Meko MCP)`, `Knowledgebase Search (Meko MCP)`, `Conversation Add Message (Meko MCP)`, etc.
+- Child spans reveal internals. Observed structure:
+  - `memory_add`: `Memory Add (Meko MCP)` → `Create a new memory in Mem0` → `Bulk Payload Update (yugabytedb / vector)` → `Execute Query (yugabytedb / vector)`
+  - `memory_search`: `Memory Search (Meko MCP)` → `Search for memories based on a query in Mem0` (Retriever)
+  - `conversation_add_message`: `Conversation Add Message (Meko MCP)` → `Conversation Message Added` span → `Reasoning` generation (the `reasoning` field is stored as a Langfuse *generation*-typed span, not a plain text field)
+  - `knowledgebase_search`: `Knowledgebase Search (Meko MCP)` → multiple `Execute Query (yugabytedb)` child spans
+- Trace tags include `agent:<agent_id>` and the Meko org UUID. Both are searchable/filterable in Langfuse.
+- Each datapack has its own Langfuse project — traces for a tool call land in the project for whichever `datapack_id` was on the call (or the default datapack if omitted).
+
+### Finding a trace in the UI
+
+Two navigation paths, both verified in the Meko UI:
+
+1. **Datapack → Conversations tab** — every row has an **Open in Observe** button that deep-links to the trace with `session=<conversation_id>` pre-filled. Fastest when you know which conversation to inspect.
+2. **Observe hub** — browse all traces across a datapack. URL shape: `/observe-hub?project=<langfuse_project_id>&session=<conversation_id>`.
+
+The Conversations-tab row preview shows the first user turn verbatim, plus the agent_id tag, message count, and started-at timestamp. If you want a conversation to be recognizable in the UI, call `conversation_add_message` with a clean first-turn `input` early in the session.
+
+### Observed latencies on prod (2026-05-07)
+
+From real traces, not the docstring happy path:
+
+| Tool | Latency per call |
+|---|---|
+| `memory_add` | 12-21 seconds (calls OpenAI for extraction, then writes to vector + graph) |
+| `memory_search` | 1.8-5.9 seconds |
+| `knowledgebase_search` | 0.6 seconds (empty index; will grow with index size) |
+| `conversation_add_message` | 0.11 seconds (fire-and-forget; queued to Langfuse) |
+
+`memory_add` is the expensive one. If you're capturing a long conversation, batch through `conversation_add_message` (cheap, queued) and let the server-side Mem0 extractor handle the heavy lifting on its own schedule, rather than firing `memory_add(messages=...)` per turn.
+
+### Proactive diagnostic pattern
+
+If a user reports "my memory_add didn't seem to save", open the Observe hub for their datapack, filter on their `conversation_id`, and look at the span tree. You will see either:
+
+- A `Memory Add (Meko MCP)` span with `Create a new memory in Mem0` child → the call reached Mem0. The fact extractor may have returned `"results": []` (common on short or non-fact-shaped text; not a bug, but lossy).
+- No span at all → the call never reached the server. Likely a transport / auth / `conversation_id` mismatch issue.
+
+The mem0 extractor is lossy — it extracts atomic facts and graph triples, and may drop prose that doesn't look fact-shaped to it. Observed 2026-05-07: 2 of 5 `memory_add` calls returned `"results": []` and only the graph side landed. When preserving authoritative text matters, store it via `conversation_add_message` (verbatim in `input`/`output`/`reasoning`) — the conversation path preserves text without LLM re-extraction.