@yugabytedb/meko-mcp 2.0.0 → 2.1.0

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

@@ -4,13 +4,13 @@
 
 When MCP clients have built-in Langfuse hooks (Cursor, Claude Code), both the client hook and the MCP server may write a trace for the same message → duplicate traces, doubled message counts, corrupted conversation retrieval.
 
-**WRONG:** Neither `seed` nor `trace_id` provided → both sides generate random IDs → two traces per message.
+**WRONG:** No `seed` provided → both sides generate random trace IDs → two traces per message.
 
 ## Solution: Use seed for deterministic trace IDs
 
 ```
 conversation_add_message(
-    scope="write", conversation_id="conv-uuid", agent_id="my_agent",
+    conversation_id="conv-uuid", agent_id="my_agent",
     input="What is our Q3 revenue?",
     output="Q3 revenue was $4.2M, up 15% from Q2.",
     seed="conv-uuid:my_agent:What is our Q3 revenue?"
@@ -19,11 +19,10 @@ conversation_add_message(
 
 Both sides hash the same seed string to produce the same trace ID. Langfuse treats the second write as an upsert → exactly one trace.
 
-## Priority Rules
+## Trace ID Rules
 
-1. **`trace_id`** — if provided, used directly (highest precedence)
-2. **`seed`** — if provided, hashed to produce deterministic trace ID
-3. **Neither** — random trace ID generated
+1. **`seed`** — if provided, hashed to produce a deterministic trace ID
+2. **Not provided** — a random trace ID is generated
 
 ## Choosing a Good Seed
 
@@ -41,7 +40,6 @@ seed = f"{conversation_id}:{agent_id}:{message_index}"
 |----------|-----|
 | Client hook + MCP server both write to Langfuse | `seed` |
 | Only the MCP server writes (no client hook) | Neither (random is fine) |
-| Migrating from another system with existing IDs | `trace_id` |
 | Replaying messages idempotently | `seed` |
 
 ## session_id on conversation_create

package/assets/skills/meko-mcp-tools/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/references/tools-cookbook.md

@@ -1,21 +1,22 @@
 # 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.** 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 `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 with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
 
 ---
 
 ## Memory Tools
 
-**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.
+**Critical:** Pass your session's `agent_id` on every memory *write* (the value from the SessionStart `additionalContext`, e.g. `claude_code:meko-mcp-server`) — it is stored on the row and rendered as the UI badge. Note that `agent_id` labels writes but does **not** filter personal reads: a single `memory_search` / `memory_get_all` returns all of your memories for this user across every `agent_id` (see the `memory_search` note below). For genuinely cross-project facts, write with `agent_id="meko_agent"` so the row lands in the common bucket.
 
 ### memory_add
 
 **When to use:** NOT for facts the user states in conversation — those are saved automatically by conversation capture + server-side extraction. Reserve `memory_add` for the three cases extraction can't reach: (1) the user explicitly says "remember this"; (2) a durable fact that lives only in your output or a tool result, never in a user turn; (3) overwriting a negated/corrected fact (pair with `memory_delete_by_id`, since extraction is additive).
 
 ```
-memory_add(scope="write", agent_id="<your-agent-id>",
+memory_add(agent_id="<your-agent-id>",
+    conversation_id="<uuid from conversation_create or the SessionStart hook>",
     text="Remember: deploy scripts must be run from the repo root, never a subdir.")
 ```
 
