@yugabytedb/meko-mcp 2.2.0 → 2.3.0

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

@@ -1,6 +1,6 @@
 # Complete Tool Catalog and Decision Tree
 
-**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.
+**25 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Retrieval (1), Memory (8), Conversation (6), Knowledge Base (2), 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
 
@@ -13,10 +13,11 @@ Before starting a session, verify that the Meko MCP tools are working:
 
 ```
 User wants to...
+├── Ask "what do you know about X?" --------> context_search (read; memory + KB + past conversations in one call)
 ├── 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)
+├── Delete ONE knowledge-base file? --------> knowledgebase_delete_document (destructive — confirm with the user first)
 ├── Store or recall information?
 │   ├── Store a fact/preference/entity? -----------> memory_add (write)
 │   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
@@ -30,47 +31,56 @@ User wants to...
     └── CRUD datapack? --------------------> datapack_create/list/describe/update/delete
 ```
 
-Agent / knowledge-base lifecycle is managed **outside** the MCP surface — typically in the Meko control-plane UI — and is not exposed as tools here.
+Agent lifecycle and KB **ingestion / index lifecycle** (adding sources, uploads, re-indexing) are managed outside the MCP surface — typically in the Meko control-plane UI. Deleting a single KB file IS exposed here (`knowledgebase_delete_document`).
 
-## Knowledge Base Tools (1)
+## Retrieval Tools (1)
 
 | Tool | Purpose |
 |------|---------|
-| `knowledgebase_search(query, agent_id, conversation_id, datapack_id, limit=10)` | Semantic search across KB chunks. `datapack_id` is REQUIRED (no default). |
+| `context_search(query, conversation_id, agent_id=None, datapack_id=None, limit=10, force_source="auto")` | Default first call for open-ended recall. Queries memory, the knowledge base, and the conversation-history cache in parallel and returns each source in its own bucket: `{"results": {"memory": [...], "knowledge_base": [...], "conversation": {"hits": [...], "thread": [...]}}, "token_savings": {...}}`. 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. `force_source` is `"auto"` (all three), `"memory"`, `"knowledge_base"`, or `"conversation"`; any other value returns `invalid_force_source`. `limit` bounds the memory and KB buckets only; the conversation bucket returns up to 10 hits plus a thread of whole turns. 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. |
+
+## Knowledge Base Tools (2)
+
+| Tool | Purpose |
+|------|---------|
+| `knowledgebase_search(query, conversation_id, datapack_id, agent_id=None, limit=10)` | Hybrid (semantic + keyword) search across KB chunks and promoted memories. `datapack_id` is REQUIRED (no default). Each hit has `id`, `chunk_text`, `document_id`, `metadata_filters`, `distance`, and `match_type` (`semantic`, `keyword`, or `hybrid`). |
+| `knowledgebase_delete_document(document_id, conversation_id, datapack_id="")` | Permanently delete ONE KB file (chunks + metadata; stored-file delete is best-effort — check `s3_deleted`). Irreversible: confirm with the user first. `document_id` comes from `knowledgebase_search` hits (no filename in hits — echo the id + chunk text). Owner/maintainer/uploader only (status 403 otherwise); status 409 while still indexing — wait and retry. |
 
 ## Memory Tools (8)
 
 | 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)` | 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_add(text, conversation_id, agent_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | Store fact/preference/entity as long-term memory |
+| `memory_search(query, conversation_id, agent_id=None, limit=10, datapack_id=None, run_id=None)` | Hybrid search across memories (semantic + keyword + entity boost). Drops rows below a server-configured similarity floor (default 0.2), so a weak query can return an empty list. `conversation_id` is required but only nests the trace. It must be a 32-hex id: `""` currently fails (MEKO-707), so pass a freshly generated one if you have no conversation yet. `run_id` filters to one conversation's memories. |
+| `memory_get_by_id(memory_id, conversation_id, agent_id=None, datapack_id=None)` | Direct pgvector row lookup by UUID. Preferred over `memory_search` for exact-id verification. Returns `not_found` for a missing id and for an id that belongs to another account. |
+| `memory_get_all(conversation_id, agent_id=None, run_id=None, datapack_id=None, promoted=False)` | Recent window (about 20 rows) of the user's memories across every agent, plus the true `total`. Not a complete listing. `promoted=True` returns the recent window of promoted memories instead. `run_id` is ignored. |
+| `memory_update(memory_id, text, conversation_id, agent_id=None, datapack_id=None)` | Overwrite memory text. Returns `memory_is_promoted` for a promoted memory (edit those in the Cloud UI Learnings tab). |
+| `memory_delete_by_id(memory_id, conversation_id, agent_id=None, datapack_id=None)` | Delete a single memory. Returns `memory_is_promoted` for a promoted memory. |
+| `memory_delete_all(conversation_id, agent_id=None, run_id=None, datapack_id=None)` | Delete all memories in the **passed `agent_id`'s bucket** (destructive). Unlike reads, this is agent-scoped: omitting `agent_id` deletes only the `meko_agent` bucket. `run_id` narrows it to one conversation; a malformed value returns `invalid_run_id`. |
 | `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)
 
 | Tool | Purpose |
 |------|---------|
