@yugabytedb/meko-mcp 2.2.0 → 2.3.0

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

@@ -4,15 +4,15 @@ description: Behavioral guide for AI agents using Meko MCP tools. Triggers when
 license: MIT
 metadata:
   author: Meko
-  version: "3.1.0"
+  version: "3.2.0"
   tags: mcp, tools, datapack, memory, conversation, rag, meko
 ---
 
 # Meko MCP Tools — Agent Behavioral Guide
 
-Meko is agent-native data infrastructure that enables continuous learning from context windows through collective memory and shared knowledge. This skill teaches you how to use Meko's 23 MCP tools available in production.
+Meko is agent-native data infrastructure that enables continuous learning from context windows through collective memory and shared knowledge. This skill teaches you how to use Meko's 25 MCP tools available in production.
 
-**Read this first.** On Claude Code, conversation capture is automatic (SessionStart / PreCompact / SessionEnd hooks) and the Meko server extracts durable memories from the captured turns on its own. Facts the user states in conversation are saved for you — you do **not** proactively call `memory_add` for them. Your active jobs are: **recall** what's already known (`memory_search`, `knowledgebase_search`), and the **few** save cases automatic extraction cannot reach. Details below.
+**Read this first.** On Claude Code, conversation capture is automatic (SessionStart / PreCompact / SessionEnd hooks) and the Meko server extracts durable memories from the captured turns on its own. Facts the user states in conversation are saved for you — you do **not** proactively call `memory_add` for them. Your active jobs are: **recall** what's already known (`context_search` first, then `memory_search` or `knowledgebase_search` for a single source), and the **few** save cases automatic extraction cannot reach. Details below.
 
 ## Non-negotiable operating contracts
 
@@ -22,8 +22,8 @@ Apply these rules before the longer guidance below. They are service-contract sa
 
 Inspect the response envelope before its contents:
 
-1. If `error` or an error-shaped `detail` is present, the search **failed** and its findings are **unknown**. Say exactly that. Never say "nothing was found," "no results," or "the store is empty."
-2. Do not retry quota (`free_tier_limit_reached`) or permission errors. Report the error and stop. Retry only documented transient failures, with a bounded backoff.
+1. If `error` or an error-shaped `detail` is present, or the whole response is an error string (for example `Error searching memories: ...` or `[Errno 111] Connection refused`), the search **failed** and its findings are **unknown**. Say exactly that. Never say "nothing was found," "no results," or "the store is empty."
+2. Do not retry quota (`free_tier_limit_reached`), permission (403), or validation errors. Report the error and stop. The one exception is `datapack_access_denied`: retry it once, because the server's access check also fails closed on a transient database error. Retry only documented transient failures (see `tools-troubleshooting.md`), with a bounded backoff. For `PAT_RATE_LIMITED`, wait out the retry-after (about 60s) before retrying.
 3. Only a successful response with an explicit empty `results` array proves a legitimate empty search.
 
 ### 2. Treat `memory_get_all` as a recent window, never an export
@@ -39,6 +39,7 @@ If no candidate supports an answer, abstain: say the retrieved evidence does not
 ### 4. Verify writes and enforce real isolation
 
 - A success-shaped write response is not proof. Read back memories and conversations. For artifacts, compute SHA-256 locally, require the matching `content_hash`, then read back important bytes. A missing hash means the upload is unconfirmed.
+- A read-back must use the same `datapack_id` as the write. Checking the default datapack after writing to a pinned one proves nothing.
 - `agent_id` attributes writes; it is not an access boundary. Put projects, tenants, or security domains that must not co-discover content in separate datapacks.
 
 ## `agent_id` — multi-agent identity
