@yugabytedb/meko-mcp 2.0.0 → 2.1.0

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

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

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

@@ -0,0 +1,50 @@
+# Authoring `reasoning` and `plan` on `conversation_add_message`
+
+`conversation_add_message` accepts two optional fields — `reasoning` and `plan` — that capture *why* the assistant replied the way it did and *what* concrete steps it took. They are stored side-by-side on the per-turn `Reasoning` observation in Langfuse, independently, so consumers can read or render either one on its own.
+
+Provide them on the large majority of substantive turns. Skip both only for genuinely trivial acknowledgements (a one-word reply, a pure restatement). Do not fabricate deliberation — but in practice, almost every substantive reply has at least a one-line *why* and a one-step plan.
+
+## `reasoning`
+
+A short paragraph (1–3 sentences) of the **why**. Plain English. Explain which trade-off you weighed, which user fact tipped the decision, why this answer beat the alternatives. Inline markdown (`**bold**`, `*italics*`, `` `code` ``) is fine.
+
+Do NOT include a `**Plan:**` heading inside `reasoning` — put steps in the `plan` field instead.
+
+## `plan`
+
+A list of 2 to 4 concrete actions taken for this turn. Each entry is a single imperative sentence, like a checklist item. Pass a list of strings.
+
+Do NOT pre-number entries. Do NOT include a `**Plan:**` heading inside the strings — `plan` is stored as a structured array on the observation's `metadata.plan`, independent of `reasoning`.
+
+## Two examples
+
+### Example A — database recommendation
+
+```
+reasoning:
+    "The user cares about low latency and predictable cost.
+     Option A wins on latency but costs more per month; option
+     B is cheaper but adds 30 ms p99. Latency was their top
+     priority, so I picked Option A."
+
+plan: [
+    "Recommend Option A and call out the latency advantage.",
+    "Show the monthly cost delta in clear numbers.",
+    "Flag the cost difference so the user can decide if it fits."
+]
+```
+
+### Example B — book pick for a long flight
+
+```
+reasoning:
+    "The user wants a non-fiction book for a six-hour flight
+     and does not enjoy business memoirs. *Sapiens* fits the
+     time slot, is non-fiction, and is not a memoir."
+
+plan: [
+    "Recommend *Sapiens* as the main pick.",
+    "Offer *Bad Blood* as a non-memoir backup.",
+    "Skip founder memoirs per the user's stated dislike."
+]
+```

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

@@ -1,21 +1,21 @@
 # Tool Cookbook — Complete Usage Examples
 
-Every tool example below shows the correct parameters, expected response, and common errors. Use `scope="read"` for reads and `scope="write"` for writes — never `"all"` or any other value.
+Every tool example below shows the correct parameters, expected response, and common errors.
 
-> **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 `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 value: for Claude Desktop, use `claude_desktop`; for Claude Code/Cursor, use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Write genuinely cross-project facts with `agent_id="meko_agent"`. On memory reads, `agent_id` attributes the trace but does not filter results. See `tools-agent-id-conventions.md`.
 
 ---
 
 ## Memory Tools
 
-**Critical:** Pass your session's `agent_id` on every memory call. For Claude Desktop that's `claude_desktop` for client-personal context, or `meko_agent` for genuinely cross-project facts (user identity, global preferences). Personal writes are scoped strictly by `agent_id` — other agents won't see your writes on personal reads unless they pass the same exact value.
+**Critical:** Pass your session's `agent_id` on every memory call. For Claude Desktop that's `claude_desktop` for normal attribution, or `meko_agent` when writing genuinely cross-project facts. Writes retain that attribution, while personal memory reads span all of this user's agents.
 
 ### memory_add
 
 **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="claude_desktop",
+memory_add(agent_id="claude_desktop",
     text="Remember: deploy scripts must be run from the repo root, never a subdir.")
 ```
 