-| `conversation_create(agent_id, run_id=None, title=None, metadata=None, session_id="")` | Create conversation container (Langfuse session) |
-| `conversation_add_message(conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None)` | Add a message turn (Langfuse trace) |
-| `conversation_get(conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | Retrieve conversation, optionally with messages |
+| `conversation_create(agent_id=None, run_id=None, title=None, metadata=None, session_id="", datapack_id=None)` | Create conversation container (Langfuse session) |
+| `conversation_add_message(conversation_id, input, output, agent_id=None, reasoning=None, metadata=None, seed=None, datapack_id=None, plan=None)` | Add a message turn (Langfuse trace). `output` is required. The response may include `extracted_memories` and, when the turn wasn't embedded for conversation search, `conversation_search_skipped` (`quota_exceeded` or `datapack_opted_out`). |
+| `conversation_get(conversation_id, agent_id=None, include_messages=False, limit=100, offset=0, datapack_id=None)` | Retrieve conversation, optionally with messages |
 | `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List the user's conversations within a datapack (`agent_id` does not filter — trace attribution only). `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_list` to look it up. `conversation_id` optional (omit for browse). |
-| `conversation_update(conversation_id, agent_id, title=None, metadata=None)` | Update title or metadata |
-| `conversation_delete(conversation_id, agent_id)` | Delete entire conversation (destructive) |
+| `conversation_update(conversation_id, agent_id=None, title=None, metadata=None, datapack_id=None)` | Update title or metadata |
+| `conversation_delete(conversation_id, agent_id=None, datapack_id=None)` | Delete entire conversation (destructive) |
 
 ## Datapack Management Tools (5)
 
 | Tool | Purpose |
 |------|---------|
-| `datapack_create(name)` | Create new datapack |
+| `datapack_create(name, conversation_id)` | Create new datapack |
 | `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, 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) |
+| `datapack_describe(conversation_id, datapack_id="", include_status=False)` | Describe a datapack by UUID (default datapack if omitted). Returns `memory_count`, `collective_memory_count` (promoted), `learnings_count` (awaiting a promotion decision), `knowledge_base_file_count`, `knowledge_chunk_count`, and `shared_knowledge_count`. `knowledge_base_file_count` and `shared_knowledge_count` are `null` when the status endpoint is unreachable; `knowledge_count` is a deprecated alias of `knowledge_chunk_count`. |
+| `datapack_update(datapack_id, conversation_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, conversation_id)` | Delete datapack by UUID (irreversible) |
+
+All five datapack tools reject an empty `conversation_id` with `conversation_id_required`.
 
 ## Artifact Tools (2)
 
@@ -104,4 +114,4 @@ For knowledge-base content on Cloud, the canonical path is **UI upload**: Datapa
 
 ## Common Parameter Patterns
 
-Memory and KB tools accept optional `datapack_id` to target a specific datapack. `agent_id` attributes writes and is enforced only on `conversation_get` (agent-owned — a wrong value returns `agent_id_mismatch`); it does **not** filter memory reads (`memory_search`/`memory_get_all`) or `conversation_list`, which return all your agents' rows for the user. See `tools-agent-id-conventions.md`.
+Memory and KB tools accept optional `datapack_id` to target a specific datapack. A `datapack_id` your account can't access returns `datapack_access_denied`. `agent_id` attributes writes. Conversations are agent-owned: `conversation_get`, `conversation_add_message`, `conversation_update`, and `conversation_delete` return `agent_id_mismatch` for any value other than the creating agent's. `agent_id` does **not** filter memory reads (`memory_search`/`memory_get_all`) or `conversation_list`, which return all your agents' rows for the user. `memory_delete_all` is the exception on the memory side: it deletes only the passed `agent_id`'s bucket. See `tools-agent-id-conventions.md`.

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

@@ -1,6 +1,7 @@
 # Knowledge Base / RAG workflow
 
-`knowledgebase_search` is the only KB tool exposed via MCP. Index
+MCP exposes two KB tools: `knowledgebase_search` (retrieval) and
+`knowledgebase_delete_document` (remove ONE uploaded file). Index
 creation and ingestion happen out of band — through the **Meko UI**
 (`cloud.mekodata.ai`).
 
@@ -8,9 +9,10 @@ creation and ingestion happen out of band — through the **Meko UI**
 
 | Situation | Use this | Why |
 |---|---|---|
-| Search an existing KB | `knowledgebase_search` | The one KB tool exposed via MCP |
+| Search an existing KB | `knowledgebase_search` | Retrieval over the indexed chunks |
 | Add documents to a KB | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). No MCP equivalent |
-| Anything else (list / delete / rename / re-index) | **UI** | No MCP tools for KB lifecycle |
+| Delete ONE uploaded file | `knowledgebase_delete_document` | Destructive; `document_id` from search hits; confirm with the user first |
+| Anything else (list / rename / re-index / source lifecycle) | **UI** | No MCP tools for the rest of KB lifecycle |
 
 ## knowledgebase_search — the one you'll actually call
 
@@ -23,7 +25,7 @@ knowledgebase_search(
     limit=10)
 ```
 
