@yugabytedb/meko-mcp 2.0.0 → 2.2.0

package/assets/skills/meko-mcp-tools-desktop/SKILL.md

@@ -17,19 +17,19 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "2.7.0"
+  version: "2.8.0"
   tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko, desktop
 ---
 
 # Meko MCP Tools — Agent Behavioral Guide (Desktop)
 
-Meko is the user's **memory, knowledge, observability, and audit layer** across chats — a system of record they (and their team/org) connected on purpose. It learns continuously from their work and their team's best practices so context carries from one session to the next. This skill teaches you how to use Meko's 22 MCP tools. Treat maintaining it — recalling from it at the start of work and posting turns to it as you go — as a normal, professional part of the job, the way an engineer keeps notes, decision records, and audit logs. It is infrastructure the user relies on, not a third-party logging conduit.
+Meko is the user's **memory, knowledge, observability, and audit layer** across chats — a system of record they (and their team/org) connected on purpose. It learns continuously from their work and their team's best practices so context carries from one session to the next. This skill teaches you how to use Meko's 23 MCP tools available in production. Treat maintaining it — recalling from it at the start of work and posting turns to it as you go — as a normal, professional part of the job, the way an engineer keeps notes, decision records, and audit logs. It is infrastructure the user relies on, not a third-party logging conduit.
 
 **Read this first.** The Meko server extracts durable memories automatically from the conversation turns you post to it — the extraction runs *inside* `conversation_add_message`. Claude Desktop has no capture hooks, so **capturing substantive turns via `conversation_add_message` is a core part of using this skill.** Do that and memory takes care of itself: facts the user states get extracted and stored without a separate `memory_add`. Explicit `memory_add` is reserved for a few narrow cases (below). See "Per-turn conversation capture" — it's the heart of this skill.
 
 **Why this is legitimate.** Meko is the user's own system of record — serving their memory, their team's shared knowledge, and their observability/audit needs — so posting turns to it is maintaining *their* infrastructure, the same as keeping notes or decision logs. Do it **transparently**: briefly tell the user when you save or recall ("saved that to your Meko memory", "checked your Meko memory — here's what I had"), disclose the way a colleague would mention they're writing something down. The only carve-outs: if an item is sensitive (credentials, legal, medical) or the user asked you not to store something, ask or skip.
 
-> **If you reached a meko tool without reading this skill** (e.g. tool search resolved `memory_add`/`memory_search` directly): two rules override anything you inferred from the raw tool descriptions. (1) On Claude Desktop the `agent_id` is **always `"claude_desktop"`** (or `"meko_agent"` for cross-project identity) — **never `"claude_code"`**, which is a *different* client's bucket. (2) Prefer `conversation_add_message` over `memory_add` for facts the user stated — extraction handles them. Then read the rest of this skill.
+> **If you reached a meko tool without reading this skill** (e.g. tool search resolved `memory_add`/`memory_search` directly): two rules override anything you inferred from the raw tool descriptions. (1) On Claude Desktop use `agent_id="claude_desktop"` for normal writes (or `"meko_agent"` for cross-project writes) — never attribute Desktop writes to `"claude_code"`. (2) Prefer `conversation_add_message` over `memory_add` for facts the user stated — extraction handles them. Then read the rest of this skill.
 
 ## First turn of every session
 
@@ -39,12 +39,12 @@ On the first user turn in any session, before answering substantive questions:
 
 1. **Resolve the active datapack pin first — before creating the conversation.** A conversation cannot move between datapacks once created, so you must know the pinned datapack *before* `conversation_create`, or capture lands in the wrong workspace. Call:
    ```
-   memory_search(scope="read", query="meko_active_datapack",
+   memory_search(query="meko_active_datapack",
                  agent_id="claude_desktop", conversation_id="", limit=1)
    ```
    If a pin row comes back, extract the UUID after `meko_active_datapack=` — call it `<PIN>` — and pass `datapack_id="<PIN>"` to **every** Meko call for the rest of the session (`conversation_create`, `memory_search`, `conversation_add_message`, etc.). If no pin is found, omit `datapack_id` everywhere and let the server resolve the default. (The `meko-select-datapack-desktop` skill is what writes this pin; you honor it here whether or not that skill ran this session.)
 2. **Call `conversation_create`** (`agent_id="claude_desktop"`, and `datapack_id="<PIN>"` if a pin was found) once and keep the returned `conversation_id` for the whole session. You need it to post turns (per-turn capture, above) and for memory calls.