@@ -26,7 +26,7 @@ memory_add(scope="write", agent_id="claude_desktop",
 
 **With user scoping:**
 ```
-memory_add(scope="write", agent_id="agent", user_id="amiram",
+memory_add(agent_id="agent", user_id="amiram",
     text="Prefers Python for backend, Go for infrastructure.")
 ```
 
@@ -44,8 +44,10 @@ memory_add(scope="write", agent_id="agent", user_id="amiram",
 
 **When to use:** Find relevant memories by meaning. Always try this before asking the user to repeat information.
 
+**Cross-conversation discovery.** `memory_search` returns hits across every stored conversation for the `(datapack_id, user_id)` pair, across all agents (the tool intentionally passes `meko_agent_id=None` to mem0, so the `agent_id` argument scopes the trace but does not filter results). When a hit references an interesting conversation, follow up with `conversation_list` to browse the associated threads and `conversation_get` to read a specific one — the memory hit's `meko_conversation_id` field is the id to fetch. Pass `run_id` on the search itself to narrow to a single conversation up front.
+
 ```
-memory_search(scope="read", query="What programming language does the team use?", agent_id="agent")
+memory_search(query="What programming language does the team use?", agent_id="agent")
 ```
 
 **Response:**
@@ -55,7 +57,7 @@ memory_search(scope="read", query="What programming language does the team use?"
 
 **With limit:**
 ```
-memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
+memory_search(query="user preferences", agent_id="agent", limit=5)
 ```
 
 ---
@@ -65,12 +67,12 @@ memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
 **When to use:** List everything stored for an agent. Useful at session start to load context.
 
 ```
-memory_get_all(scope="read", agent_id="agent")
+memory_get_all(agent_id="agent")
 ```
 
 **With user scoping:**
 ```
-memory_get_all(scope="read", agent_id="agent", user_id="amiram")
+memory_get_all(agent_id="agent", user_id="amiram")
 ```
 
 ---
@@ -78,7 +80,7 @@ memory_get_all(scope="read", agent_id="agent", user_id="amiram")
 ### memory_get_by_id
 
 ```
-memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
+memory_get_by_id(memory_id="mem-uuid-123", agent_id="agent")
 ```
 
 ---
@@ -88,7 +90,7 @@ memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
 **When to use:** Overwrite a specific memory's text. Requires the memory UUID.
 
 ```
-memory_update(scope="write", memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="agent")
+memory_update(memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="agent")
 ```
 
 ---
@@ -96,19 +98,39 @@ 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="agent")
+memory_delete_by_id(memory_id="mem-uuid-123", agent_id="agent")
 ```
 
 ---
 
 ### memory_delete_all
 
-**Destructive. Requires admin scope.** Deletes all memories for the agent.
+**Destructive.** Deletes all memories for the agent. For removing a single memory, prefer `memory_delete_by_id` — `memory_delete_all` wipes the entire agent scope in the datapack.
+
+```
+memory_delete_all(agent_id="agent")
+```
+
+---
+
+### memory_promote
+
+**When to use:** The user asks to share or promote specific memories to the team's knowledge base — the MCP counterpart of the Cloud UI's "Promote to Knowledge" flow. One-way: promoted memories become team-visible via `knowledgebase_search` and are evicted from the private memory store. Requires the caller to be a datapack **owner or maintainer**; viewers and contributors get a 403 permission error.
 
 ```
-memory_delete_all(scope="admin", agent_id="agent")
+memory_promote(memory_ids=["mem-uuid-123", "mem-uuid-456"],
+    agent_id="claude_desktop", conversation_id="<uuid from conversation_create>")
 ```
 
+**Response:**
+```json
+{"inserted_ids": ["mem-uuid-123"], "updated_ids": ["mem-uuid-456"], "not_found_ids": []}
+```
+
+Get exact UUIDs from the `id` field of `memory_search` / `memory_get_all` results; never use graph relation IDs. Before the call, show the user each exact memory and UUID, explain that promotion is team-visible, one-way, and evicts the private records, then obtain explicit confirmation for those candidates. Pass the active `conversation_id` and intended `agent_id` / `datapack_id`; on legacy schemas that expose `scope`, use `write`, not `admin`.
+
+On 403, authentication, or permission failure, report the error and stop — do not escalate scope, change datapacks, or alter identity. After a successful call, `knowledgebase_search` may verify shared visibility, but it is not a rollback mechanism.
+
 ---
 
 ## Conversation Tools
@@ -118,7 +140,7 @@ memory_delete_all(scope="admin", agent_id="agent")
 **When to use:** Start storing a multi-turn exchange. Do this when the session contains valuable dialog worth preserving.
 
 ```
-conversation_create(scope="write", agent_id="agent", user_id="amiram",
+conversation_create(agent_id="agent", user_id="amiram",
     title="Debugging the auth middleware")
 ```
 
@@ -133,23 +155,21 @@ 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.
+Leave `index_for_search` at its default (`False`). Conversation-cache embedding is currently a WorkbenchLM-only feature — the inference gateway opts in on its own turns; agent-harness conversations should not opt in.
 
 ```
-conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_add_message(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...",
-    index_for_search=True)
+    reasoning="Checked the middleware source, found issuer mismatch between config and JWT...")
 ```
 
 **With dedup seed (use when client hooks also write to Langfuse):**
 ```
-conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_add_message(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?",
-    index_for_search=True)
+    seed="conv-uuid-123:agent:Why is the auth middleware returning 401?")
 ```
 
 ---
@@ -157,7 +177,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="agent",
+conversation_get(conversation_id="conv-uuid-123", agent_id="agent",
     include_messages=True, limit=50)
 ```
 
@@ -165,8 +185,12 @@ conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="agent"
 
 ### conversation_list
 
+Target the datapack by `datapack_id` (UUID). It's optional — omit it to use the
+pinned/default datapack, or pass the pinned `datapack_id`. Use `datapack_list`
+to look up the id.
+
 ```
-conversation_list(scope="read", agent_id="agent", limit=20)
+conversation_list(datapack_id="<datapack-uuid>", agent_id="agent", limit=20)
 ```
 
 ---
@@ -174,7 +198,7 @@ conversation_list(scope="read", agent_id="agent", limit=20)
 ### conversation_update
 
 ```
-conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+conversation_update(conversation_id="conv-uuid-123", agent_id="agent",
     title="Resolved: Auth middleware issuer mismatch")
 ```
 
@@ -182,10 +206,10 @@ conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="ag
 
 ### conversation_delete
 
-**Destructive. Requires admin scope.**
+**Destructive.**
 
 ```
-conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="agent")
+conversation_delete(conversation_id="conv-uuid-123", agent_id="agent")
 ```
 
 ---
@@ -202,7 +226,6 @@ See `tools-rag-workflow.md` for the decision table.
 
 ```
 knowledgebase_search(
-    scope="read",
     query="natural-language question",
     agent_id="agent",
     conversation_id="<uuid from conversation_create>",
@@ -229,7 +252,6 @@ Populated KBs return results with chunk content and similarity scores. An empty/
 
 ```
 artifact_put(
-    scope="write",
     filename="analysis_report.csv",
     content_type="text/csv",
     content_base64="<base64-encoded bytes>",
@@ -265,7 +287,6 @@ Save the `content_hash` — it's the retrieval key for `artifact_get`.
 **Small files (< 1 MB) — content returned inline:**
 ```
 artifact_get(
-    scope="read",
     content_hash="a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
     conversation_id="<uuid from conversation_create>",
     agent_id="claude_desktop"
@@ -305,16 +326,20 @@ For large files use `local_path` to read the file. S3 URLs are never exposed.
 ### datapack_create / datapack_list / datapack_describe
 
 ```
-datapack_create(scope="write", name="analytics_prod")
-datapack_list(scope="read")  # returns datapack_id for each datapack
-datapack_describe(scope="read", datapack_id="<uuid>", include_status=True)
+datapack_create(name="analytics_prod")
+datapack_list()  # returns datapack_id for each datapack
+datapack_describe(datapack_id="<uuid>", include_status=True)
 ```
 
 ### datapack_update / datapack_delete
 
+`datapack_update` renames or edits a datapack's description. At least one of `name` / `description` must be provided (or the tool returns `nothing_to_update`). The server refuses to rename `meko_default_datapack` — the error is `"meko_default_datapack cannot be renamed"`. Passing `description=""` does NOT clear an existing description.
+
 ```
-datapack_update(scope="write", datapack_id="<uuid>", connection_string="postgresql://...")
-datapack_delete(scope="admin", datapack_id="<uuid>")  # Irreversible!
+datapack_update(datapack_id="<uuid>", name="renamed-datapack")
+datapack_update(datapack_id="<uuid>", description="new description")
+datapack_update(datapack_id="<uuid>", name="x", description="y")
+datapack_delete(datapack_id="<uuid>")  # Irreversible!
 ```
 
 ### Agent and knowledge-base management (NOT MCP — control-plane only)
@@ -322,6 +347,6 @@ datapack_delete(scope="admin", datapack_id="<uuid>")  # Irreversible!
 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/: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.
+- Or the Meko Cloud UI at `cloud.mekodata.ai` → Datapacks → agents / knowledge-bases.
 
 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

@@ -36,7 +36,7 @@ It works **poorly** for:
 
 1. **Write a single narrative summary** as a memory — one call, not row-by-row:
    ```
-   memory_add(scope="write",
+   memory_add(
        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)")
@@ -56,8 +56,8 @@ The skill description is tuned to its 1024-char ceiling; broadening it further d
 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
+## No semantic search over conversation content
 
-`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`.
+Semantic (meaning-based) search across stored conversation content is not part of the public tool surface today. To find a past conversation, browse with `conversation_list` (by datapack) and inspect candidates with `conversation_get`.
 
-For finding past knowledge by meaning, use `memory_search` instead — which is why storing key facts via `memory_add` alongside conversations is important.
+For finding past knowledge by meaning, `memory_search` remains the most reliable path — which is why storing key facts via `memory_add` alongside conversations is important.

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

@@ -11,10 +11,10 @@
 Memory is backed by pgvector (semantic search) and Apache AGE (entity-relationship graph). It retrieves relevant facts by meaning, not by conversation order.
 
 ```
-memory_add(scope="write", agent_id="support_bot",
+memory_add(agent_id="support_bot",
     text="Customer Alice (alice@acme.com) prefers email, has Pro plan.", user_id="alice_123")
 
-memory_search(scope="read", query="What plan does Alice have?", agent_id="support_bot")
+memory_search(query="What plan does Alice have?", agent_id="support_bot")
 ```
 
 ## Use `conversation_create` + `conversation_add_message` when storing:
@@ -26,10 +26,10 @@ memory_search(scope="read", query="What plan does Alice have?", agent_id="suppor
 Conversations are backed by Langfuse sessions and traces. They preserve full structure: who said what, in what order, with what reasoning.
 
 ```
-conversation_create(scope="write", agent_id="support_bot", user_id="alice_123", title="Pricing discussion")
+conversation_create(agent_id="support_bot", user_id="alice_123", title="Pricing discussion")
 -- Returns: {"id": "conv-uuid-here"}
 
-conversation_add_message(scope="write", conversation_id="conv-uuid-here", agent_id="support_bot",
+conversation_add_message(conversation_id="conv-uuid-here", agent_id="support_bot",
     input="What are your pricing tiers?",
     output="We offer Starter ($10/mo), Pro ($50/mo), and Enterprise (custom).",
     reasoning="Retrieved pricing page data. No special discounts apply.")
@@ -65,47 +65,44 @@ 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.
 
-## Personal memory vs. team-shared knowledge — the three read paths
+## Personal memory vs. team-shared knowledge — the two read paths
 
-Agents on Cloud Meko have three distinct read surfaces. Pick the right one for the question.
+Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the question.
 
 | Read path | What it returns | How to call |
 |---|---|---|
-| Your own desktop memories | Memories you wrote under this `agent_id`, filtered by `(datapack_id, user_id, agent_id)` | `memory_search(agent_id="claude_desktop", 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="...", ...)` |
+| Your personal memories | Everything you and any of your agents wrote for this user, filtered by `(datapack_id, user_id)` and not by `agent_id` | `memory_search(agent_id="claude_desktop", query="...", ...)` — `agent_id` attributes the trace |
 | 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 other clients' buckets (e.g. also see what was written from `claude_code:some-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.
+One `memory_search` already spans this user's memories across all agents; no per-agent fan-out is needed.
 
 ### 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.
+- **Personal memories** — written by `memory_add`. The `agent_id` records the writer but does not restrict reads; memories are scoped per-user, so any of that user's agents can read them and no other user can.
 - **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.
+  1. An agent calls `memory_promote` for exact, user-confirmed memory UUIDs, or the user promotes them from the Cloud UI's Learnings tab. Promotion moves the memories and graph context into shared knowledge, strips `user_id`, preserves originating `agent_id` as provenance, and evicts the private mem0 records.
   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.
+`memory_promote` is a one-way, destructive MCP path. Before calling it, retrieve exact UUIDs with `memory_search` or `memory_get_all`, show the exact candidates, explain team visibility and private-record eviction, and obtain explicit user confirmation. Only owners and maintainers may promote; report 403/auth failures without escalating scope or switching datapacks. The Cloud UI remains an alternative.
 
 ### When the user asks "what do you know about X?"
 
-A full sweep is three calls (budget for it — each is 2-6 seconds):
+A full sweep is two calls (budget for it — each is 2-6 seconds):
 
 ```
 memory_search(agent_id="claude_desktop", 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=..., ...)
 ```
 
+The single `memory_search` includes everything this user and their other agents wrote in the datapack.
+
 When you answer, be explicit about scope so the user knows why something is or isn't there:
 
-- "I found this in your own desktop memories…"
-- "I found this in your common cross-project bucket (something you or another agent wrote under `meko_agent`)…"
+- "I found this in your personal memories (something you or another of your agents saved earlier)…"
 - "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 clients' buckets (e.g. also see what was written from `claude_code:some-repo` or `cursor:foo`), call `memory_search` once per known agent_id — empty string just resolves to `meko_agent`, not a fan-out.
+- "I couldn't find anything in your personal memories. You might want to check the Cloud UI's Memory Summary tab."
 
 ## Memory limitations for structured data