-Required: `query`, `agent_id`, `conversation_id`, `datapack_id`.
+Required: `query`, `conversation_id`, `datapack_id`.
 Unlike the memory tools, `datapack_id` has no default here — you must
 pass it explicitly. `agent_id` is **ignored for filtering** on this
 tool (KB results are team-shared on the datapack), but you still pass
@@ -37,10 +39,12 @@ Populated KB:
 {
   "results": [
     {
-      "content": "<chunk text>",
-      "similarity": 0.87,
-      "source_uri": "<original source URI>",
-      "document_name": "<file key>",
+      "id": "<chunk id>",
+      "chunk_text": "<chunk text>",
+      "document_id": "<KB document id; pass to knowledgebase_delete_document>",
+      "metadata_filters": {},
+      "distance": 0.31,
+      "match_type": "semantic" | "keyword" | "hybrid",
       ...
     },
     ...
@@ -49,6 +53,8 @@ Populated KB:
 }
 ```
 
+Lower `distance` is closer. Promoted memories appear as hits whose `metadata_filters.source` is `"memory"`. Hits carry no filename, so show the user the `document_id` and chunk text when they need to identify a file.
+
 Empty or nonexistent KB: `{"results": [], "count": 0}` (no error,
 just an empty array).
 

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** (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.
+4. **Use your session's `agent_id` consistently on writes** (the SessionStart-injected value), and on every conversation call (`conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`). 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,22 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 ---
 
+## Connection errors: `[Errno 111] Connection refused`
+
+**Affects:** any tool, intermittently. Reports show `memory_add`, `conversation_create`, `memory_search`, and `context_search` failing this way while identical calls succeed minutes later.
+
+**What it means:** the request reached no listening server, usually a server instance that was restarting or scaling. It is not a timeout and not a rejected argument.
+
+**What to do:** wait a few seconds and retry once. Retry `conversation_add_message` only with a `seed`, and never retry `conversation_create` (see the table below). If the retry also fails, report the failure. For a write, tell the user it was not saved; don't let a failed write pass silently.
+
+---
+
+## `memory_search` hangs or times out
+
+`memory_search` can stall for minutes under backend load while other tools respond. Don't raise the client timeout; that only makes the stall longer. Retry once. If it stalls again, report that the search failed, and if the user needs an answer now, try `context_search` or `memory_get_by_id` for a known id. `memory_get_all` only returns a recent window, so it can't replace a search.
+
+---
+
 ## 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."
@@ -47,6 +63,34 @@ Bursts of requests on one token return:
 
 ---
 
+## Quota errors that look like auth errors
+
+`free_tier_limit_reached` can arrive with HTTP 403, and automatic capture that hits a cap shows up as capture failing with 403. Read the error code, not the status. A quota error means the account reached a lifetime cap (see `tools-known-limitations.md`). Don't rotate keys or reinstall. Tell the user which tool hit the cap and that upgrading the plan lifts it.
+
+---
+
+## Datapack and ownership errors
+
+| Error | Meaning | What to do |
+|---|---|---|
+| `datapack_access_denied` | The `datapack_id` isn't a UUID, or it isn't owned by or shared with your account. The access check also fails closed on a transient server database error. | Retry once. If it repeats, stop; don't switch to another datapack. If the id came from a pin, ask the user to re-pin with the select-datapack skill. |
+| `datapack_id_required` | The call couldn't resolve a datapack. Conversation reads and writes (including `conversation_list`), `datapack_describe`, and `knowledgebase_delete_document` return it. | Pass the pinned `datapack_id`. Don't drop the parameter to make the call pass. |
+| `not_found` from `memory_get_by_id`, `memory_update`, or `memory_delete_by_id` | The memory doesn't exist **or** belongs to another account. The server returns the same error for both on purpose. | Check the id came from a search in this datapack. |
+| `memory_is_promoted` | The memory was promoted to shared knowledge and is read-only through MCP. | Point the user at the Cloud UI Learnings tab. |
+| `invalid_run_id` | `memory_delete_all` got a `run_id` that isn't a conversation id. | Pass the conversation UUID, or omit `run_id`. |
+| `embedder_error` from `knowledgebase_search` | The server couldn't resolve the embedding setup for this datapack's index. | Report it; retrying won't help. |
+| `invalid_force_source` from `context_search` | `force_source` isn't `auto`, `memory`, `knowledge_base`, or `conversation`. | Omit `force_source`. |
+
+---
+
+## Conversation writes fail right after `conversation_create`
+
+`conversation_add_message` has intermittently returned `not_found`, or `agent_id_mismatch` naming agent `'None'`, seconds after `conversation_create` returned that id. It shows up most with several parallel subagents writing to one conversation. Retry once with the same `seed` after a few seconds. If it still fails, don't create a new conversation for the same work: save the durable findings with `memory_add` and tell the user the transcript is incomplete.
+
+On a long conversation that has worked before, `not_found` can instead mean the trace grew too large to load. See `tools-known-limitations.md`.
+
+---
+
 ## 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

@@ -4,7 +4,7 @@ On Cloud Meko, every write and every personal read carries a `user_id` that iden
 
 ## The default behavior: automatic user_id from cognito
 
-On Cloud, the server resolves your `user_id` automatically from the cognito account attached to your MCP session (the API key or OAuth token). You do not need to pass `user_id` on every call — omit it and the server fills in the account owner's id.
+On Cloud, the server resolves your `user_id` from the cognito account attached to your MCP session (the API key or OAuth token).
 
 This is the common case for Claude Code / Claude Desktop / Cursor:
 
@@ -18,43 +18,11 @@ memory_add(
 
 A second person signing into the same Cloud datapack with their own account gets their own `user_id` automatically — they can never read your un-promoted memories via MCP, and you can never read theirs.
 
-## When to pass user_id explicitly
+## No tool takes a user_id argument
 
-Explicit `user_id` is an **optional sub-scope** for agents that serve multiple end-users behind a single Meko account — think a support bot or team assistant where one cognito account is the "operator" but the agent is acting on behalf of different people. Each end-user's memories live in a separate partition under the same cognito account.
+`user_id` always comes from the credentials on your MCP session. No Meko MCP tool accepts a `user_id` (or `app_id`) argument, and the server rejects unknown arguments, so adding one makes the call fail.
 
-```
-# Serving Alice
-memory_add(
-           text="Alice prefers email communication. Has Pro plan.",
-           agent_id="support-bot",
-           user_id="alice_123",
-           conversation_id="<conv>")
-
-# Serving Bob — completely separate partition, same cognito account
-memory_add(
-           text="Bob prefers Slack. On Enterprise plan.",
-           agent_id="support-bot",
-           user_id="bob_456",
-           conversation_id="<conv>")
-
-# Search only returns Alice's memories
-memory_search(
-              query="communication preference",
-              agent_id="support-bot",
-              user_id="alice_123",
-              conversation_id="<conv>")
-```
-
-This is rarely relevant for Claude Code / Desktop / Cursor — those are single-human clients, and the automatic cognito user_id is the right behavior. It matters for autonomous multi-user agents built on top of the Meko API.
-
-## Gotcha — mixing scoped and unscoped calls
-
-If you pass `user_id="alice"` on writes but omit it on searches, the search falls back to the auto cognito user_id and **will not find** Alice's memories. They're in a different partition. Pick a convention for a given agent and stick to it:
-
-- Claude Code / Desktop / Cursor: omit `user_id`, rely on the auto cognito value.
-- Multi-user autonomous agents: pass `user_id` consistently on every write and read.
-
-Mixing creates invisible data.
+An agent that serves several end users behind one Meko account can't partition memory per end user with `user_id`. `agent_id` doesn't work either: it attributes rows but doesn't filter reads. Give each end user or tenant that must not see the others' content a separate datapack, and pass that `datapack_id` on every call.
 
 ## How user_id relates to agent_id and the Shared Knowledge split
 
@@ -62,7 +30,7 @@ Mixing creates invisible data.
 |---|---|---|
 | Personal memories (`memory_add`, `memory_search`, `memory_get_all`) | `(datapack_id, user_id)` | Enforced on every read. `agent_id` is not applied — one user sees all their own memories across every agent, but cannot see another user's un-promoted memories. |
 | Conversation listing (`conversation_list`) | `(datapack_id, user_id)` | Enforced. `agent_id` is not applied — you see all your own conversations across every agent. |
-| Conversation fetch (`conversation_get`) | `(datapack_id, user_id, agent_id)` | Enforced. Agent-owned: pass the creating `agent_id` or you get `agent_id_mismatch`. Cross-user reads require promotion. |
+| Conversation fetch and writes (`conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`) | `(datapack_id, user_id, agent_id)` | Enforced. Agent-owned: pass the creating `agent_id` or you get `agent_id_mismatch`. Cross-user reads require promotion. |
 | Team Shared Knowledge (`knowledgebase_search`) | `(datapack_id)` only | **Not used** — `user_id` is stripped when a memory is promoted to Knowledge. All team members on the datapack see the same Shared Knowledge. |
 
 Personal content crosses the `user_id` boundary through `memory_promote` or the Cloud UI's "Promote to Knowledge" action. The MCP path requires exact memory UUIDs, explicit user confirmation, and an owner/maintainer role; it moves the records into team-visible Shared Knowledge and evicts the private copies.
@@ -72,9 +40,8 @@ Personal content crosses the `user_id` boundary through `memory_promote` or the
 | Parameter | Identifies | Typical value | Required? |
 |---|---|---|---|
 | `datapack_id` | Which datapack's DB/Langfuse project | `"c038ba7b-..."` (UUID) | Optional on most tools (default datapack if omitted). **Required** on `knowledgebase_search`. |
-| `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) |
+| `user_id` | The cognito account | Resolved from your credentials | Not a tool argument |
 | `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` | 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.8.0"
