@yugabytedb/meko-mcp 2.1.0 → 2.2.0

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

@@ -8,7 +8,7 @@
 - A **preference**: "Customer budget is $50k"
 - An **entity relationship**: "Alice works at Acme Corp"
 
-Memory is backed by pgvector (semantic search) and Apache AGE (entity-relationship graph). It retrieves relevant facts by meaning, not by conversation order.
+Memory is backed by pgvector. Search is hybrid: semantic similarity, keyword matching, and a boost for memories that mention the entities named in your query (people, projects, tools). It retrieves relevant facts by meaning, not by conversation order.
 
 ```
 memory_add(agent_id="support_bot",
@@ -71,7 +71,7 @@ Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the
 
 | Read path | What it returns | How to call |
 |---|---|---|
-| 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 |
+| 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 every bucket | `memory_search(agent_id="<your agent_id>", query="...", ...)` |
 | 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 |
 
 `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.
@@ -80,7 +80,7 @@ Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the
 
 - **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. 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.
+  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 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.
@@ -89,18 +89,7 @@ Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the
 
 ### When the user asks "what do you know about X?"
 
-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=..., ...)   # all your personal memories, every agent
-knowledgebase_search(agent_id="<anything>", datapack_id="<uuid>", query="X", conversation_id=..., ...)
-```
-
-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 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."
+A full sweep is two calls: `memory_search` (all your personal memories, every agent — no per-agent fan-out) then `knowledgebase_search` (team-shared knowledge). When you answer, name which surface each finding came from, so the user knows why something is or isn't there.
 
 ## Memory limitations for structured data
 
@@ -114,72 +103,28 @@ There is no MCP-side "just put it in a database table" option — raw SQL access
 
 ## Memory Storage: automatic, not proactive
 
-On Claude Code, do **not** proactively `memory_add` facts the user states. Conversation capture is automatic (see below) and the server extracts durable memories from the captured turns on its own — personal info, team conventions, domain knowledge the user states, and corrections are all saved without a tool call. Re-storing them with `memory_add` just duplicates what extraction already holds.
-
-Explicit `memory_add` is reserved for the three cases automatic extraction cannot reach:
-
-- **Explicit request** → the user says "remember this" / "save this."
-- **Output-only / tool-derived fact** → a durable fact that lives only in your output or a tool result, never in a user turn. Extraction reads only the user turn, so it never sees these.
-- **Overwriting correction** → a prior fact was negated and the stale memory must not survive. Extraction is additive (it adds the new fact but leaves the old one live), so `memory_search` for the stale memory and `memory_update` / `memory_delete_by_id` it.
-
-Use `memory_search` at the start of sessions to recall what you already know before asking the user to repeat themselves.
-
-## Using Both Together
-
-Capture stores the full conversation (preserves structure) and extraction derives searchable memories from it — both happen automatically. Add an explicit `memory_add` only for the three cases above.
+On Claude Code, do **not** proactively `memory_add` facts the user states — capture + server-side extraction stores them automatically. Explicit `memory_add` is reserved for the three cases extraction cannot reach (explicit "remember this"; output-only/tool-derived facts; overwriting a negated fact) — the canonical list and rules live in SKILL.md. Use `memory_search` at session start to recall what you already know.
 
 ## Key Retrieval Difference
 
-- `memory_search`: **semantic similarity** across all memories via pgvector. Returns relevant facts regardless of when stored.
-- `conversation_get`: **ordered list of message turns** for a specific conversation. No semantic search. Requires `conversation_id`.
+- `memory_search`: **semantic similarity** across all memories — relevant facts regardless of when stored.
+- `conversation_get`: **ordered message turns** for one conversation. No semantic search; requires `conversation_id`.
 
 ## Automatic Conversation Capture
 
-The Meko plugin captures conversations automatically via three mechanisms:
+The plugin captures conversations via three mechanisms — a periodic checkpoint (~10 min), a PreCompact hook, and a SessionEnd hook — storing the full transcript verbatim (user prompts as `input`, assistant text as `output`, tool calls and results as `reasoning`).
 
-1. **Periodic checkpoint (~10 min)** — Agent-driven via CronCreate, uses `conversation_add_message` MCP tool directly
-2. **PreCompact hook** — Shell script that fires before Claude Code's auto-compaction, captures via MCP JSON-RPC
-3. **SessionEnd hook** — Shell script that fires at session termination, captures final exchanges
+Each message's seed is `<conversation_id>:<user_message_uuid>`; all three mechanisms derive the same deterministic trace ID from it, so overlapping captures are idempotent. A shared watermark file tracks what has been saved.
 
-### What gets captured
-
-The full transcript including:
-- **User prompts** — verbatim text (the `input` field)
-- **Assistant responses** — all text blocks (the `output` field)
-- **Tool calls** — tool name + input parameters (the `reasoning` field)
-- **Tool results** — output from tool executions (appended to `reasoning`)
-
-This is more than just text — tool calls and results are critical context for session replay, cross-agent sharing, and compaction.
-
-### Seed-based deduplication
-
-Each message's seed is `<conversation_id>:<user_message_uuid>`. All three capture mechanisms generate the same seed for the same exchange, producing the same deterministic trace ID via `sha256(seed)[:16].hex()`. This means duplicate writes from overlapping captures are idempotent.
-
-### When to manually store conversations
-
-Automatic capture handles the raw exchange. You should still manually use `conversation_create` + `conversation_add_message` when:
-- The user explicitly asks to "save this conversation"
-- You want to add curated `reasoning` traces beyond raw tool calls
-- You want to store a selected subset of the conversation with a descriptive title
-
-### Watermark coordination
-
-A shared watermark file at `~/.claude/meko-capture/<session-id>.watermark.json` tracks what has been saved. Both hooks and the agent's periodic checkpoint use this to avoid reprocessing already-captured exchanges.
+Manually use `conversation_create` + `conversation_add_message` only when the user explicitly asks to save a conversation, or you want curated `reasoning` traces or a titled subset.
 
 ## Observability: conversation_id IS the Langfuse trace ID
 
-This is the feature agents tend to miss. Verified live 2026-05-07 in the Meko UI's Observe hub.
+This is the feature agents tend to miss.
 
-- `conversation_create` returns a `conversation_id` (e.g. `d71fc8b61a7f45d585eea9a6436e0c3f`).
-- That ID is also the **Langfuse trace_id** for the conversation. Not a separate trace — literally the same identifier.
-- Every subsequent MCP tool call made while passing that `conversation_id` becomes a **span under that trace**, named after the tool: `Memory Add (Meko MCP)`, `Memory Search (Meko MCP)`, `Knowledgebase Search (Meko MCP)`, `Conversation Add Message (Meko MCP)`, etc.
-- Child spans reveal internals. Observed structure:
-  - `memory_add`: `Memory Add (Meko MCP)` → `Create a new memory in Mem0` → `Bulk Payload Update (yugabytedb / vector)` → `Execute Query (yugabytedb / vector)`
-  - `memory_search`: `Memory Search (Meko MCP)` → `Search for memories based on a query in Mem0` (Retriever)
-  - `conversation_add_message`: `Conversation Add Message (Meko MCP)` → `Conversation Message Added` span → `Reasoning` generation (the `reasoning` field is stored as a Langfuse *generation*-typed span, not a plain text field)
-  - `knowledgebase_search`: `Knowledgebase Search (Meko MCP)` → multiple `Execute Query (yugabytedb)` child spans
-- Trace tags include `agent:<agent_id>` and the Meko org UUID. Both are searchable/filterable in Langfuse.
-- Each datapack has its own Langfuse project — traces for a tool call land in the project for whichever `datapack_id` was on the call (or the default datapack if omitted).
+- `conversation_create` returns a `conversation_id`; that ID **is** the Langfuse trace_id — not a separate trace, the same identifier.
+- Every MCP tool call made with that `conversation_id` becomes a span under the trace, named after the tool (e.g. `Memory Search (Meko MCP)`), with child spans exposing the storage steps.
+- Trace tags include `agent:<agent_id>` and are filterable. Each datapack has its own Langfuse project — traces land in the project of whichever `datapack_id` was on the call.
 
 ### Finding a trace in the UI
 
@@ -190,14 +135,14 @@ Two navigation paths, both verified in the Meko UI:
 
 The Conversations-tab row preview shows the first user turn verbatim, plus the agent_id tag, message count, and started-at timestamp. If you want a conversation to be recognizable in the UI, call `conversation_add_message` with a clean first-turn `input` early in the session.
 
-### Observed latencies on prod (2026-05-07)
+### Typical latencies
 
 From real traces, not the docstring happy path:
 
 | Tool | Latency per call |
 |---|---|
-| `memory_add` | 12-21 seconds (calls OpenAI for extraction, then writes to vector + graph) |
-| `memory_search` | 1.8-5.9 seconds |
+| `memory_add` | ~10-30 seconds (calls an LLM for extraction, then writes to the vector store; scales with payload size) |
+| `memory_search` | ~2-6 seconds (small, focused memories; whole-document stores read ~4x slower — chunk on write) |
 | `knowledgebase_search` | 0.6 seconds (empty index; will grow with index size) |
 | `conversation_add_message` | 0.11 seconds (fire-and-forget; queued to Langfuse) |
 
@@ -205,9 +150,6 @@ From real traces, not the docstring happy path:
 
 ### Proactive diagnostic pattern
 
-If a user reports "my memory_add didn't seem to save", open the Observe hub for their datapack, filter on their `conversation_id`, and look at the span tree. You will see either:
-
-- A `Memory Add (Meko MCP)` span with `Create a new memory in Mem0` child → the call reached Mem0. The fact extractor may have returned `"results": []` (common on short or non-fact-shaped text; not a bug, but lossy).
-- No span at all → the call never reached the server. Likely a transport / auth / `conversation_id` mismatch issue.
+If a user reports "my memory_add didn't seem to save", open the Observe hub, filter on their `conversation_id`, and check the span tree: a memory-add span present means the call arrived (the extractor may still have returned `"results": []` on non-fact-shaped text); no span means the call never reached the server (transport / auth / `conversation_id` mismatch).
 
-The mem0 extractor is lossy — it extracts atomic facts and graph triples, and may drop prose that doesn't look fact-shaped to it. Observed 2026-05-07: 2 of 5 `memory_add` calls returned `"results": []` and only the graph side landed. When preserving authoritative text matters, store it via `conversation_add_message` (verbatim in `input`/`output`/`reasoning`) — the conversation path preserves text without LLM re-extraction.
+The mem0 extractor is lossy — it extracts atomic facts and may drop prose that doesn't look fact-shaped to it; a `memory_add` can return `"results": []` on non-fact-shaped text. When preserving authoritative text matters, store it via `conversation_add_message` (verbatim in `input`/`output`/`reasoning`) — the conversation path preserves text without LLM re-extraction.

package/assets/skills/meko-mcp-tools/references/tools-overview.md

@@ -1,19 +1,20 @@
 # Complete Tool Catalog and Decision Tree
 
-**23 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
+**23 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1). Combined Meko + AMP endpoints may expose additional infrastructure tools; those are outside this skill's scope.
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
 1. `memory_search(query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-2. `datapack_list()` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
+2. `datapack_list(conversation_id="<session-conversation-id>")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
 
 ## Decision tree: which tool do I need?
 
 ```
 User wants to...
-├── Search a knowledge base? ---------------> knowledgebase_search (read)
+├── Search personal context? ---------------> memory_search (read)
+├── Search shared datapack knowledge? ------> knowledgebase_search (read)
 ├── Add documents to a knowledge base? -----> point user at Meko UI: Datapack → Actions → Add Knowledge
 │                                              (no MCP tool — Cloud uses UI ingestion only)
 ├── Store or recall information?
@@ -42,13 +43,13 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 | Tool | Purpose |
 |------|---------|
 | `memory_add(text, agent_id, conversation_id, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
-| `memory_search(query, agent_id, conversation_id="", limit=10, datapack_id=None)` | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
+| `memory_search(query, agent_id, conversation_id="", limit=10, datapack_id=None)` | Hybrid search across memories (semantic + keyword + entity boost). `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
 | `memory_get_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
 | `memory_get_all(agent_id, conversation_id, run_id=None, datapack_id=None)` | List all of the user's memories (every agent — `agent_id` does not filter) |
 | `memory_update(memory_id, text, agent_id, conversation_id, datapack_id=None)` | Overwrite memory text |
 | `memory_delete_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Delete a single memory |
 | `memory_delete_all(agent_id, conversation_id, run_id=None, datapack_id=None)` | Delete all memories for agent (destructive) |
-| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them + graph context out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403. |
+| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403. |
 
 ## Conversation Tools (6)
 
@@ -66,9 +67,9 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 | Tool | Purpose |
 |------|---------|
 | `datapack_create(name)` | Create new datapack |
-| `datapack_list()` | List all datapacks |
+| `datapack_list(conversation_id, datapack_id=None)` | List all datapacks. `conversation_id` is required for trace nesting; omit `datapack_id` to use the endpoint default. |
 | `datapack_describe(datapack_id, include_status=False)` | Describe datapack by UUID |
-| `datapack_update(datapack_id, name=None, description=None)` | Rename a datapack and/or update its description. Pass at least one of `name` / `description`. |
+| `datapack_update(datapack_id, name=None, description=None, conversation_search_opt_out=None)` | Rename a datapack, update its description, and/or opt out of (or back into) conversation-search caching. Pass at least one field. Opt-out is owner/maintainer only. |
 | `datapack_delete(datapack_id)` | Delete datapack by UUID (irreversible) |
 
 ## Artifact Tools (2)

package/assets/skills/meko-mcp-tools/references/tools-troubleshooting.md

@@ -7,7 +7,7 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
 2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
 3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
-4. **Use your session's `agent_id` consistently on writes.** Pass the value the SessionStart hook injected (e.g. `claude_code:<repo-basename>` for Claude Code; `claude_desktop` for Claude Desktop) on every write so rows are attributed correctly, and on `conversation_get` (which *does* enforce it — conversations are owned by the `agent_id` that created them; a wrong value returns `agent_id_mismatch`). Memory reads (`memory_search`/`memory_get_all`) and `conversation_list` are not affected — they return all your agents' rows for this user regardless of the `agent_id` passed. Don't switch write forms mid-session.
+4. **Use your session's `agent_id` consistently on writes** (the SessionStart-injected value), and on `conversation_get` — conversations are owned by the creating `agent_id`; a wrong value returns `agent_id_mismatch`. Memory reads and `conversation_list` are unaffected by `agent_id`. Don't switch write forms mid-session.
 
 ---
 
@@ -26,6 +26,27 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 ---
 
+## An error payload is a FAILED search, never an empty one
+
+Quota errors, rate-limit errors, and tool refusals come back as an error object with **no `results` key** — reading `response.get("results", [])` first silently converts "you were refused" into "the store is empty." Follow SKILL.md operating contract 1: report it as "search failed: `<error code>` — findings unknown," never as "no results."
+
+---
+
+## Rate limiting: `PAT_RATE_LIMITED`
+
+Bursts of requests on one token return:
+
+```json
+{"error": "PAT_RATE_LIMITED", "detail": "too many requests for this token; retry after 60s"}
+```
+
+- Throttling is **endpoint-specific**: `artifact_put` bursts and high-concurrency `memory_get_all` trigger it readily; `memory_search` tolerates far more. Do not assume one safe concurrency level for every tool.
+- A rate-limited `artifact_put` returns this error **instead of** a `content_hash` — checking only for the hash misreads throttling as silent write loss.
+- Honor the retry-after (~60s) or back off exponentially; pace sustained work. Retry only idempotent operations or hash-protected writes.
+- Distinct from the lifetime quota error (`free_tier_limit_reached`) — waiting never recovers that one.
+
+---
+
 ## agent_id errors
 
 On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.

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

@@ -75,6 +75,6 @@ Personal content crosses the `user_id` boundary through `memory_promote` or the
 | `user_id` | The cognito account or end-user (for multi-user agents) | auto from cognito for single-human clients; explicit string for multi-user agents | Optional (server auto-fills from cognito context) |
 | `agent_id` | Which agent wrote / is reading | `"claude_code:<repo>"`, `"claude_desktop"`, `"cursor:<repo>"`, `"meko_agent"` (common bucket) | Optional (empty/missing → `meko_agent` server-side); pass the per-session value verbatim for project-scoped reads/writes. Ignored on `knowledgebase_search`. |
 | `app_id` | Optional application/product sub-scope | `"second_brain"`, `"helpdesk"` | Optional |
-| `run_id` | Optional specific execution run | `"run_20260507_001"` | Optional |
+| `run_id` | A conversation id, used as a read/delete filter against the row's `meko_conversation_id` | `"374c70f3b95745ac92724d98475cc2d6"` | Optional. On `memory_add` it is trace metadata only and does not scope the write — see `tools-agent-id-conventions.md`. |
 
 See `tools-agent-id-conventions.md` for the full `agent_id` model.

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

@@ -17,13 +17,13 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "2.7.2"
+  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 23 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.
 
@@ -190,10 +190,10 @@ Required parameters: `query`, `agent_id`, `conversation_id`. On **`memory_search
 
 `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.
 
-**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
 ```
@@ -208,9 +208,9 @@ Required parameters: `query`, `agent_id`, `conversation_id`, `datapack_id`. `dat
 
 ### memory_promote — explicit confirmation required
 
-`memory_promote` is destructive and non-idempotent: it makes selected content visible to the datapack, moves the memories and graph context into shared knowledge, and evicts the private mem0 records. There is no MCP rollback.
+`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. Never pass relation or graph-edge IDs.
+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`.
@@ -228,7 +228,7 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 ## Key concepts
 
-1. **23 tools in 6 groups**: 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`.
+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.
@@ -243,7 +243,7 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 23 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 |

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 <!--tool-count-->23<!--/tool-count--> 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
 

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

@@ -6,7 +6,7 @@ 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 23 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

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

@@ -92,7 +92,12 @@ Always tell the user which surface you searched: personal memory or team-shared
 
 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`.
 

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

@@ -46,6 +46,8 @@ memory_add(agent_id="agent", user_id="amiram",
 
 **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.
 
+**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.
+
 ```
 memory_search(query="What programming language does the team use?", agent_id="agent")
 ```
@@ -127,7 +129,7 @@ memory_promote(memory_ids=["mem-uuid-123", "mem-uuid-456"],
 {"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`.
+Get exact UUIDs from the `id` field of `memory_search` / `memory_get_all` results; never pass any other identifier. 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.
 
@@ -155,8 +157,6 @@ conversation_create(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.
 
-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(conversation_id="conv-uuid-123", agent_id="agent",
     input="Why is the auth middleware returning 401?",
@@ -327,18 +327,19 @@ For large files use `local_path` to read the file. S3 URLs are never exposed.
 
 ```
 datapack_create(name="analytics_prod")
-datapack_list()  # returns datapack_id for each datapack
+datapack_list(conversation_id="<this conversation's id>")  # returns datapack_id for each datapack
 datapack_describe(datapack_id="<uuid>", include_status=True)
 ```
 
 ### datapack_update / datapack_delete
 
-`datapack_update` renames or edits a datapack's description. At least one of `name` / `description` must be provided (or the tool returns `nothing_to_update`). The server refuses to rename `meko_default_datapack` — the error is `"meko_default_datapack cannot be renamed"`. Passing `description=""` does NOT clear an existing description.
+`datapack_update` renames a datapack, edits its description, and/or opts it in/out of conversation-search embedding. At least one of `name` / `description` / `conversation_search_opt_out` must be provided (or the tool returns `nothing_to_update`). The server refuses to rename `meko_default_datapack` — the error is `"meko_default_datapack cannot be renamed"`. Passing `description=""` does NOT clear an existing description. `conversation_search_opt_out=True` stops future turns from being indexed 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(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!
 ```
 

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

@@ -8,7 +8,7 @@
 - A **preference**: "Customer budget is $50k"
 - An **entity relationship**: "Alice works at Acme Corp"
 
-Memory is backed by pgvector (semantic search) and Apache AGE (entity-relationship graph). It retrieves relevant facts by meaning, not by conversation order.
+Memory is backed by pgvector. Search is hybrid: semantic similarity, keyword matching, and a boost for memories that mention the entities named in your query (people, projects, tools). It retrieves relevant facts by meaning, not by conversation order.
 
 ```
 memory_add(agent_id="support_bot",
@@ -80,7 +80,7 @@ One `memory_search` already spans this user's memories across all agents; no per
 
 - **Personal memories** — written by `memory_add`. The `agent_id` records the writer but does not restrict reads; memories are scoped per-user, so any of that user's agents can read them and no other user can.
 - **Team-shared Shared Knowledge** — arrives two ways:
-  1. 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.
+  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 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.
@@ -194,7 +194,7 @@ From real traces, not the docstring happy path:
 
 | Tool | Latency per call |
 |---|---|
-| `memory_add` | 12-21 seconds (calls OpenAI for extraction, then writes to vector + graph) |
+| `memory_add` | 12-21 seconds (calls OpenAI for extraction, then writes to the vector store) |
 | `memory_search` | 1.8-5.9 seconds |
 | `knowledgebase_search` | 0.6 seconds (empty index; will grow with index size) |
 | `conversation_add_message` | 0.11 seconds (fire-and-forget; queued to Langfuse) |
@@ -208,4 +208,4 @@ If a user reports "my memory_add didn't seem to save", open the Observe hub for
 - A `Memory Add (Meko MCP)` span with `Create a new memory in Mem0` child → the call reached Mem0. The fact extractor may have returned `"results": []` (common on short or non-fact-shaped text; not a bug, but lossy).
 - No span at all → the call never reached the server. Likely a transport / auth / `conversation_id` mismatch issue.
 
-The mem0 extractor is lossy — it extracts atomic facts and graph triples, and may drop prose that doesn't look fact-shaped to it. Observed 2026-05-07: 2 of 5 `memory_add` calls returned `"results": []` and only the graph side landed. When preserving authoritative text matters, store it via `conversation_add_message` (verbatim in `input`/`output`/`reasoning`) — the conversation path preserves text without LLM re-extraction.
+The mem0 extractor is lossy — it extracts atomic facts and may drop prose that doesn't look fact-shaped to it. Observed 2026-05-07 (on the graph-era server): 2 of 5 `memory_add` calls returned `"results": []`. When preserving authoritative text matters, store it via `conversation_add_message` (verbatim in `input`/`output`/`reasoning`) — the conversation path preserves text without LLM re-extraction.

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

@@ -1,19 +1,20 @@
 # Complete Tool Catalog and Decision Tree
 
-**23 tools on Cloud Meko** (verified against `https://mcp.mekodata.ai/mcp`). Grouped: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1).
+**23 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Memory (8), Conversation (6), Knowledge Base (1), Datapack (5), Artifacts (2), Observability (1). Combined Meko + AMP endpoints may expose additional infrastructure tools; those are outside this skill's scope.
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
 1. `memory_search(query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-2. `datapack_list()` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
+2. `datapack_list(conversation_id="<this conversation's id>")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
 
 ## Decision tree: which tool do I need?
 
 ```
 User wants to...
-├── Search a knowledge base? ---------------> knowledgebase_search (read)
+├── Search personal context? ---------------> memory_search (read)
+├── Search shared datapack knowledge? ------> knowledgebase_search (read)
 ├── Add documents to a knowledge base? -----> point user at Meko UI: Datapack → Actions → Add Knowledge
 │                                              (no MCP tool — Cloud uses UI ingestion only)
 ├── Store or recall information?
@@ -42,13 +43,13 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 | Tool | Purpose |
 |------|---------|
 | `memory_add(text, agent_id, conversation_id, user_id=None, app_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
-| `memory_search(query, agent_id, conversation_id="", user_id=None, limit=10, datapack_id=None)` | Semantic search across memories + graph relations. `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
+| `memory_search(query, agent_id, conversation_id="", user_id=None, limit=10, datapack_id=None)` | Hybrid search across memories (semantic + keyword + entity boost). `conversation_id` optional (omit or pass `""` for cross-conversation discovery). |
 | `memory_get_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. |
 | `memory_get_all(agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | List all memories for agent |
 | `memory_update(memory_id, text, agent_id, conversation_id, datapack_id=None)` | Overwrite memory text |
 | `memory_delete_by_id(memory_id, agent_id, conversation_id, datapack_id=None)` | Delete a single memory |
 | `memory_delete_all(agent_id, conversation_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | Delete all memories for agent (destructive) |
-| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them + graph context out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403.
+| `memory_promote(conversation_id, memory_ids, agent_id=None, datapack_id=None)` | Promote private memories into the datapack's shared knowledge base (moves them out of mem0, then evicts from mem0 — one-way). Owners/maintainers only; viewers/contributors get 403.
 
 ## Conversation Tools (6)
 
@@ -66,7 +67,7 @@ Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typi
 | Tool | Purpose |
 |------|---------|
 | `datapack_create(name)` | Create new datapack |
-| `datapack_list()` | List all datapacks |
+| `datapack_list(conversation_id, datapack_id=None)` | List all datapacks. `conversation_id` is required for trace nesting; omit `datapack_id` to use the endpoint default. |
 | `datapack_describe(datapack_id, include_status=False)` | Describe datapack by UUID |
 | `datapack_update(datapack_id, name=None, description=None)` | Rename a datapack and/or update its description. Pass at least one of `name` / `description`. |
 | `datapack_delete(datapack_id)` | Delete datapack by UUID (irreversible) |

package/assets/skills/meko-select-datapack-desktop/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "1.2.0"
+  version: "1.2.1"
   tags: meko, datapack, selection, project, claude-desktop, desktop
 ---
 

package/assets/skills/meko-select-datapack-desktop/references/cookbook.md

@@ -11,7 +11,7 @@ Concrete transcripts of the four flows the skill supports on Claude Desktop.
 > memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
 [empty]
 
-> datapack_list()
+> datapack_list(conversation_id="<conv-id>")
 [14 entries returned, filtering by "prod-research"]
 
 One match: `prod-research`. Pinning.
@@ -44,7 +44,7 @@ datapack_id flows through automatically.
 > memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
 [returns id=mem_abc123, text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
 
-> datapack_list()
+> datapack_list(conversation_id="<conv-id>")
 [14 entries returned, filtering by "q2-roadmap-deck"]
 
 One match: `q2-roadmap-deck`. Switching pin.
@@ -69,7 +69,7 @@ The `memory_update` is critical here — using `memory_add` again would create a
 > memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
 [empty]
 
-> datapack_list()
+> datapack_list(conversation_id="<conv-id>")
 [1 entry returned]
 
 Only one datapack: `meko-local-setup`. Auto-selecting.