@yugabytedb/meko-mcp 1.2.0 → 2.1.0

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

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

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

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