+  version: "2.9.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 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.
+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 25 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.
 
@@ -40,11 +40,13 @@ On the first user turn in any session, before answering substantive questions:
 1. **Resolve the active datapack pin first — before creating the conversation.** A conversation cannot move between datapacks once created, so you must know the pinned datapack *before* `conversation_create`, or capture lands in the wrong workspace. Call:
    ```
    memory_search(query="meko_active_datapack",
-                 agent_id="claude_desktop", conversation_id="", limit=1)
+                 agent_id="claude_desktop",
+                 conversation_id="<fresh 32-hex id>", limit=1)
    ```
+   `<fresh 32-hex id>` is a newly generated 32-character lowercase hex string, such as a UUID with the hyphens removed. You don't have a conversation yet, and `""` fails on production `memory_search` (MEKO-707).
    If a pin row comes back, extract the UUID after `meko_active_datapack=` — call it `<PIN>` — and pass `datapack_id="<PIN>"` to **every** Meko call for the rest of the session (`conversation_create`, `memory_search`, `conversation_add_message`, etc.). If no pin is found, omit `datapack_id` everywhere and let the server resolve the default. (The `meko-select-datapack-desktop` skill is what writes this pin; you honor it here whether or not that skill ran this session.)
 2. **Call `conversation_create`** (`agent_id="claude_desktop"`, and `datapack_id="<PIN>"` if a pin was found) once and keep the returned `conversation_id` for the whole session. You need it to post turns (per-turn capture, above) and for memory calls.