@@ -47,9 +48,11 @@ Use the SessionStart-injected `agent_id` verbatim. It normally has shape `<clien
 
 **Read scoping varies by tool:**
 - `memory_search` / `memory_get_all` — scoped to `(datapack_id, user_id)`; `agent_id` does not filter results. Do not fan out reads by agent.
-- `conversation_get` — agent-owned: pass the exact `agent_id` that created the conversation; any other value returns `agent_id_mismatch`.
+- `conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`: agent-owned. Pass the exact `agent_id` that created the conversation; any other value returns `agent_id_mismatch`.
+- `memory_delete_all`: deletes only the passed `agent_id`'s bucket, even though memory reads span every agent. A `memory_search` preview can show rows this call won't delete.
 - `conversation_list` — user/datapack scoped; `agent_id` is trace attribution only.
 - `knowledgebase_search` — datapack scoped; `agent_id` is ignored.
+- `context_search`: the memory and KB buckets follow the rules above. The conversation bucket is broader than both: it spans every user and agent on the datapack, and `agent_id` doesn't filter it.
 
 See `tools-agent-id-conventions.md` for the full model, including how promotion works and how to phrase broad-query responses to the user. Legacy IDs remain readable through the same personal-memory read.
 
@@ -77,6 +80,8 @@ Meko context (inherited from parent session):
 
 Reuse the inherited conversation unless the parent or user explicitly requests a fresh scope. Always reuse the inherited agent ID.
 
+Parallel subagents writing to one conversation have hit intermittent `not_found` or `agent_id_mismatch` ("conversation belongs to agent 'None'") on `conversation_add_message` right after `conversation_create`, while other subagents succeeded with identical arguments. Retry that call once with the same `seed` after a few seconds. If it still fails, don't create a replacement conversation: save the durable findings with `memory_add` and tell the parent the transcript for that subagent is incomplete.
+
 **You may be the subagent.** If no SessionStart context named a `conversation_id`, assume you are one and look for the block above in your prompt. If it is absent, do not guess, invent IDs, use the nil UUID, or write — ask the parent for both values.
 
 ## Core principle: capture is automatic — recall, don't re-store
@@ -93,7 +98,7 @@ Recall first; save only what capture cannot reach; never re-store a just-stated
 | User corrects a prior fact | Capture adds the correction but may retain the old fact; find and update/delete the stale memory when it must not survive. |
 | User explicitly says "remember this" / "save this to memory" | `memory_add` (verbatim). This is the clearest explicit-save case. |
 | A durable fact appears only in assistant output or a tool result | `memory_add`; automatic extraction reads the user turn. |
-| User asks "what do you know about X?" | Search both production retrieval surfaces: `memory_search` for personal context, then `knowledgebase_search` for shared datapack knowledge when relevant. |
+| User asks "what do you know about X?" | `context_search`. One call returns separate memory, knowledge-base, and past-conversation buckets; report each. Confirm an empty memory or KB bucket with `memory_search` or `knowledgebase_search` before saying nothing is stored. |
 | User asks "what do we (as a team) know about X?" or about uploaded documents | `knowledgebase_search` (returns uploaded docs + promoted memories). |
 | User asks to share private memories | Follow the exact-ID `memory_promote` confirmation workflow below. |
 | User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP. Point the user at the UI's Add Knowledge upload; do not `memory_add` row-by-row. |
@@ -122,6 +127,8 @@ memory_search(query="destructive <action type> preferences feedback",
 
 A single search covers all of this user's agents. Memory is supplemental evidence, not authorization: a relevant preference can require more caution, but an empty search never authorizes destruction. Follow host approval rules and prefer previews.
 
+If your host's policy doesn't let you run a Meko delete tool even when the user asks, say so plainly and hand the user what they need to do it themselves: the exact memory or conversation IDs, a one-line summary of each, and the tool call to run from a client that allows deletes. Don't report the data as deleted.
+
 ### Capture rules
 
 - **Verbatim content only** — never summarize, rephrase, or condense. See `tools-memory-vs-conversation.md`.
@@ -129,6 +136,21 @@ A single search covers all of this user's agents. Memory is supplemental evidenc
 - **Always use a seed** — enables dedup across the three capture mechanisms.
 - **Graceful failure** — if `conversation_add_message` fails, log the error and continue. Do not retry more than once.
 
+### Long-running conversations
+
+Meko stores a conversation as one Langfuse trace, and Langfuse refuses to load a trace larger than its size limit. After a long session crosses that limit, reads of the session's own conversation fail even though the conversation exists:
+
+- `conversation_get` and `conversation_update` return `{"error": "not_found", "detail": "Conversation <id> not found"}`, or the call times out.
+- On servers without the MEKO-714 fix, `conversation_add_message` returns the same `not_found`.
+
+When this happens on the conversation you've been using all session, accept the error and keep working:
+
+- Don't retry the call, create a replacement conversation, or replay earlier messages. Each replay makes the trace larger, and recreating the conversation has caused capture loops.
+- Skip the read-back for that conversation. Tell the user once that Meko can't load this conversation because it's too large, and don't report it as data loss.
+- Keep using `context_search`, the `memory_*` tools, and `knowledgebase_search`. They don't load the conversation trace.
+
+A `not_found` for a conversation you just created, or one this session never wrote to, has other causes; see `tools-troubleshooting.md`.
+
 ## Calling tools correctly on the first attempt
 
 **Use only the required parameters. Do not guess optional parameters.**
@@ -150,6 +172,27 @@ Required parameters: `text`, `conversation_id`. On **writes**, `conversation_id`
 
 **Write one coherent fact per memory**, with the identifiers a later search will use — never a transcript or multi-topic dump; focused memories retrieve better and read far faster.
 
+### context_search: default first call for recall
+
+```
+context_search(
+               query="auth migration decisions",
+               agent_id="<your-agent-id>",
+               conversation_id="<session_conversation_id>",
+               datapack_id="<pinned datapack UUID, if any>")
+```
+
+Required parameters: `query`, `conversation_id`. It queries memory, the knowledge base, and the conversation-history cache in parallel and returns `{"results": {"memory": [...], "knowledge_base": [...], "conversation": {"hits": [...], "thread": [...]}}, "token_savings": {...}}`.
+
+- Read every bucket. A KB document can supersede a memory or a past conversation; nothing is hidden by another source's hit.
+- An empty bucket is ambiguous: either that source found nothing relevant, or it failed. `context_search` turns a failed source into an empty list and records the error only in the trace. Before you tell the user nothing is stored about X, confirm with `memory_search` or `knowledgebase_search`, which return errors.
+- A bucket is `null` only when that source wasn't queried: `force_source` excluded it, or the server couldn't build a query vector for it.
+- The conversation bucket is datapack-wide. It returns embedded turns from every user and agent on the datapack, and each hit carries its author's `user_id`. Don't present a hit as this user's own history.
+- `limit` bounds the memory and KB buckets only; the conversation bucket returns up to 10 hits plus a thread of whole turns.
+- The memory bucket has no similarity floor on the default path, so it can contain weak rows. Discount them against the other buckets instead of treating them as answers.
+- Set `force_source` to `"memory"`, `"knowledge_base"`, or `"conversation"` only when you already know the one source you need.
+- Use `memory_search` or `knowledgebase_search` directly when you need `run_id` filtering, the memory similarity floor, or exact document IDs for `knowledgebase_delete_document`.
+
 ### memory_search — correct call pattern
 
 ```
