@yugabytedb/meko-mcp 2.0.0 → 2.2.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,38 +1,34 @@
 # 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* (from the SessionStart `additionalContext`) — it is stored on the row as attribution. It does **not** filter reads: one `memory_search` / `memory_get_all` returns all of your memories across every `agent_id`. For cross-project facts, write with `agent_id="meko_agent"`.
 
 ### 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.")
 ```
 
 **Response:**
 ```json
-{"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.")
+{"results": [{"id": "mem-uuid-123", "memory": "Deploy scripts must be run from the repo root, never a subdir."}]}
 ```
 
 **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)
+- Multi-topic dumps (transcripts, mixed logs + decisions) — store **one coherent fact per memory**, with the identifiers a later search will use
 
 **Common errors:**
 - `syntax error at or near "-"` — legacy error from the pre-multi-tenancy schema when `agent_id` became part of a PostgreSQL identifier. No longer applies on Cloud (agent_id is a TEXT column value, any string is accepted). If you hit it on a deployment that still uses the old schema, use underscores instead of hyphens.
@@ -45,9 +41,13 @@ 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 (`agent_id` scopes the call's trace, not the 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. For a deliberately cross-conversation search leave `run_id` off; to scope a search to a single conversation instead, pass `run_id=<conversation_id>` (it filters on `meko_conversation_id` — see `tools-known-limitations.md`).
+
+**Relevance floor.** Vector-matched `results` below `MEMORY_SEARCH_MIN_SCORE` (mem0's cosine-similarity score, default `0.5`) are dropped as weak matches rather than returned. A query can come back with fewer results than `limit`, or an empty list, when nothing clears the bar; that means no sufficiently relevant memory, not a broken call.
+
 **Response:**
 ```json
 {"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
@@ -55,22 +55,19 @@ 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)
 ```
 
+**Evidence cap (SKILL.md operating contract 3): reason over at most ~10 results, no matter how many were retrieved or requested.** If asked to "use everything," still select the ~10 most relevant and say that you did.
+
 ---
 
 ### memory_get_all
 
-**When to use:** List everything stored for an agent. Useful at session start to load context.
+**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.
 
 ```
-memory_get_all(scope="read", agent_id="agent")
-```
-
-**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 +75,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 +85,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 +93,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", 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 any other identifier), and follow the confirmation checklist in SKILL.md before calling. On 403 or any auth failure, report and stop — never escalate scope, change datapacks, or alter identity.
+
+---
+
 ## Conversation Tools
 
 ### conversation_create
@@ -118,7 +133,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 +148,19 @@ conversation_create(scope="write", agent_id="agent", user_id="amiram",
 
 **When to use:** Add a user/assistant exchange to an existing conversation. **All fields must be verbatim** — never summarize or rephrase.
 
-Pass `index_for_search=True` on substantive turns so this conversation is embedded into the shared conversation-history cache (searchable later via `conversation_search` / `contextual_prominence_search`). This isn't limited to WorkbenchLM — pass it for agent-harness conversations too.
-
 ```
-conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+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 +168,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 +176,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 +189,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 +197,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 +217,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>",
@@ -212,7 +226,7 @@ knowledgebase_search(
 
 Unlike memory tools, `datapack_id` has no default — you must pass it explicitly.
 
-**Response (empty KB, verified 2026-05-07):**
+**Response (empty KB):**
 ```json
 {"results": [], "count": 0}
 ```
@@ -229,7 +243,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>",
@@ -255,6 +268,7 @@ Save the `content_hash` — it's the retrieval key for `artifact_get`.
 **Common errors:**
 - `invalid_base64` — `content_base64` is not valid base64; decode the file before passing it.
 - `artifact_too_large` — file exceeds 5 MiB (default). Set `MEKO_MAX_ARTIFACT_UPLOAD_BYTES` to raise the limit.
+- `PAT_RATE_LIMITED` — burst uploads throttle; the error carries **no `content_hash`**, which mimics silent write loss. Pace bulk uploads, back off ~60s. The `content_hash` is the plain SHA-256 of the bytes — compute it locally and verify important artifacts with an `artifact_get` read-back.
 
 ---
 
@@ -265,7 +279,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 +322,23 @@ 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(conversation_id="<session conversation id>")  # returns datapack_id for each datapack
+datapack_describe(datapack_id="<uuid>", include_status=True)
 ```
 
 ### datapack_update / datapack_delete
 
+`datapack_update` renames a datapack, edits its description, and/or opts it in/out of conversation-search embedding. `name`, `description`, and `conversation_search_opt_out` are all optional; pass at least one. If none are provided 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. Conversation-search embedding is on by default; `conversation_search_opt_out=True` stops future turns from being indexed (already-cached turns are unaffected) and is restricted to the datapack's owner or a maintainer. This is best-effort, not a hard guarantee — a transient database error on the live embed path's opt-out check fails open, so a turn can occasionally still get embedded for an opted-out datapack.
+
 ```
-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_update(datapack_id="<uuid>", conversation_search_opt_out=True)
+datapack_delete(datapack_id="<uuid>")  # Irreversible!
 ```
 
 ### Agent and knowledge-base management (NOT MCP — control-plane only)
@@ -326,6 +346,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

@@ -2,6 +2,30 @@
 
 These are current limitations of the Meko MCP tools. Know them upfront to avoid wasted tool calls.
 
+## Lifetime request quotas by tier
+
+`memory_search`, `knowledgebase_search`, and `memory_add` are quota-gated **per user, lifetime** — not per minute or per day. Default caps by plan:
+
+| Tier | memory_search | knowledgebase_search | memory_add |
+|---|---:|---:|---:|
+| Free | 1,000 | 1,000 | 10,000 |
+| Standard | 5,000 | 5,000 | 30,000 |
+| Pro / Enterprise | uncapped | uncapped | uncapped |
+
+When the cap is reached the tool returns an error object with code `free_tier_limit_reached` (on every tier; the `tier` field names the capped tier) and **no `results` key**.
+
+- **Do not retry** — the cap is lifetime.
+- **Budget searches**: polling, verify read-backs, and per-item sweeps all draw from one pool.
+- **Never report this error as "no results"** — it is a failed search; see `tools-troubleshooting.md`.
+
+## memory_get_all returns a fixed recent window — it has NO pagination
+
+One call returns roughly the **20 most recent rows**; the response's `total` reports the true count. Scoping arguments do not narrow the window, and paging parameters are rejected — there is no way to reach older rows through this tool. A second call with `promoted=true` returns the recent window of promoted rows, not the remaining personal rows; neither call alone nor the two together is a complete listing. Follow SKILL.md operating contract 2: state the gap when `total` exceeds rows returned, never claim a complete enumeration, and use `memory_search` or `memory_get_by_id` for anything specific.
+
+## run_id is a read/delete filter on the conversation id, not a write key
+
+`memory_search(run_id=<conversation_id>)` and the memory delete tools filter on the row's `meko_conversation_id`, so passing a conversation id there correctly scopes the call to that one conversation — a supported, reliable way to read a single conversation's memories (read/write/delete scoping was made consistent in MEKO-473/MEKO-474, #271). The one gotcha is on the write side: `memory_add`'s own `run_id` is Langfuse trace metadata only and is **not** persisted as the row's conversation id, so a row written with `memory_add(run_id=X)` is not findable via `memory_search(run_id=X)`. Scope writes with `conversation_id`, then filter the matching read by that same id.
+
 ## No delete tools for RAG artifacts
 
 There are no MCP tools to:
@@ -25,7 +49,7 @@ To **query** a built index, use `knowledgebase_search` — it returns both uploa
 `memory_add` passes text through Mem0's fact extraction pipeline. This works well for:
 - Facts: "Alice works at Acme Corp"
 - Preferences: "User prefers dark mode"
-- Entity relationships: "Amiram reports to Karthik"
+- Entity relationships: "Alice reports to Bob"
 
 It works **poorly** for:
 - CSV rows or tabular data — columns and rows get dropped
@@ -36,7 +60,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 +70,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.