-3. **Call `memory_search`** with `agent_id="claude_desktop"`, the `conversation_id` from step 2, `datapack_id="<PIN>"` if pinned, and a query derived from the user's topic. One search returns this user's memories across every agent, including the `meko_agent` common bucket; `agent_id` attributes the trace but does not filter memory results.
+3. **Call `context_search`** with `agent_id="claude_desktop"`, the `conversation_id` from step 2, `datapack_id="<PIN>"` if pinned, and a query derived from the user's topic. One call returns separate memory, knowledge-base, and past-conversation buckets. The memory bucket covers this user's memories across every agent, including the `meko_agent` common bucket; `agent_id` doesn't filter it.
 4. Incorporate the recalled facts into your reply. Don't re-ask things you've been told before.
 
 Recall and capture are routine parts of answering — the user has set Meko up as their memory layer, so you don't need a per-call permission prompt for them. Do briefly say what you did ("checked your Meko memory", "saved that to your Meko memory") — a short disclosure, not a silent background action and not a big announcement.
@@ -57,7 +59,7 @@ Recall and capture are routine parts of answering — the user has set Meko up a
 
 **Read scoping:**
 - `memory_search` / `memory_get_all` — scoped to `(datapack_id, user_id)`. `agent_id` does not filter results, so one call returns this user's memories across every agent.