@@ -159,9 +202,9 @@ memory_search(
               conversation_id="<session_conversation_id>")
 ```
 
-Required parameters: `query`, `agent_id`, `conversation_id`. On **`memory_search`** specifically, `conversation_id` is used only for Langfuse trace nesting — it does NOT filter results. Pass the session's UUID so the search span appears under the active conversation in Observe; passing `""` is accepted and means "don't nest under any trace."
+Required parameters: `query`, `conversation_id`. On **`memory_search`** specifically, `conversation_id` is used only for Langfuse trace nesting — it does NOT filter results. Pass the session's UUID so the search span appears under the active conversation in Observe. Never pass `""`: production `memory_search` currently fails on an empty value (MEKO-707). If you have no conversation yet, pass a freshly generated 32-character lowercase hex id (a UUID with the hyphens removed); on a read it only nests the trace.
 
-`agent_id` does not filter what `memory_search` returns — one call covers every agent's rows for this user, including the `meko_agent` bucket (see Read scoping above).
+`agent_id` does not filter what `memory_search` returns — one call covers every agent's rows for this user, including the `meko_agent` bucket (see Read scoping above). Results below a server-configured similarity floor (default 0.2) are dropped, so an empty `results` list can mean "only weak matches", not "nothing stored".
 
 Evidence going into reasoning follows operating contract 3 (retrieve ≤ ~25, pass ≤ ~10).
 
@@ -180,7 +223,7 @@ knowledgebase_search(
                      limit=10)
 ```
 
-Required parameters: `query`, `agent_id`, `conversation_id`, `datapack_id`. `datapack_id` has no default here. `agent_id` is ignored for filtering — results are the team's shared knowledge on the datapack regardless of what you pass.
+Required parameters: `query`, `conversation_id`, `datapack_id`. `datapack_id` has no default here. `agent_id` is ignored for filtering — results are the team's shared knowledge on the datapack regardless of what you pass.
 
 For recalling working memories — especially recently-changed facts — prefer `memory_search`; the knowledge base is the team's publish/archive surface.
 
@@ -201,7 +244,7 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 ### Critical parameter rules
 
 - **agent_id**: Per-session value, injected via `additionalContext` by the SessionStart hook. Shape: `<client>:<repo-basename>`. Pass verbatim on project-scoped writes and reads. Pass `"meko_agent"` for the cross-project common bucket (or empty/omit — server rewrites empty to `meko_agent`). Ignored on `knowledgebase_search`. See `tools-agent-id-conventions.md`.
-- **conversation_id**: the conversation's ID *is* its trace ID, so every call carrying it becomes a span under that conversation in the Observe hub. On write tools (`memory_add`, `conversation_add_message`) pass a real UUID from `conversation_create` or the SessionStart hook — a nil/empty value orphans the trace. On `memory_search` it only nests the trace (it does not filter), and empty-string is accepted; on `memory_get_all` and most read tools, still pass the session UUID when you have one. Never pass `"current"` or other non-UUID junk.
+- **conversation_id**: the conversation's ID *is* its trace ID, so every call carrying it becomes a span under that conversation in the Observe hub. On write tools (`memory_add`, `conversation_add_message`) pass a real UUID from `conversation_create` or the SessionStart hook — a nil/empty value orphans the trace. On read tools it only nests the trace (it does not filter), but it must still be a 32-hex id: `memory_search` fails on `""`, and most other tools reject it with `conversation_id_required`. Never pass `"current"` or other non-UUID junk.
 - **When in doubt about optional parameters, omit them.** The server has sensible defaults.
 
 ### Verify after writing
@@ -209,7 +252,7 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 Never confirm a successful save to the user without first validating via a read-back. `{"status": "accepted"}` or HTTP 200 from a write tool is not proof of persistence — indexing lag, silent server errors, and wrong-datapack routing all surface as "the write looked fine but nothing is there." Always read back before reporting success.
 
 - **After `memory_add`**: call `memory_search` with a distinctive token from the stored text (a name, UUID, rare phrase — not a common word). Assert the new memory appears in the results. Only then tell the user it was saved.