@@ -24,12 +25,6 @@ memory_add(scope="write", agent_id="<your-agent-id>",
 {"results": [{"id": "mem-uuid-123", "memory": "User Amiram is VP of Product at YugabyteDB. Prefers concise responses."}]}
 ```
 
-**With user scoping:**
-```
-memory_add(scope="write", agent_id="agent", user_id="amiram",
-    text="Prefers Python for backend, Go for infrastructure.")
-```
-
 **What NOT to store via memory_add:**
 - Full conversations (use `conversation_create` + `conversation_add_message`)
 - Large documents (use the UI's Datapack → Actions → Add Knowledge upload flow)
@@ -45,9 +40,11 @@ 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.
 
 ```
-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", conversation_id="<uuid>")
 ```
 
+**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.
+
 **Response:**
 ```json
 {"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
@@ -55,22 +52,17 @@ 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", conversation_id="<uuid>", limit=5)
 ```
 
 ---
 
 ### memory_get_all
 
-**When to use:** List everything stored for an agent. Useful at session start to load context.
-
-```
-memory_get_all(scope="read", agent_id="agent")
-```
+**When to use:** List all of your memories for this user — across every `agent_id` (`agent_id` does not filter the result). Useful at session start to load context.
 
-**With user scoping:**
 ```
-memory_get_all(scope="read", agent_id="agent", user_id="amiram")
+memory_get_all(agent_id="agent", conversation_id="<uuid>")
 ```
 
 ---
@@ -78,7 +70,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", conversation_id="<uuid>")
 ```
 
 ---
@@ -88,7 +80,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", conversation_id="<uuid>")
 ```
 
 ---
@@ -96,21 +88,41 @@ 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", conversation_id="<uuid>")
 ```
 
 ---
 
 ### 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(scope="admin", agent_id="agent")
+memory_delete_all(agent_id="agent", conversation_id="<uuid>")
 ```
 
 ---
 
+### 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_promote(memory_ids=["mem-uuid-123", "mem-uuid-456"],
+    agent_id="agent", 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
 
 ### conversation_create
@@ -118,7 +130,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",
     title="Debugging the auth middleware")
 ```
 
@@ -133,23 +145,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 +167,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 +175,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 +188,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 +196,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 +216,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 +242,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 +277,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="agent"
@@ -309,16 +320,22 @@ For large files use the `local_path` value to read the file with normal file too
 ### 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 the description of a datapack. Both `name` and `description` are optional; pass at least one. If both are omitted the tool returns `nothing_to_update` without hitting the API.
+
+The server refuses to rename the caller's `meko_default_datapack` — a rename call against that datapack returns `"meko_default_datapack cannot be renamed"`. Description edits on the default datapack are still allowed. Passing `description=""` does NOT clear an existing description; clearing is not supported via MCP.
+
 ```
-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)
@@ -326,6 +343,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/references/tools-datapack-workflow.md

@@ -22,8 +22,8 @@ Datapacks are isolated workspaces — each has its own memory store and knowledg
 ### Creation
 
 ```
-datapack_create(scope="write", agent_id="<your agent_id>",
-    conversation_id="<uuid>", name="sales_analytics")
+datapack_create(name="sales_analytics",
+    conversation_id="<uuid>")
 -- Returns: {"datapack_id": "dp-uuid-123", "datapack_name": "sales_analytics", ...}
 ```
 
@@ -37,20 +37,20 @@ If the user asks to set those up mid-session, point them at the control plane ra
 ### Targeting a specific datapack on subsequent calls
 
 ```
-memory_search(scope="read", agent_id="<your-agent-id>",
+memory_search(agent_id="<your-agent-id>",
     conversation_id="<uuid>", query="...", datapack_id="dp-uuid-123")
-knowledgebase_search(scope="read", agent_id="<your-agent-id>",
+knowledgebase_search(agent_id="<your-agent-id>",
     conversation_id="<uuid>", datapack_id="dp-uuid-123", query="...")
 ```
 
-### Teardown (requires admin scope)
+### Teardown
 
 Delete child resources first (agents and KB sources via the control plane), then the datapack:
 
 ```
 # Control-plane (REST or UI): DELETE /datapacks/:datapack_id/knowledge-bases
 # Control-plane (REST or UI): DELETE /datapacks/:datapack_id/agents/sales_agent
-datapack_delete(scope="admin", datapack_id="dp-uuid-123")  # MCP-exposed, destructive, irreversible
+datapack_delete(datapack_id="dp-uuid-123")  # MCP-exposed, destructive, irreversible
 ```
 
 ## Common mistake: forgetting datapack_id on memory tools

package/assets/skills/meko-mcp-tools/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)")
@@ -46,8 +46,8 @@ It works **poorly** for:
 
 Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
 
-## 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/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",
-    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.", user_id="alice_123")
+memory_add(agent_id="support_bot",
+    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.")
 
-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", 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,42 @@ 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 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="...", ...)` |
+| Your personal memories | Everything you and any of your agents wrote for this user — filtered by `(datapack_id, user_id)`, **not** by `agent_id`. One call covers your project bucket, the `meko_agent` common bucket, and every other project's rows. | `memory_search(agent_id="<your agent_id>", query="...", ...)` — `agent_id` scopes the Langfuse trace, not the results |
 | 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.
+`agent_id` does not filter memory reads, so a single `memory_search` already spans all of your agents; there is no per-agent fan-out to do.
 
 ### 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 via MCP, 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 0.6-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
+memory_search(agent_id="<your-agent-id>", query="X", conversation_id=..., ...)   # all your personal memories, every agent
 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:
+The single `memory_search` already returns everything you and any other agent wrote for this user (`agent_id` doesn't filter memory reads) — no per-agent fan-out. 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 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 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.
+- "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