-- `conversation_list` — also returns this user's conversations across agents. `conversation_get` is agent-owned and requires the exact `agent_id` that created the conversation.
+- `conversation_list` — also returns this user's conversations across agents. `conversation_get`, `conversation_add_message`, `conversation_update`, and `conversation_delete` are agent-owned and require the exact `agent_id` that created the conversation.
 - `knowledgebase_search` — scoped to `datapack_id` only. `agent_id` on the request is ignored. Returns the team's Shared Knowledge — uploaded documents plus promoted memories.
 
 Some pre-existing rows use the older constant `agent_id="agent"` or ad-hoc shapes (e.g. `claude-desktop` with a hyphen). They remain readable; the stored value is still shown as provenance in the UI. See `tools-agent-id-conventions.md` for the full model.
@@ -76,7 +78,7 @@ conversation_add_message(conversation_id="<id>",
     reasoning="<why you answered as you did; tool calls if any>")
 ```
 
-Post the turn verbatim — do not summarize. The call is cheap (queued, ~0.1s) and returns immediately.
+Post the turn verbatim — do not summarize.
 
 The failure mode to avoid: answering the user and moving on **without posting the turn**. If you don't post it, nothing is captured and nothing is extracted — a turn later there's no record the exchange happened. Treat `conversation_add_message` as part of completing a substantive turn: once you've written your reply, post the turn (and note you did) before the turn is done. This is transparent capture into the user's own memory store, so there's no reason to skip it — but if the content is sensitive or the user asked you not to store it, skip and say so.
 
@@ -118,10 +120,10 @@ Meko turns your volatile context window into persistent, shareable knowledge:
 **Meko is the memory store — never write memories to local files, markdown notes, or any file-based memory system.** Meko's memory is persistent across all agents, sessions, and team members; local files are not.
 
 - To remember what the user says → **post the turn with `conversation_add_message`** (the server extracts memories from it), NOT write to a local file.
-- To recall → call `memory_search` on the MCP server, NOT read local files.
+- To recall → call `context_search` on the MCP server (or `memory_search` for memory alone), NOT read local files.
 - For the narrow explicit-save cases → `memory_add` (see "When to also call memory_add").
 
-If a Meko call fails, you may fall back to local storage and tell the user — but Meko is always the first choice.
+If a Meko call fails, tell the user the save or recall failed and include the error. Don't quietly write a local file instead; offer one only if the user wants a local copy.
 
 ## Core principle: capture the turn, don't hand-curate memory
 
@@ -140,7 +142,7 @@ Your job is not to decide fact-by-fact what to `memory_add`. It's to **post ever
 | User corrects or negates a prior fact | Post the turn (the new fact is extracted). Extraction is **additive**, so if the stale fact must not survive, `memory_search` for it and `memory_update` / `memory_delete_by_id`. |
 | User explicitly says "remember this" | `memory_add` (verbatim), in addition to posting the turn. |
 | A durable fact lives only in your output or a tool result | `memory_add`. Extraction reads the user side of the turn, so it won't capture these. |
-| User asks "what do you know about X?" | Two-call sweep: one `memory_search(agent_id="claude_desktop")` covers this user's memories across every agent; `knowledgebase_search(datapack_id=<X>)` covers team-shared knowledge. |
+| User asks "what do you know about X?" | `context_search(agent_id="claude_desktop")`. 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 specific private memories with the team | Follow the `memory_promote` confirmation workflow below. Never promote based on a fuzzy search result or implied consent. |
 | 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. |
@@ -164,6 +166,22 @@ conversation_create(agent_id="claude_desktop",
 - **Use seeds** for dedup: `seed="<conversation_id>:claude-desktop:<sequential_number>"`.
 - Don't also `memory_add` the same fact — the server extracts memories from the posted turn. `memory_add` is only for the three exception cases above.
 
+### 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 this session's conversation fail even though it 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 created at the start of the session, accept the error and keep working:
+
+- Don't retry the call, create a replacement conversation, or re-post earlier turns. Each re-post makes the trace larger.
+- If `conversation_add_message` still succeeds, keep posting turns and skip only the read-back.
+- If `conversation_add_message` fails with `not_found`, stop posting turns for this session. Save durable facts with `memory_add` instead, and tell the user once that Meko can't take more turns in this conversation because it's too large.
+- Keep using `context_search`, the `memory_*` tools, and `knowledgebase_search`. They don't load the conversation trace.
+
+A `not_found` right after `conversation_create` has other causes; see `tools-troubleshooting.md`.
+
 ## Calling tools correctly on the first attempt
 
 **Use only the required parameters. Do not guess optional parameters.**
@@ -179,6 +197,24 @@ memory_add(
 ```
 Required parameters: `text`, `agent_id`, `conversation_id`. On **writes**, `conversation_id` must be a real UUID from `conversation_create` — writes attached to a nil/empty conversation are orphaned in Langfuse traces. Empty / missing `agent_id` is NOT rejected — the server quietly falls back to the `meko_agent` common bucket. Pass `agent_id="claude_desktop"` explicitly so this client's writes stay in the right bucket and don't pollute the cross-project pool.
 