-- **After `conversation_add_message`**: call `conversation_get(include_messages=true)` with the returned `conversation_id`. Assert `message_count` > 0 and that the new message is in the returned list.
+- **After `conversation_add_message`**: call `conversation_get(include_messages=true)` with the returned `conversation_id`. Assert `message_count` > 0 and that the new message is in the returned list. On a long conversation whose trace is too large for Langfuse, `conversation_get` returns `not_found` even though the write landed. Follow "Long-running conversations" above instead of re-posting or recreating the conversation.
 - **After `artifact_put`**: operating contract 4 — the locally-computed SHA-256 must match the returned `content_hash` (a rate-limited or errored put carries **none**); read back important artifacts via `artifact_get` and compare bytes.
 - **On verification failure**: tell the user the save did not succeed — do **not** claim it did. Include the verification-failure detail (empty search, missing message, HTTP error) so they can act — wrong datapack, scope mismatch, expired API key are the common causes.
 
@@ -234,13 +277,13 @@ On the first Meko tool call in a fresh session (no prior Meko tool call since pr
 
 ## Budgeting calls
 
-`memory_add` takes ~10s for a one-line fact and ~20-30s for document-sized text; `memory_search` ~2-6s. Sustained bulk ingest throttles to roughly per-call latency — run large ingests as background jobs. `memory_search`, `knowledgebase_search`, and `memory_add` also draw from **lifetime per-user quotas** on Free/Standard tiers, so budget latency *and* call count. `datapack_id` is optional on most tools (default datapack) but **required** on `knowledgebase_search`. See `tools-known-limitations.md`.
+`memory_add` takes ~10s for a one-line fact and ~20-30s for document-sized text; `memory_search` ~2-6s. Sustained bulk ingest throttles to roughly per-call latency — run large ingests as background jobs. `memory_search`, `knowledgebase_search`, and `memory_add` also draw from **lifetime per-user quotas** on Free/Standard tiers, and `context_search` and `conversation_add_message` on the Free tier, so budget latency *and* call count. `datapack_id` is optional on most tools (default datapack) but **required** on `knowledgebase_search`. See `tools-known-limitations.md`.
 
 ## Reference sections
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 23 tools available in production, with decision tree |
+| `tools-overview.md` | Complete catalog of all 25 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-datapack-workflow.md` | Datapack lifecycle and datapack_id routing |

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

@@ -6,7 +6,7 @@ description: Maps reference files to their topics for the meko-mcp-tools skill
 # Reference Sections
 
 ## Tool Selection & Catalog
-- [tools-overview.md](tools-overview.md) — Complete catalog of all 23 tools available in production, with a decision tree
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 25 tools available in production, with a decision tree
 
 ## Tool-Specific Guidance
 - [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message
@@ -18,7 +18,7 @@ description: Maps reference files to their topics for the meko-mcp-tools skill
 
 ## Conventions & Deduplication
 - [tools-agent-id-conventions.md](tools-agent-id-conventions.md) — agent_id naming rules, hyphen prohibition, and namespace isolation
-- [tools-user-id-conventions.md](tools-user-id-conventions.md) — user_id vs agent_id: when to pass each, and how they scope memory
+- [tools-user-id-conventions.md](tools-user-id-conventions.md) — how the server resolves user_id from your credentials, and how it and agent_id scope memory
 - [tools-conversation-dedup.md](tools-conversation-dedup.md) — Seed-based deterministic trace IDs for Langfuse deduplication
 
 ## Practical Usage

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

@@ -14,7 +14,16 @@ Each memory is written under an `agent_id` (stored on the row, shown as the UI b
 | Loose client name | Non-coding agents (Claude Desktop, generic MCP clients) where there's no project concept. | `claude_desktop` |
 | `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` |
 
-**Discover the value at session start.** The SessionStart hook injects the chosen `agent_id` into the first-turn `additionalContext` based on the cwd's repo basename. Use that value verbatim — do not re-derive it. If the block is absent, fall back to `<client>:<basename(cwd)>` or ask the user.
+**Discover the value at session start.** The SessionStart hook injects the chosen `agent_id` into the first-turn `additionalContext`. Project-scoped ids are derived by walking parents of the session cwd for `.git` and taking the repo-root basename; the walk stops at `$HOME`, so a git-tracked home directory does not claim every directory beneath it. Sessions outside any repo get the bare client name (`claude_code`), not a leaf basename.
+
+Use the injected value verbatim — do not re-derive it. A resumed session, or one that re-fires SessionStart (`/clear`, `/compact`), keeps the bucket its conversation already belongs to, and `MEKO_AGENT_ID` overrides either, so the injected value is not always what a fresh derivation would produce. If the block is absent, ask the user rather than guessing from the raw cwd basename (sibling directories like `docs/` or `webapp/` in unrelated repos would collide).
+
+MEKO-590 changed new coding-session ids from the cwd leaf to the repository
+root. Existing ownership does not change in place: migration checkpoints and
+Kiro session intents keep their persisted pre-MEKO-590 id, because the server
+does not allow an existing conversation's owner to change. Datapack pins also
+fall back to the old cwd-leaf filename until the user pins or clears again.
+New sessions without persisted state use the repository-root id.
 
 For genuinely cross-project facts ("the user's name is Alice", "the user prefers dark mode") write with `agent_id="meko_agent"` so their attribution clearly identifies the common cross-project bucket.
 
@@ -42,7 +51,7 @@ Filter tuple: `(datapack_id, user_id)`. `agent_id` is **not** applied on memory
 
 ### Personal conversation reads — `conversation_get`, `conversation_list`
 
-- `conversation_get` — agent-owned. Filter tuple `(datapack_id, user_id, agent_id)`: pass the exact `agent_id` that created the conversation; a wrong value returns `agent_id_mismatch`.
+- `conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete` — agent-owned. Filter tuple `(datapack_id, user_id, agent_id)`: pass the exact `agent_id` that created the conversation; a wrong value returns `agent_id_mismatch`.
 - `conversation_list` — **not** agent-filtered. It lists by `(datapack_id, user_id)` only; `agent_id` on the call is trace-attribution only (like memory reads), so one call returns the datapack's conversations for your user regardless of which agent created them.
 
 ### Team-shared reads — `knowledgebase_search`
@@ -81,13 +90,12 @@ knowledgebase_search(agent_id=anything, query=...)
 
 ## When to use what — broad-query guidance
 
-If the user asks "what do you know about X?": one `memory_search` covers the whole personal surface (every `agent_id`, nothing to fan out), then `knowledgebase_search` for team-shared knowledge. Tell the user which surface each finding came from.
+If the user asks "what do you know about X?": one `context_search` returns the whole personal memory surface (every `agent_id`, nothing to fan out), team-shared knowledge, and matching past-conversation turns in separate buckets. Tell the user which surface each finding came from. Conversation hits can come from other users on the datapack.
 
 ## Optional sub-scoping
 
 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 Code; more common in API products)
-- `run_id` — on `memory_search` and the delete tools it is a **read/delete
+- `run_id` — on `memory_search` and `memory_delete_all` it is a **read/delete
   filter** on the row's `meko_conversation_id`, so pass a *conversation id* to
   scope the call to that conversation (consistent scoping landed in
   MEKO-473/MEKO-474, #271). On `memory_add` it is Langfuse trace metadata only
@@ -95,10 +103,10 @@ Optional parameters can narrow a call further:
   `conversation_id` — a row written with `memory_add(run_id=X)` is not findable
   via `memory_search(run_id=X)`.
 
-Available on `memory_add`, `memory_search`, `memory_get_all`, `memory_delete_all`, `conversation_create`, `conversation_list`.
+Accepted by `memory_add`, `memory_search`, `memory_get_all`, `memory_delete_all`, and `conversation_create`. `memory_get_all` ignores it. No tool takes a `user_id` argument; the server resolves it from your credentials (see `tools-user-id-conventions.md`).
 
 ## 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; memory reads still return the legacy rows.
-- 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. `memory_search` and `conversation_list` are likewise agent-agnostic (they return all your agents' rows for the user); only `conversation_get` enforces `agent_id` (agent ownership).
+- 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. `memory_search` and `conversation_list` are likewise agent-agnostic (they return all your agents' rows for the user); the conversation calls (`conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`) enforce `agent_id` (agent ownership), and `memory_delete_all` deletes only the passed `agent_id`'s bucket.
 - 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.

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

@@ -6,6 +6,47 @@ Every tool example below shows the correct parameters, expected response, and co
 
 ---
 
+## Retrieval
+
+### context_search
+
+Default first call for open-ended recall ("what do you know about X?"). One call queries memory, the knowledge base, and the conversation-history cache in parallel.
+
+```
+context_search(
+    query="auth migration decisions",
+    agent_id="<your agent_id>",
+    conversation_id="<session conversation id>",
+    datapack_id="<datapack UUID>")
+```
+
+Required: `query`, `conversation_id`. `datapack_id` is optional (default datapack if omitted); pass the pinned id when you have one.
+
+Response:
+
+```
+{
+  "results": {
+    "memory": [{"id": "...", "memory": "...", "score": 0.51, ...}],
+    "knowledge_base": [{"id": "...", "chunk_text": "...", "document_id": "...", "distance": 0.31, "match_type": "hybrid", ...}],
+    "conversation": {"hits": [...], "thread": [...]}
+  },
+  "token_savings": {"total_tokens": 49000, "memory": {"tokens_sent": 600, "tokens_saved": 48400}, "tokens_saved": 48400}
+}
+```
+
+- A bucket is `null` only when that source wasn't queried: `force_source` excluded it, or the server couldn't build a query vector for it.
+- An empty bucket is ambiguous: either that source found nothing relevant, or it failed. `context_search` turns a failed source into an empty list and records the error only in the trace. Before you tell the user nothing is stored about X, confirm with `memory_search` or `knowledgebase_search`, which return errors.
+- The conversation bucket is datapack-wide. It returns embedded turns from every user and agent on the datapack, and each hit carries its author's `user_id`. Don't present a hit as this user's own history.
+- `limit` bounds the memory and KB buckets only; the conversation bucket returns up to 10 hits plus a thread of whole turns.
+- The memory bucket has no similarity floor on the default path. The KB bucket drops chunks above an absolute distance cutoff, so it can be empty even when `knowledgebase_search` would return a weak best match.
+- `force_source="memory" | "knowledge_base" | "conversation"` queries only that source. `force_source="memory"` reapplies the `memory_search` similarity floor.
+- `token_savings` is an estimate for reporting. Don't base decisions on it.
+
+**Errors:** `conversation_id_required`, `invalid_force_source`, `datapack_access_denied`, and `free_tier_limit_reached` (Free tier: 1,000 lifetime calls). Treat any error as a failed search (SKILL.md operating contract 1).
+
+---
+
 ## Memory Tools
 
 **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"`.
@@ -46,13 +87,15 @@ memory_search(query="What programming language does the team use?", agent_id="ag
 
 **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.
+**Relevance floor.** `memory_search` drops results whose raw cosine similarity is below the server's `memory_search_min_score` setting (default `0.2`, tunable at runtime). A query can return 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}]}
+{"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89, "raw_similarity_score": 0.72}]}
 ```
 
+`score` is the fused hybrid rank (semantic + keyword + entity boost) used to order results; `raw_similarity_score` is the unfused cosine value. A similarity threshold like `MEMORY_SEARCH_MIN_SCORE` gates on `raw_similarity_score` when it is not null, and falls back to `score` when the raw field is absent or null.
+
 **With limit:**
 ```
 memory_search(query="user preferences", agent_id="agent", conversation_id="<uuid>", limit=5)
@@ -64,7 +107,7 @@ memory_search(query="user preferences", agent_id="agent", conversation_id="<uuid
 
 ### memory_get_all
 
-**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.
+**When to use:** See the most recent memories (about 20 rows) across every `agent_id`, plus the true `total`. It is not a complete listing and takes no paging arguments (SKILL.md operating contract 2). Use `memory_search` or `memory_get_by_id` for anything older or specific.
 
 ```
 memory_get_all(agent_id="agent", conversation_id="<uuid>")
@@ -96,11 +139,13 @@ memory_update(memory_id="mem-uuid-123", text="Updated: Team uses Go for all new
 memory_delete_by_id(memory_id="mem-uuid-123", agent_id="agent", conversation_id="<uuid>")
 ```
 
+`memory_update` and `memory_delete_by_id` return `memory_is_promoted` for a promoted memory, and `not_found` for an id that is missing or belongs to another account.
+
 ---
 
 ### memory_delete_all
 
-**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.
+**Destructive.** Deletes all memories in the passed `agent_id`'s bucket in the datapack. It does not touch other agents' rows, even though `memory_search` shows them; omitting `agent_id` deletes only the `meko_agent` bucket. Pass `run_id=<conversation_id>` to limit it to one conversation. For removing a single memory, prefer `memory_delete_by_id`.
 
 ```
 memory_delete_all(agent_id="agent", conversation_id="<uuid>")
@@ -134,9 +179,12 @@ Get exact UUIDs from the `id` field of `memory_search` / `memory_get_all` result
 
 ```
 conversation_create(agent_id="agent",
-    title="Debugging the auth middleware")
+    title="Debugging the auth middleware",
+    datapack_id="<uuid from datapack_list>")
 ```
 
+`datapack_id` is required whenever no server-side default resolves for the caller. Omitting it in that state returns `{"error": "datapack_id_required"}` and persists nothing; the same contract applies to `conversation_add_message`, `conversation_get`, `conversation_update`, and `conversation_delete`.
+
 **Response:**
 ```json
 {"id": "conv-uuid-123", "title": "Debugging the auth middleware"}
@@ -207,7 +255,7 @@ conversation_delete(conversation_id="conv-uuid-123", agent_id="agent")
 
 ## Knowledge Base Tools
 
-**KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` is the one KB tool exposed via MCP.
+**KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). MCP exposes two KB tools: `knowledgebase_search`, and `knowledgebase_delete_document` for removing a single uploaded file.
 
 See `tools-rag-workflow.md` for the decision table.
 
@@ -235,6 +283,17 @@ Populated KBs return results with chunk content and similarity scores. An empty/
 
 ---
 
+### knowledgebase_delete_document
+
+Permanently deletes ONE knowledge-base file — its chunks and metadata in one transaction, plus a best-effort delete of the stored file. Irreversible: confirm with the user before calling, and take `document_id` from `knowledgebase_search` hits — hits carry `document_id` but NOT a filename, so confirm by echoing the id and the matched chunk text (the documents list API / Meko UI is the authoritative name source). Never guess an id; non-UUID values are rejected.
+
+```
+knowledgebase_delete_document(document_id="<uuid from a search hit>",
+                              conversation_id="<session conversation id>")
+```
+
+Returns `{"document_id", "chunks_deleted", "s3_deleted"}` — if `s3_deleted` is `false`, say so: the index entries are gone but the stored file may remain. Errors include a numeric `status`: `403` means the user is not the datapack owner, a maintainer, or the file's uploader — report it, don't retry; `409` (`DOCUMENT_PROCESSING`) means the file is still being indexed — wait for indexing to finish, then retry.
+
 ## Artifact Tools
 
 ### artifact_put
@@ -322,11 +381,24 @@ For large files use the `local_path` value to read the file with normal file too
 ### datapack_create / datapack_list / datapack_describe
 
 ```
-datapack_create(name="analytics_prod")
+datapack_create(name="analytics_prod", conversation_id="<conversation id>")
 datapack_list(conversation_id="<session conversation id>")  # returns datapack_id for each datapack
-datapack_describe(datapack_id="<uuid>", include_status=True)
+datapack_describe(datapack_id="<uuid>", include_status=True, conversation_id="<conversation id>")
 ```
 
+`datapack_describe` returns these counts:
+
+| Field | Meaning |
+|---|---|
+| `memory_count` | All memories stored in the datapack |
+| `collective_memory_count` | Memories promoted to shared knowledge |
+| `learnings_count` | Memories awaiting a promotion decision |
+| `knowledge_base_file_count` | Uploaded KB documents; `null` if the status endpoint is unreachable |
+| `knowledge_chunk_count` | KB chunks across all documents (for debugging retrieval) |
+| `shared_knowledge_count` | `collective_memory_count + knowledge_base_file_count`; `null` when the file count is `null` |
+
+`knowledge_count` is a deprecated alias of `knowledge_chunk_count`. `datapack_list` doesn't compute counts; call `datapack_describe` for them.
+
 ### 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.
@@ -334,11 +406,11 @@ datapack_describe(datapack_id="<uuid>", include_status=True)
 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(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!
+datapack_update(datapack_id="<uuid>", name="renamed-datapack", conversation_id="<conversation id>")
+datapack_update(datapack_id="<uuid>", description="new description", conversation_id="<conversation id>")
+datapack_update(datapack_id="<uuid>", name="x", description="y", conversation_id="<conversation id>")
+datapack_update(datapack_id="<uuid>", conversation_search_opt_out=True, conversation_id="<conversation id>")
+datapack_delete(datapack_id="<uuid>", conversation_id="<conversation id>")  # Irreversible!
 ```
 
 ### Agent and knowledge-base management (NOT MCP — control-plane only)
@@ -348,4 +420,4 @@ Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/li
 - REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (agents), `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases` (KB sources).
 - 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`.
+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`, and can remove a single uploaded file with `knowledgebase_delete_document` — see `tools-rag-workflow.md`.

package/assets/skills/meko-mcp-tools/references/tools-datapack-workflow.md

@@ -50,7 +50,7 @@ Delete child resources first (agents and KB sources via the control plane), then
 ```
 # 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(datapack_id="dp-uuid-123")  # MCP-exposed, destructive, irreversible
+datapack_delete(datapack_id="dp-uuid-123", conversation_id="<conversation id>")  # MCP-exposed, destructive, irreversible
 ```
 
 ## Common mistake: forgetting datapack_id on memory tools

package/assets/skills/meko-mcp-tools/references/tools-known-limitations.md

@@ -12,6 +12,10 @@ These are current limitations of the Meko MCP tools. Know them upfront to avoid
 | Standard | 5,000 | 5,000 | 30,000 |
 | Pro / Enterprise | uncapped | uncapped | uncapped |
 
+The Free tier also caps `context_search` and `conversation_add_message` at 1,000 calls each. Embedding turns into the conversation-search cache has its own cap (2,000 turns on Free, 10,000 on Pro). When that cap is reached, `conversation_add_message` still stores the turn and reports `conversation_search_skipped: "quota_exceeded"`; the turn just won't appear in `context_search`'s conversation bucket.
+
+A quota error can arrive with HTTP 403. It is not an authentication failure; don't reconfigure credentials because of it.
+
 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.
@@ -24,9 +28,19 @@ One call returns roughly the **20 most recent rows**; the response's `total` rep
 
 ## 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.
+`memory_search(run_id=<conversation_id>)` and `memory_delete_all(run_id=<conversation_id>)` 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.
+
+`memory_get_all` accepts `run_id` but ignores it, and `conversation_list` has no `run_id`.
+
+## memory_delete_all is agent-scoped; memory reads are not
+
+`memory_search` and `memory_get_all` return every agent's rows for the user. `memory_delete_all` deletes only rows in the `agent_id` you pass, and an omitted `agent_id` means the `meko_agent` bucket. A `memory_search(run_id=X)` preview can therefore list rows that `memory_delete_all(run_id=X)` leaves in place. To clear rows written by several agents, delete them by id with `memory_delete_by_id`, or call `memory_delete_all` once per `agent_id` shown in the preview.
 
-## No delete tools for RAG artifacts
+## Promoted memories are read-only through MCP
+
+`memory_update` and `memory_delete_by_id` return `memory_is_promoted` for a memory that has been promoted to shared knowledge. Edit or remove promoted content in the Cloud UI Learnings tab.
+
+## No MCP tools for index / source / pipeline lifecycle
 
 There are no MCP tools to:
 - Delete a vector index
@@ -34,7 +48,7 @@ There are no MCP tools to:
 - Clear stuck work queue entries
 - Reset a failed pipeline
 
-KB-source deletion happens via the Meko control plane (REST: `DELETE /datapacks/:datapack_id/knowledge-bases`, or the UI), which removes the registration from the Meko API — but does **not** touch the actual `dist_rag` index, source records, or vector data in the datapack's database.
+The one exception is a single uploaded **file**: `knowledgebase_delete_document` removes that file's chunks and metadata. KB-**source** deletion (the registered source, not one file) happens via the Meko control plane (REST: `DELETE /datapacks/:datapack_id/knowledge-bases`, or the UI): it unregisters the source from the Meko API but does **not** touch the actual `dist_rag` index, source records, or vector data in the datapack's database.
 
 **Workaround:** For stuck or failed indexes, create a new index with a different name. Stale indexes remain in the database until manually cleaned up by an admin.
 
@@ -70,8 +84,17 @@ It works **poorly** for:
 
 Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
 
-## No semantic search over conversation content
+## Conversation search covers embedded turns only
+
+`context_search` searches past conversation turns by meaning in its `conversation` bucket. Only turns embedded into the conversation-search cache are searchable. Turns are embedded by default, except when:
+
+- the datapack opted out with `datapack_update(datapack_id=..., conversation_search_opt_out=True, conversation_id=...)`;
+- the account hit the embedding quota (`conversation_search_skipped: "quota_exceeded"`); or
+- the turn was too short to carry content (the server skips trivial turns); or
+- the turn was stored before conversation search was enabled.
+
+To find a conversation by other attributes, browse with `conversation_list` and inspect candidates 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`.
+## Very long conversations can't be read back
 
-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.
+When a conversation's trace grows too large for Langfuse, `conversation_get` and `conversation_update` return `{"error": "not_found", "detail": "Conversation <id> not found"}` or time out for that conversation, even though `conversation_add_message` and `conversation_delete` still work. Servers without the MEKO-714 fix instead return `not_found` from `conversation_add_message` on these conversations. If read-back or a write fails with `not_found` on a long conversation that you know exists, report the failure as a server-side limit on that conversation. Don't recreate the conversation under the same id or replay its messages; that makes the trace larger.

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

@@ -26,22 +26,26 @@ memory_search(query="What plan does Alice have?", agent_id="support_bot")
 Conversations are backed by Langfuse sessions and traces. They preserve full structure: who said what, in what order, with what reasoning.
 
 ```
-conversation_create(agent_id="support_bot", title="Pricing discussion")
+conversation_create(agent_id="support_bot", title="Pricing discussion",
+    datapack_id="<uuid from datapack_list>")
 -- Returns: {"id": "conv-uuid-here"}
 
 conversation_add_message(conversation_id="conv-uuid-here", agent_id="support_bot",
+    datapack_id="<uuid from datapack_list>",
     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.")
 ```
 
+`datapack_id` is required for both calls whenever no server-side default resolves for the caller. Omitting it in that state returns `{"error": "datapack_id_required"}` and persists nothing.
+
 ## Decision Matrix
 
 | Signal | Tool |
 |--------|------|
 | "remember that...", "note that...", "keep in mind..." | `memory_add` |
 | "store this conversation", "save this chat" | `conversation_create` + `conversation_add_message` |
-| "what do you know about X?", "recall..." | `memory_search` |
+| "what do you know about X?", "recall..." | `context_search` |
 | "show me our past conversation about..." | `conversation_list` + `conversation_get` |
 | "the user prefers...", "their budget is..." | `memory_add` |
 | "save my query and your response" | `conversation_add_message` |
@@ -89,7 +93,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: `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.
+Call `context_search`. One call returns your personal memories (every agent, no per-agent fan-out), team-shared knowledge, and matching past-conversation turns from anyone on the datapack. If the memory or KB bucket is empty, confirm with `memory_search` or `knowledgebase_search` before saying nothing is there, because `context_search` returns an empty list for a failed source. 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
 
@@ -112,7 +116,7 @@ On Claude Code, do **not** proactively `memory_add` facts the user states — ca
 
 ## Automatic Conversation Capture
 
-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`).
+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`). Skill bodies, background-task notifications, and subagent reports that Claude Code writes into the transcript go to `reasoning` of the turn they belong to, never to `input`. A typed `/skill args` is captured with that command as its `input`.
 
 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.