-3. **Call `memory_search`** with `agent_id="claude_desktop"`, the `conversation_id` from step 2, `datapack_id="<PIN>"` if pinned, and a query derived from the user's topic. Also call it once with `agent_id="meko_agent"` to surface cross-project facts (user identity, global preferences) that any Meko client may have stored.
+3. **Call `memory_search`** with `agent_id="claude_desktop"`, the `conversation_id` from step 2, `datapack_id="<PIN>"` if pinned, and a query derived from the user's topic. One search returns this user's memories across every agent, including the `meko_agent` common bucket; `agent_id` attributes the trace but does not filter memory results.
 4. Incorporate the recalled facts into your reply. Don't re-ask things you've been told before.
 
 Recall and capture are routine parts of answering — the user has set Meko up as their memory layer, so you don't need a per-call permission prompt for them. Do briefly say what you did ("checked your Meko memory", "saved that to your Meko memory") — a short disclosure, not a silent background action and not a big announcement.
@@ -56,10 +56,11 @@ Recall and capture are routine parts of answering — the user has set Meko up a
 **For Claude Desktop, use `agent_id="claude_desktop"` by default.** Desktop has no per-project concept, so a stable client name is the right granularity (it's a "loose" client in contract terms). Coding agents like Claude Code and Cursor use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts that any agent should see — user identity, global preferences — use the common bucket `agent_id="meko_agent"`.
 
 **Read scoping:**
-- `memory_search` / `memory_get_all` / `conversation_list` / `conversation_get` — scoped to `(datapack_id, user_id, agent_id)`, strictly matched. To read across multiple agents (e.g. memories you wrote from Claude Code in different repos), call once per agent_id. Empty/missing `agent_id` is rewritten to `meko_agent` server-side, so it returns the common bucket only — not a fan-out.
-- `knowledgebase_search` — scoped to `datapack_id` only. `agent_id` on the request is ignored. Returns the team's Shared Knowledge — uploaded documents plus memories the user promoted via the UI.
+- `memory_search` / `memory_get_all` — scoped to `(datapack_id, user_id)`. `agent_id` does not filter results, so one call returns this user's memories across every agent.
+- `conversation_list` — also returns this user's conversations across agents. `conversation_get` is agent-owned and requires the exact `agent_id` that created the conversation.
+- `knowledgebase_search` — scoped to `datapack_id` only. `agent_id` on the request is ignored. Returns the team's Shared Knowledge — uploaded documents plus promoted memories.
 
-Some pre-existing rows use the older constant `agent_id="agent"` or ad-hoc shapes (e.g. `claude-desktop` with a hyphen). They remain readable — query them with the literal value. See `tools-agent-id-conventions.md` for the full model.
+Some pre-existing rows use the older constant `agent_id="agent"` or ad-hoc shapes (e.g. `claude-desktop` with a hyphen). They remain readable; the stored value is still shown as provenance in the UI. See `tools-agent-id-conventions.md` for the full model.
 
 ## Per-turn conversation capture — the heart of this skill
 
@@ -68,7 +69,7 @@ Claude Desktop has no capture hooks, so you are the capture mechanism. **When th
 Concretely, once per session call `conversation_create` (see "First turn of every session" above) to get a `conversation_id`, then for each substantive exchange:
 
 ```
-conversation_add_message(scope="write", conversation_id="<id>",
+conversation_add_message(conversation_id="<id>",
     agent_id="claude_desktop",
     input="<the user's exact prompt>",
     output="<your exact response>",
@@ -99,8 +100,8 @@ Use the right bucket: `agent_id="meko_agent"` for cross-project facts (user iden
 
 Meko turns your volatile context window into persistent, shareable knowledge:
 
-- **Personal memory** — Store who the user is, their preferences, role, and working style. Survives across sessions. Private to you (scoped per-user and per-agent).
-- **Team-shared knowledge** — Memories the user promotes from the Learnings tab in the Cloud UI become visible to every member of the datapack. Uploaded documents land in the same place. Both are queryable via `knowledgebase_search`.
+- **Personal memory** — Store who the user is, their preferences, role, and working style. Survives across sessions. Private to the user and readable across all of their agents.
+- **Team-shared knowledge** — Important memories can be promoted with `memory_promote` (after explicit confirmation) or from the Learnings tab in the Cloud UI. Uploaded documents land in the same place. The resulting content is visible to every datapack member and queryable via `knowledgebase_search`.
 - **Conversation history** — Preserve full dialog exchanges with reasoning traces for audit, replay, and learning transfer.
 - **Decision traces** — Capture how and why decisions were made, enabling debugging and continuous improvement.
 
@@ -110,7 +111,7 @@ Meko turns your volatile context window into persistent, shareable knowledge:
 - You need to decide what to store, where, and how (personal memory vs. team-shared knowledge)
 - You want to search the team's shared knowledge base (`knowledgebase_search`)
 - You are managing datapacks
-- You want to understand scope/permission requirements, `agent_id` conventions, or `datapack_id` routing
+- You want to understand `agent_id` conventions, or `datapack_id` routing
 
 ## Critical: Use Meko, not local storage
 
@@ -139,8 +140,9 @@ Your job is not to decide fact-by-fact what to `memory_add`. It's to **post ever
 | User corrects or negates a prior fact | Post the turn (the new fact is extracted). Extraction is **additive**, so if the stale fact must not survive, `memory_search` for it and `memory_update` / `memory_delete_by_id`. |
 | User explicitly says "remember this" | `memory_add` (verbatim), in addition to posting the turn. |
 | A durable fact lives only in your output or a tool result | `memory_add`. Extraction reads the user side of the turn, so it won't capture these. |
-| User asks "what do you know about X?" | Three-call sweep: `memory_search(agent_id="claude_desktop")` → `memory_search(agent_id="meko_agent")` → `knowledgebase_search(datapack_id=<X>)`. |
+| User asks "what do you know about X?" | Two-call sweep: one `memory_search(agent_id="claude_desktop")` covers this user's memories across every agent; `knowledgebase_search(datapack_id=<X>)` covers team-shared knowledge. |
 | User asks "what do we (as a team) know about X?" or about uploaded documents | `knowledgebase_search` (returns uploaded docs + promoted memories). |
+| User asks to share specific private memories with the team | Follow the `memory_promote` confirmation workflow below. Never promote based on a fuzzy search result or implied consent. |
 | User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP. Point the user at the UI's Add Knowledge upload; do not `memory_add` row-by-row. |
 | User wants to add documents to the team's knowledge base | Point them at the Cloud UI flow — Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). MCP ingestion tools are not available on Cloud. |
 
@@ -151,7 +153,7 @@ The **what and when** is covered above ("Per-turn conversation capture" — post
 `conversation_create` — once per session; keep the `conversation_id`:
 
 ```
-conversation_create(scope="write", agent_id="claude_desktop",
+conversation_create(agent_id="claude_desktop",
     title="<descriptive topic>")
 ```
 
@@ -170,75 +172,80 @@ conversation_create(scope="write", agent_id="claude_desktop",
 
 Only for the three exception cases (explicit "remember this", output-only/tool-derived fact, overwriting correction) — not for facts the user stated, which the posted turn already captures. Example of an explicit save:
 ```
-memory_add(scope="write",
+memory_add(
            text="Remember: deploy scripts must be run from the repo root, never a subdir",
            agent_id="claude_desktop",
            conversation_id="<id from conversation_create>")
 ```
-Required parameters: `scope`, `text`, `agent_id`, `conversation_id`. On **writes**, `conversation_id` must be a real UUID from `conversation_create` — writes attached to a nil/empty conversation are orphaned in Langfuse traces. Empty / missing `agent_id` is NOT rejected — the server quietly falls back to the `meko_agent` common bucket. Pass `agent_id="claude_desktop"` explicitly so this client's writes stay in the right bucket and don't pollute the cross-project pool.
+Required parameters: `text`, `agent_id`, `conversation_id`. On **writes**, `conversation_id` must be a real UUID from `conversation_create` — writes attached to a nil/empty conversation are orphaned in Langfuse traces. Empty / missing `agent_id` is NOT rejected — the server quietly falls back to the `meko_agent` common bucket. Pass `agent_id="claude_desktop"` explicitly so this client's writes stay in the right bucket and don't pollute the cross-project pool.
 
 ### memory_search — correct call pattern
 ```
-memory_search(scope="read",
+memory_search(
               query="user role",
               agent_id="claude_desktop",
               conversation_id="<id from conversation_create>")
 ```
-Required parameters: `scope`, `query`, `agent_id`, `conversation_id`. On **`memory_search`** specifically, `conversation_id` is used only for Langfuse trace nesting — it does NOT filter results. Pass the session's UUID so the search span appears under the active conversation; passing `""` is accepted and means "don't nest under any trace." For conversation-scoped filtering use the separate `run_id` parameter.
+Required parameters: `query`, `agent_id`, `conversation_id`. On **`memory_search`** specifically, `conversation_id` is used only for Langfuse trace nesting — it does NOT filter results. Pass the session's UUID so the search span appears under the active conversation; passing `""` is accepted and means "don't nest under any trace." For conversation-scoped filtering use the separate `run_id` parameter.
 
-For cross-project common-bucket search (facts written under `agent_id="meko_agent"`, including everything written with empty/missing `agent_id`), pass it explicitly:
-```
-memory_search(scope="read", query="user role",
-              agent_id="meko_agent", conversation_id="<id>")
-```
+`agent_id` attributes the search trace but does not filter the returned memories. One call includes rows written by `claude_desktop`, `meko_agent`, coding agents, and legacy agent values for this user.
 
-Empty string also resolves to `meko_agent` server-side. To search across other clients' specific buckets (e.g. `claude_code:some-repo`), call `memory_search` once per known agent_id — there's no single-call fan-out.
-
-**Interpreting results — trust the memory rows, be skeptical of stray `relations`.** `memory_search` returns three lists: `results` (the actual stored memories — trust these), `relations`, and `promoted_relations` (entity-graph edges). Two things to know so you don't discard useful results:
+**Interpreting results.** `memory_search` returns a single list — `{"results": [...]}` — the stored memories, ranked by a hybrid score (semantic similarity + keyword match + a boost for memories mentioning the entities named in your query). There are no `relations` / `promoted_relations` keys. Two things to know so you don't discard useful results:
 
 - **`memory_search` is cross-agent by design.** Results include memories written by *other* clients (`agent_id` "agent", "claude_code:…", etc.) for the same user — that is expected, not a tenant leak. Use them.
-- **A `relations` edge can outlive the memory it came from.** Deleting a memory does not always remove its graph edges, so `relations` may contain stale or contradicted entities (e.g. an identity that conflicts with the consistent picture in `results`). When a relation contradicts the memory rows, **trust the rows and disregard the stray relation** — don't conclude the whole result set is "someone else's data" and throw it away.
+- **Older (pre-2.x) servers may still return `relations` / `promoted_relations` (graph edges) alongside `results`.** If they appear, trust the memory rows in `results` and disregard any edge that contradicts them — don't conclude the whole result set is "someone else's data" and throw it away.
 
 ### knowledgebase_search — correct call pattern
 ```
-knowledgebase_search(scope="read",
+knowledgebase_search(
                      query="...",
                      agent_id="<anything — ignored>",
                      conversation_id="<id>",
                      datapack_id="<datapack UUID>",
                      limit=10)
 ```
-Required parameters: `scope`, `query`, `agent_id`, `conversation_id`, `datapack_id`. `datapack_id` has no default here. `agent_id` is ignored for filtering — results are the team's shared knowledge on the datapack regardless of what you pass.
+Required parameters: `query`, `agent_id`, `conversation_id`, `datapack_id`. `datapack_id` has no default here. `agent_id` is ignored for filtering — results are the team's shared knowledge on the datapack regardless of what you pass.
+
+### memory_promote — explicit confirmation required
+
+`memory_promote` is destructive and non-idempotent: it makes selected content visible to the datapack, moves the memories into shared knowledge, and evicts the private mem0 records. There is no MCP rollback.
+
+1. Use `memory_search` or `memory_get_all` to obtain exact memory UUIDs from the `id` field. Never pass any other identifier.
+2. Present each exact candidate memory and its UUID to the user.
+3. State that promotion is one-way, team-visible, and removes the private records.
+4. Obtain explicit confirmation for those exact candidates before calling `memory_promote`.
+5. Call it with the active `conversation_id`, exact `memory_ids`, `agent_id="claude_desktop"`, and intended `datapack_id`. If a legacy deployment exposes `scope`, use the minimum `write` scope; do not escalate to `admin`.
+6. Only datapack owners and maintainers may promote. If a viewer/contributor receives 403, or any authentication/permission error occurs, report it and stop. Do not retry with a broader scope, another datapack, or altered identity.
+7. After success, optionally verify visibility with `knowledgebase_search`. Do not claim rollback is possible.
+
+The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 ### Critical parameter rules
 
-- **agent_id**: `"claude_desktop"` for this client's project-less personal writes/reads. Use `"meko_agent"` for the cross-project common bucket (genuinely global facts like user identity). Empty/missing routes to `meko_agent` server-side; that's not a cross-agent fan-out. Ignored on `knowledgebase_search`. See `tools-agent-id-conventions.md`.
+- **agent_id**: `"claude_desktop"` for this client's project-less writes and trace attribution. Use `"meko_agent"` when writing genuinely cross-project facts such as user identity. Empty/missing values on writes route to `meko_agent`. The value does not filter `memory_search`, `memory_get_all`, `conversation_list`, or `knowledgebase_search`; `conversation_get` is the read that requires the creating agent's exact value. See `tools-agent-id-conventions.md`.
 - **conversation_id**: Behavior varies by tool. On write tools (`memory_add`, `conversation_add_message`) pass a real UUID from `conversation_create` — a nil/empty value orphans the Langfuse trace. On `memory_search` it's used only for trace nesting (not for filtering), and empty-string is accepted; on `memory_get_all` and most read tools, still pass the session UUID when you have one. Never pass `"current"` or other non-UUID junk — only a real UUID or an intentionally empty string where the tool allows it.
-- **scope**: Only `"read"`, `"write"`, or `"admin"`. Nothing else.
 - **When in doubt about optional parameters, omit them.** The server has sensible defaults.
 
 ## Key concepts
 
-1. **22 tools in 5 groups**: Memory (8 — including `flush_pending_memory_candidates`, deprecated; per-turn `conversation_add_message` replaces it), Conversation (6), Knowledge Base (1 — `knowledgebase_search`), Datapack (5), Artifacts (2 — `artifact_put`, `artifact_get`). KB ingestion is UI-only (Datapack → Actions → Add Knowledge); raw SQL is not exposed. See `tools-overview.md`.
-2. **Scope hierarchy**: `read < write < admin` — every tool validates scope at entry. Only three valid values: `"read"`, `"write"`, `"admin"`. Using anything else (e.g., `"all"`) will fail. Pass the **minimum** each tool needs: reads (`memory_search`, `memory_get_*`, `conversation_get`/`list`, `datapack_list`/`describe`) take `"read"`; writes (`memory_add`/`update`, `conversation_create`/`add_message`, `datapack_create`/`update`) take `"write"`; only the destructive tools (`memory_delete_all`, `conversation_delete`, `datapack_delete`) require `"admin"`. Each tool's docstring states its required scope — follow it; don't escalate a search to `"admin"`.
-3. **datapack_id routing**: DB, RAG, and memory tools accept optional `datapack_id` (default datapack if omitted). `knowledgebase_search` is the exception: `datapack_id` is **required** there.
-4. **agent_id is multi-agent**: For Claude Desktop, use `agent_id="claude_desktop"` for desktop-personal writes and `agent_id="meko_agent"` for cross-project common facts. Writes are scoped to `(datapack_id, user_id, agent_id)`. Personal reads filter strictly on this tuple — to span agent_ids, call once per known value (the empty-string shortcut is not a fan-out; the server rewrites empty to `meko_agent`). `knowledgebase_search` ignores `agent_id` entirely. See `tools-agent-id-conventions.md`.
-5. **Personal memory vs. team-shared knowledge**: Un-promoted memories are scoped per-user and per-agent — only you see them. The user can promote important memories to Shared Knowledge via the Cloud UI's Learnings tab, which makes them visible to every team member on the datapack. `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents.
-6. **conversation_id IS the Langfuse trace ID**: every MCP tool call inside a conversation becomes a span under that trace. Observable in the Meko UI's Observe hub. See `tools-memory-vs-conversation.md`.
-7. **Adding documents to the team knowledge base is UI-only on Cloud today**: user uploads files via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each). The MCP ingestion tools are not available on Cloud. See `tools-rag-workflow.md`.
-8. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
-9. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly.
-10. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
-11. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks.
+1. **23 tools in 6 groups** (all available in production): Memory (8 — including `memory_promote`), Conversation (6), Knowledge Base (1 — `knowledgebase_search`), Datapack (5), Artifacts (2 — `artifact_put`, `artifact_get`), Observability (1 — `track_token_usage`). Memory is captured automatically from turns posted with `conversation_add_message` — post each substantive turn and the server extracts durable memories from it. KB ingestion is UI-only (Datapack → Actions → Add Knowledge); raw SQL is not exposed. See `tools-overview.md`.
+2. **datapack_id routing**: DB, RAG, and memory tools accept optional `datapack_id` (default datapack if omitted). `knowledgebase_search` is the exception: `datapack_id` is **required** there.
+3. **agent_id is multi-agent**: For Claude Desktop, use `agent_id="claude_desktop"` for normal writes and `agent_id="meko_agent"` for cross-project facts. Writes are attributed to `(datapack_id, user_id, agent_id)`. Personal memory reads and `conversation_list` span all of this user's agents; `conversation_get` remains agent-owned. `knowledgebase_search` ignores `agent_id` entirely. See `tools-agent-id-conventions.md`.
+4. **Personal memory vs. team-shared knowledge**: Un-promoted memories are scoped per-user — readable across all of that user's agents, but no other user can see them. With explicit confirmation, `memory_promote` moves exact memories into Shared Knowledge; the Cloud UI's Learnings tab is an alternative. Promoted content is visible to every datapack member. `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents.
+5. **conversation_id IS the Langfuse trace ID**: every MCP tool call inside a conversation becomes a span under that trace. Observable in the Meko UI's Observe hub. See `tools-memory-vs-conversation.md`.
+6. **Adding documents to the team knowledge base is UI-only on Cloud today**: user uploads files via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each). The MCP ingestion tools are not available on Cloud. See `tools-rag-workflow.md`.
+7. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
+8. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly.
+9. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
+10. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks.
 
 ## Reference sections
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 22 tools with decision tree |
+| `tools-overview.md` | Complete catalog of all 23 tools available in production, with decision tree |
 | `tools-cookbook.md` | Per-tool examples with correct parameters, responses, and error cases |
 | `tools-memory-vs-conversation.md` | When to use memory tools vs conversation tools |
 | `tools-rag-workflow.md` | End-to-end RAG pipeline flow |
-| `tools-scope-permissions.md` | read/write/admin permission hierarchy |
 | `tools-troubleshooting.md` | Error recovery, retry strategies, stuck pipeline diagnosis |
 | `tools-known-limitations.md` | Broken tools, missing capabilities, permission gaps |

package/assets/skills/meko-mcp-tools-desktop/desktop/README.md

@@ -1,6 +1,6 @@
 # Meko MCP Tools — Claude Desktop Setup
 
-Use the Meko MCP tools skill natively in Claude Desktop. Because Desktop has no lifecycle hooks, the skill teaches Claude to capture each substantive turn by posting it via `conversation_add_message` (the server extracts durable memories from those posts), to reserve explicit `memory_add` for the narrow cases (the user says "remember this", a fact lives only in the assistant's output or a tool result, or a corrected fact needs overwriting), to classify information, to use all 25 Meko MCP tools correctly, and to handle errors gracefully.
+Use the Meko MCP tools skill natively in Claude Desktop. Because Desktop has no lifecycle hooks, the skill teaches Claude to capture each substantive turn by posting it via `conversation_add_message` (the server extracts durable memories from those posts), to reserve explicit `memory_add` for the narrow cases (the user says "remember this", a fact lives only in the assistant's output or a tool result, or a corrected fact needs overwriting), to classify information, to use all <!--tool-count-->24<!--/tool-count--> Meko MCP tools correctly, and to handle errors gracefully.
 
 ## Setup
 
@@ -12,21 +12,21 @@ In Claude Desktop: Customize > Personal plugins > Browse plugin marketplace. Sea
 
 **Option B — .skill file:**
 
-Download `meko-mcp-tools-desktop.skill` from the [releases page](https://github.com/yugabyte/meko-mcp-server/releases) and drag it into Claude Desktop (or use Customize > Skills > Import).
+Download `meko-mcp-tools-desktop.skill` from the [releases page](https://github.com/yugabyte/meko-skills/releases) and drag it into Claude Desktop (or use Customize > Skills > Import).
 
 **Option C — Manual install:**
 
 ```bash
-git clone https://github.com/yugabyte/meko-mcp-server.git
+git clone https://github.com/yugabyte/meko-skills.git
 ```
 
-Copy `skills/skills/meko-mcp-tools-desktop/` into Claude Desktop's skill directory. The exact path depends on your Desktop version — check Customize > Skills for the install location.
+Copy `skills/meko-mcp-tools-desktop/` into Claude Desktop's skill directory. The exact path depends on your Desktop version — check Customize > Skills for the install location.
 
 ### Step 2: Configure the MCP server
 
 Add the Meko MCP server to your Claude Desktop configuration. Go to Claude > Settings > Developer > Edit Config and add a `mcpServers` entry.
 
-**Local HTTP** (for [meko-test](https://github.com/yugabyte/meko-test) docker-compose users):
+**Local HTTP** (for local Meko development environments):
 
 ```json
 {
@@ -70,7 +70,7 @@ Replace `/path/to/meko-mcp-server` with your cloned repo path and set the correc
 {
   "mcpServers": {
     "meko": {
-      "url": "https://<your-instance>.mcp.mekodev.com/mcp"
+      "url": "https://mcp.mekodata.ai/mcp"
     }
   }
 }

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

@@ -6,15 +6,15 @@ description: Maps reference files to their topics for the meko-mcp-tools-desktop
 # Reference Sections
 
 ## Tool Selection & Catalog
-- [tools-overview.md](tools-overview.md) — Complete catalog of all 22 tools with a decision tree
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 23 tools available in production, with a decision tree
 
 ## Tool-Specific Guidance
 - [tools-agent-id-conventions.md](tools-agent-id-conventions.md) — Multi-agent model: the three buckets (project `<client>:<repo-basename>`, common `meko_agent`, loose client name), personal vs. team-shared read surfaces
 - [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message, plus Desktop capture guidance
+- [tools-conversation-reasoning.md](tools-conversation-reasoning.md) — Authoring the `reasoning` and `plan` fields on `conversation_add_message`, with worked examples
 - [tools-rag-workflow.md](tools-rag-workflow.md) — End-to-end RAG pipeline: source registration, index creation, status polling
 
 ## Safety & Permissions
-- [tools-scope-permissions.md](tools-scope-permissions.md) — read/write/admin permission hierarchy and per-tool requirements
 
 ## Practical Usage
 - [tools-cookbook.md](tools-cookbook.md) — Per-tool examples with correct parameters, expected responses, and common errors

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,30 +77,32 @@ 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
+- `run_id` — **read/delete filter only**, and it filters on the row's
+  `meko_conversation_id`, so the value to pass is a *conversation id*, not a
+  free-form run label. On `memory_add` it is Langfuse trace metadata only and is
+  never persisted on the row: writing with `run_id=X` then reading with
+  `memory_search(run_id=X)` returns nothing, silently. Scope writes with
+  `conversation_id` instead (MEKO-473).
 
 Available on `memory_add`, `memory_search`, `memory_get_all`, `memory_delete_all`, `conversation_create`, `conversation_list`.
 
 ## 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."
+]
+```