+### context_search: default first call for recall
+```
+context_search(
+               query="auth migration decisions",
+               agent_id="claude_desktop",
+               conversation_id="<id from conversation_create>",
+               datapack_id="<PIN, if pinned>")
+```
+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.
+- 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 here, so discount weak rows against the other buckets.
+- Use `memory_search` for the pin lookup and for `run_id` filtering, and `knowledgebase_search` when you need exact `document_id` values.
+
 ### memory_search — correct call pattern
 ```
 memory_search(
@@ -186,14 +222,14 @@ memory_search(
               agent_id="claude_desktop",
               conversation_id="<id from conversation_create>")
 ```
-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; passing `""` is accepted and means "don't nest under any trace." For conversation-scoped filtering use the separate `run_id` parameter.
+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. 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. For conversation-scoped filtering use the separate `run_id` parameter.
 
 `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.** `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:
+**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.
 
 - **`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.
-- **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.
+- **Results below a server-configured similarity floor (default 0.2) are dropped.** An empty `results` list can mean "only weak matches", not "nothing stored". Some older rows may carry a `graph_nodes` / `graph_edges` block in `metadata`; ignore it.
 
 ### knowledgebase_search — correct call pattern
 ```
@@ -204,7 +240,7 @@ knowledgebase_search(
                      datapack_id="<datapack UUID>",
                      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.
 
 ### memory_promote — explicit confirmation required
 
@@ -222,20 +258,20 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 ### Critical parameter rules
 
-- **agent_id**: `"claude_desktop"` for this client's project-less writes and trace attribution. Use `"meko_agent"` when writing genuinely cross-project facts such as user identity. Empty/missing values on writes route to `meko_agent`. The value does not filter `memory_search`, `memory_get_all`, `conversation_list`, or `knowledgebase_search`; `conversation_get` is the read that requires the creating agent's exact value. See `tools-agent-id-conventions.md`.
-- **conversation_id**: Behavior varies by tool. On write tools (`memory_add`, `conversation_add_message`) pass a real UUID from `conversation_create` — a nil/empty value orphans the Langfuse trace. On `memory_search` it's used only for trace nesting (not for filtering), 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 — only a real UUID or an intentionally empty string where the tool allows it.
+- **agent_id**: `"claude_desktop"` for this client's project-less writes and trace attribution. Use `"meko_agent"` when writing genuinely cross-project facts such as user identity. Empty/missing values on writes route to `meko_agent`. The value does not filter `memory_search`, `memory_get_all`, `conversation_list`, or `knowledgebase_search`. The conversation calls (`conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`) require the creating agent's exact value, and `memory_delete_all` deletes only the passed value's bucket. See `tools-agent-id-conventions.md`.
+- **conversation_id**: Behavior varies by tool. On write tools (`memory_add`, `conversation_add_message`) pass a real UUID from `conversation_create` — a nil/empty value orphans the Langfuse trace. On read tools it's used only for trace nesting (not for filtering), 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 values. Before `conversation_create` (the first-turn pin lookup), use a freshly generated 32-hex id.
 - **When in doubt about optional parameters, omit them.** The server has sensible defaults.
 
 ## Key concepts
 
-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`.
+1. **25 tools in 7 groups** (all available in production): Retrieval (1: `context_search`), Memory (8 — including `memory_promote`), Conversation (6), Knowledge Base (2 — `knowledgebase_search`, `knowledgebase_delete_document`), 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.
 5. **conversation_id IS the Langfuse trace ID**: every MCP tool call inside a conversation becomes a span under that trace. Observable in the Meko UI's Observe hub. See `tools-memory-vs-conversation.md`.
 6. **Adding documents to the team knowledge base is UI-only on Cloud today**: user uploads files via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each). The MCP ingestion tools are not available on Cloud. See `tools-rag-workflow.md`.
 7. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
-8. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly.
+8. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly. On the Free tier, `conversation_add_message` and `context_search` are each capped at 1,000 lifetime calls, and `memory_search` and `knowledgebase_search` at 1,000. Per-turn capture draws down the `conversation_add_message` cap, so on Free skip trivial turns. When a call returns `free_tier_limit_reached`, report it and stop calling that tool; it can arrive as HTTP 403 but isn't an authentication problem.
 9. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
 10. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks.
 
@@ -243,7 +279,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 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-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-->24<!--/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-->25<!--/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 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-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

@@ -42,7 +42,7 @@ Empirically verified 2026-07-23 on Cloud prod: memories written under two distin
 
 ### Personal conversation reads — `conversation_get`, `conversation_list`
 
-- `conversation_get` is agent-owned: pass the exact `agent_id` that created the conversation.
+- `conversation_get`, `conversation_add_message`, `conversation_update`, and `conversation_delete` are agent-owned: pass the exact `agent_id` that created the conversation, or the call returns `agent_id_mismatch`.
 - `conversation_list` is not agent-filtered and returns the datapack's conversations for this user across agents.
 
 ### Team-shared reads — `knowledgebase_search`
@@ -83,15 +83,17 @@ knowledgebase_search(agent_id=anything, query=...)
 
 If the user asks "what do you know about X?":
 
-1. **`memory_search(agent_id="claude_desktop", query="X")`** — returns all of this user's personal memories across every agent. `agent_id` attributes the trace.
-2. **`knowledgebase_search(agent_id="<anything>", datapack_id="<datapack>", query="X")`** — returns team-shared knowledge. Useful when the answer may have been promoted by the user or a teammate.
+call **`context_search(agent_id="claude_desktop", conversation_id="<id>", datapack_id="<datapack>", query="X")`**. It returns separate buckets:
 
-Always tell the user which surface you searched: personal memory or team-shared knowledge.
+- memory: all of this user's personal memories across every agent;
+- knowledge base: team-shared knowledge, including anything the user or a teammate promoted;
+- conversation: matching past turns from any user or agent on the datapack.
+
+Always tell the user which surface each finding came from. Confirm an empty memory or KB bucket with `memory_search` or `knowledgebase_search` before saying nothing is there.
 
 ## 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 Desktop; more common in API products)
 - `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
@@ -99,7 +101,7 @@ Optional parameters can narrow a call further:
   `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`.
+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.
 
 ## Things I checked and found in-data on real Cloud datapacks