@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/assets/hooks-handlers/lib/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/assets/hooks-handlers/test_single_conversation.sh

@@ -17,7 +17,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CAPTURE_JS="$SCRIPT_DIR/lib/capture.js"
 MCP_URL="${1:-${MEKO_MCP_URL:-http://localhost:8000/mcp}}"
-AGENT_ID="${MEKO_AGENT_ID:-claude_code}"
+AGENT_ID="${MEKO_AGENT_ID:-agent}"
 
 # Temp dirs for isolation
 WATERMARK_DIR="$(mktemp -d -t meko-test-wm-XXXXXX)"

package/assets/scripts/package-desktop-skill.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Package meko-mcp-tools-desktop as a .skill file for Claude Desktop distribution.
+# Usage: bash scripts/package-desktop-skill.sh
+# Output: meko-mcp-tools-desktop.skill (ZIP archive)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILLS_ROOT="$SCRIPT_DIR/../skills"
+SKILL_NAME="meko-mcp-tools-desktop"
+OUTPUT="$SCRIPT_DIR/../$SKILL_NAME.skill"
+
+if [ ! -d "$SKILLS_ROOT/$SKILL_NAME" ]; then
+    echo "Error: Skill directory not found at $SKILLS_ROOT/$SKILL_NAME" >&2
+    exit 1
+fi
+
+if [ ! -f "$SKILLS_ROOT/$SKILL_NAME/SKILL.md" ]; then
+    echo "Error: SKILL.md not found in $SKILLS_ROOT/$SKILL_NAME/" >&2
+    exit 1
+fi
+
+# Remove previous build if it exists
+rm -f "$OUTPUT"
+
+# Package skill + references (exclude OS artifacts and desktop README)
+cd "$SKILLS_ROOT"
+zip -r "$OUTPUT" \
+    "$SKILL_NAME/SKILL.md" \
+    "$SKILL_NAME/references/" \
+    -x "*.DS_Store" "*__pycache__*"
+
+echo "Created $OUTPUT ($(du -h "$OUTPUT" | cut -f1))"
+echo ""
+echo "Contents:"
+unzip -l "$OUTPUT" | grep -E "^\s+[0-9]" | grep -v "files$"

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

@@ -4,53 +4,55 @@ description: Behavioral guide for AI agents using Meko MCP tools. Triggers when
 license: MIT
 metadata:
   author: Meko
-  version: "2.1.0"
+  version: "2.3.0"
   tags: mcp, yugabytedb, 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 31 MCP tools — and more importantly, **when to use them proactively** without waiting to be asked.
+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 26 MCP tools — and more importantly, **when to use them proactively** without waiting to be asked.
 
 ## What Meko enables
 
 Meko turns your volatile context window into persistent, shareable knowledge:
 
-- **Personal memory** — Store who the user is, their preferences, role, and working style. Survives across sessions.
-- **Team/org memory** — Store organizational conventions, coding standards, tooling choices. Shared across agents and team members.
-- **Shared knowledge** — Persist domain knowledge (product specs, data dictionaries, research) into a searchable knowledge base via RAG.
+- **Personal memory** — Store who the user is, their preferences, role, and working style. Private to you (scoped per-user and per-agent). Survives across sessions.
+- **Team-shared knowledge** — When the user promotes important memories from the Cloud UI's Learnings tab (or uploads documents via **Add Knowledge**), the content becomes visible to every member of the datapack. Queryable via `knowledgebase_search`.
 - **Conversation history** — Preserve full dialog exchanges with reasoning traces for audit, replay, and learning transfer.
 - **Decision traces** — Capture how and why decisions were made, enabling debugging and continuous improvement.
-- **Structured data** — Store and query tabular data in a real database, not squeezed into memory.
 
 ## When to use this skill
 
-- You are calling tools on a Meko / YugabyteDB MCP server
-- You need to decide what to store, where, and how
-- You are constructing SQL queries for `db_run_read_only_query` or `db_run_write_query`
-- You are setting up a RAG knowledge base pipeline
-- You are managing datapacks, agents, or knowledge base sources
-- You want to understand scope/permission requirements, `agent_id` constraints, or `datapack_id` routing
+- You are calling tools on a Meko MCP server
+- You need to decide what to store, where, and how (personal memory vs. team-shared knowledge)
+- You want to search the team's shared knowledge base (`knowledgebase_search`)
+- You are managing datapacks
+- You want to understand scope/permission requirements, `agent_id` conventions, or `datapack_id` routing
 
-## Discover the user's `agent_id` namespace — don't guess it
+## `agent_id` — multi-agent identity
 
-`agent_id` is currently overloaded: it doubles as a user-namespace key and an agent-type label. Treat it as the **user's namespace**, not as "which tool am I." See [issue #10](https://github.com/amiramm/meko-mcp-server/issues/10) for why this matters.
+`agent_id` identifies which agent wrote a memory or conversation. It is **not a constant**. On Cloud Meko today, different agents (Claude Code, Cursor, Claude Desktop — and different projects within each) each use their own `agent_id`, and the Cloud UI renders the value as a badge on every row.
 
-Defaulting to `claude_code` because you are Claude Code **fragments the user's memory across tools.** Don't do it.
+**Three buckets:**
 
-### The discovery protocol (run once per session, before any memory call)
+- **Project bucket** — `<client>:<repo-basename>`, e.g. `claude_code:meko-mcp-server`. The default for almost every memory in a coding session. The hook derives it from the cwd and injects it via SessionStart `additionalContext`.
+- **Common bucket** — `meko_agent`. The cross-project bucket for facts any agent should see regardless of project (user identity, global preferences). Empty / missing `agent_id` lands here automatically; you can also pass it explicitly.
+- **Loose name** — non-coding clients (Claude Desktop, generic MCP) use a stable client name like `claude_desktop`. Not relevant in this skill (Claude Code is a coding agent).
 
-1. Call `db_summarize_database(scope="read", conversation_id="00000000-0000-0000-0000-000000000000")`.
-2. Inspect the returned tables. Mem0 stores memories in `<agent_id>_mem0_collection`. For each such table with `row_count > 0`, that's an `agent_id` the user is already using.
-3. Pick the namespace:
-   - **Exactly one `<x>_mem0_collection` has rows** → use `agent_id="<x>"`.
-   - **Multiple candidates with rows** → pick the one with the highest `row_count` (that's the user's primary namespace). Mention the other(s) briefly so the user can steer if they want memory written elsewhere.
-   - **No `<x>_mem0_collection` has rows** → use `agent_id="agent"`. This is the fallback for a fresh user.
-4. Cache the chosen value. Use it for every `memory_*` and `conversation_*` call in this session.
+```
+agent_id = "claude_code:meko-mcp-server"   # this session's project bucket
+agent_id = "meko_agent"                     # cross-project facts
+```
+
+The SessionStart hook injects the project-bucket value into the first-turn `additionalContext`. Use that value verbatim for project-scoped Meko MCP calls in this session; do not re-derive it. Use `meko_agent` explicitly when you want a write or read to span projects.
 
-Never pick `claude_code` just because you're running in Claude Code. Pick what the user already uses. If you're wrong, the next `memory_search` returns nothing and you'll notice.
+**Read scoping varies by tool:**
+- `memory_search` / `memory_get_all` / `conversation_list` / `conversation_get` — scoped to `(datapack_id, user_id, agent_id)`. Each agent_id is its own bucket; pass the exact value you want to read from. Empty/whitespace gets rewritten to `meko_agent` server-side, so it returns common-bucket rows only — **not** a cross-agent fan-out.
+- `knowledgebase_search` — scoped to `(datapack_id)` only. `agent_id` on the request is **ignored**; you see the team's shared knowledge regardless of what you pass. Includes uploaded documents and memories that the user promoted via the UI's "Promote to Knowledge" flow.
 
-The SessionStart hook may seed a `conversation_id` in the watermark, but it does not pick `agent_id` for you — discovery still applies.
+See `tools-agent-id-conventions.md` for the full model, including how promotion works and how to phrase broad-query responses to the user.
+
+Some pre-existing rows in real datapacks use the older `agent_id="agent"` constant or other ad-hoc shapes (`claude_code`, `cursor:<slug>`). They remain readable — query them with `agent_id="agent"` explicitly. New writes should follow the schema above.
 
 ## Critical: Use Meko tools, not local storage
 
@@ -62,6 +64,54 @@ The SessionStart hook may seed a `conversation_id` in the watermark, but it does
 
 If a Meko tool call fails, you may fall back to local storage and tell the user — but Meko is always the first choice.
 
+## When spawning subagents
+
+Subagents (dispatched via the `Agent` / `Task` tool) do **not** receive the SessionStart `additionalContext` block. If they touch Meko, they either invoke tools with a nil-UUID `conversation_id` (orphaned from the parent's trace) or guess an `agent_id` / fabricate a `conversation_id` (split namespace, broken trace). A 2026-04-30 probe found 5 orphan memories written by a general-purpose subagent.
+
+### Rule (parent's responsibility)
+
+**Every spawn prompt MUST prepend an inherited-context block** with the parent's actual `agent_id` and `conversation_id`:
+
+```
+Meko context (inherited from parent session):
+- agent_id: "<parent's agent_id, verbatim>"
+- conversation_id: "<parent's conversation_id>"
+- Use these for all Meko MCP calls. Consult the meko-mcp-tools skill first for anything novel; do not re-derive these values.
+```
+
+Both values come from the SessionStart `additionalContext` that was injected into your first turn. Pass them through verbatim — the `agent_id` is not a fixed constant; it reflects the client + project the parent is running in.
+
+**Default: inject unconditionally.** The skill-listing heuristic (subagent seeing `meko-agent-skills:meko-mcp-tools` in its available skills) is unreliable, and injecting a 4-line block costs nothing. Don't try to predict whether the subagent will touch Meko — inject always.
+
+### What the subagent does with it
+
+The subagent treats the block as authoritative. Apply this hierarchy in order:
+
+1. **Default: reuse the inherited `conversation_id`.** The parent decides scope. Do NOT re-derive these values. Do NOT create a fresh conversation on a "feels separate" judgment — a separate-feeling task is not an explicit signal.
+2. **Exception: create a new conversation only when the spawn prompt (or user) explicitly says so.** An explicit signal means the parent's prompt says something like "use a fresh conversation" or "start your own conversation scope," or the user directly asks for one. Absent that signal, reuse.
+
+Whichever path applies, always use the inherited `agent_id` as-is — do not replace it, slugify it, or fall back to a constant.
+
+If the inherited block is **absent**, the subagent MUST NOT guess — see the self-diagnosis subsection below.
+
+### You may be a subagent — self-diagnosis
+
+**Tell-tale signs:**
+- You did NOT receive a SessionStart `additionalContext` block naming a Meko `conversation_id`.
+- You see `meko-agent-skills:meko-mcp-tools` in your available skills but no watermark / inherited-context reference in your initial prompt.
+- Your spawn prompt mentions you were "spawned" / "dispatched" / "launched" by a parent, or mentions a `Task` / `Agent` tool.
+
+**What to do:**
+- Look for a `Meko context (inherited from parent session):` block in the spawn prompt. If present, use those values verbatim for every Meko MCP call.
+- If absent, **refuse to invoke Meko write tools** and respond to the parent with a clarification request: ask for the parent's `agent_id` and `conversation_id`. The parent can re-dispatch with the block prepended.
+
+**What NOT to do:**
+- Do NOT fall back to the nil UUID (`"00000000-0000-0000-0000-000000000000"`) for `conversation_id` — that's an orphan-write pattern.
+- Do NOT invent an `agent_id`. The right value is whatever the parent is using (typically `claude_code:<repo-basename>`); don't assume `"agent"`, `"claude-code"`, `"meko_agent"`, or a different basename. Ask.
+- Do NOT silently create your own conversation to "just get moving" — ask the parent.
+
+Subagents cannot auto-discover the parent's watermark today: Claude Code does not expose a `CLAUDE_PARENT_SESSION_ID` env var or any equivalent marker file to subagent processes (see the spike note in `skills/hooks-handlers/lib/capture.js`). Prompt injection is the only enforcement mechanism.
+
 ## Core principle: Be Meko's persistent brain
 
 **Do not wait for the user to say "save this to memory."** Proactively store context that would be valuable in future sessions. Think of Meko as your long-term memory that persists across conversations.
@@ -73,12 +123,14 @@ If a Meko tool call fails, you may fall back to local storage and tell the user
 | User shares personal info ("I'm Amiram", "I'm a VP of Product") | Store as personal memory immediately | `memory_add` |
 | User states a preference ("I prefer dark mode", "always use Python") | Store as personal preference | `memory_add` |
 | User shares org convention ("we write in Go", "our standard is X") | Store as organizational memory | `memory_add` |
-| User teaches domain knowledge ("Meko traces are decision traces") | Store as memory AND consider KB ingestion | `memory_add` |
+| User teaches domain knowledge ("Meko traces are decision traces") | Store as memory; consider suggesting they promote it to Shared Knowledge from the Learnings tab | `memory_add` |
 | User corrects your behavior ("don't do X, do Y instead") | Store the correction as a learning | `memory_add` |
-| User asks "what do you know about X?" | Search memory first, then DB | `memory_search` then `db_run_read_only_query` |
+| User asks "what do you know about X?" | Three-call sweep: your project's memories, then the cross-project common bucket, then team-shared knowledge | `memory_search(agent_id=<yours>)` → `memory_search(agent_id="meko_agent")` → `knowledgebase_search` |
+| User asks "what do we (as a team) know about X?" or about uploaded documents | Query the team's Shared Knowledge directly | `knowledgebase_search` (returns uploaded docs + promoted memories) |
 | Session produced a valuable multi-turn exchange | Preserve the full conversation | `conversation_create` + `conversation_add_message` |
-| Significant learnings accumulated during session | Offer to persist key takeaways | Summarize and propose `memory_add` calls |
-| User provides structured/tabular data (CSV, data dictionary) | Store as database table, NOT memory | `db_run_write_query` (CREATE TABLE + INSERT) |
+| Significant learnings accumulated during session | Offer to persist key takeaways; remind the user they can promote important ones to Shared Knowledge from the Cloud UI | Summarize and propose `memory_add` calls |
+| User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP on Cloud today — `db_run_write_query` returns `{"error": "not_available"}`. Store the key facts as memories or point the user at the UI's knowledge-base upload for file form | `memory_add` for facts, UI "Add Knowledge" for files |
+| User wants to add documents to the team's knowledge base | Point them at the Cloud UI flow — Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). The MCP ingestion tools are not available on Cloud. | UI only |
 
 ### Information classification
 
@@ -89,19 +141,21 @@ User says something → Classify:
 ├── About themselves (name, role, preferences)
 │   → memory_add — personal profile
 ├── About how their team/org works (conventions, standards, policies)
-│   → memory_add — organizational memory
+│   → memory_add — personal memory; the user can promote it to Shared
+│      Knowledge from the UI's Learnings tab so teammates see it too
 ├── Domain knowledge (facts, definitions, specs, research)
-│   → memory_add for quick recall + KB ingestion for search at scale
+│   → memory_add for quick recall; for bulk documents, the user uploads
+│      files via the UI's Datapack → Actions → Add Knowledge flow
 ├── A correction or learning ("don't do X", "always do Y")
 │   → memory_add — behavioral feedback
 ├── Full conversation worth preserving (multi-turn, reasoning traces)
 │   → conversation_create + conversation_add_message — verbatim
 └── Structured/tabular data (CSV rows, schemas, data dictionaries)
-    → db_run_write_query (CREATE TABLE + INSERT) — NOT memory_add
+    → Not MCP-supported on Cloud today (db_run_write_query returns
+      {"error": "not_available"}). Extract key facts to memory_add
+      or tell the user this isn't a Cloud feature yet.
 ```
 
-**Why not memory_add for tabular data?** Mem0 extracts individual facts from text. Passing CSV rows through it loses columns, rows, and structural relationships. Use the database for structured data.
-
 ## Automatic conversation capture
 
 The Meko plugin automatically captures conversations via three mechanisms that coordinate through a shared watermark file:
@@ -117,10 +171,10 @@ All three are handled automatically. **Do NOT set up CronCreate for conversation
 The SessionStart hook has already done the setup for you:
 
 1. **Created a Meko conversation** — `conversation_id` is injected into `additionalContext` on the first turn. Use that value for all subsequent MCP tool calls that accept `conversation_id`.
-2. **Discovered and cached `agent_id`** — also injected into `additionalContext`. Use the injected value as-is; do not re-run `db_summarize_database` unless `additionalContext` shows discovery failed (falls back to a default).
+2. **Echoed the session's `agent_id`** — also injected into `additionalContext`. Use the injected value verbatim for project-scoped Meko tool calls. It's a per-session value derived from the cwd (shape: `claude_code:<repo-basename>`), not a constant. For genuinely cross-project facts, write/read with `agent_id="meko_agent"` (the common bucket) instead.
 3. **Preloaded recent memories** — `additionalContext` may include a `### Memories from prior sessions` block. Inspect it before acting so you don't re-ask questions the user has already answered.
 
-If `additionalContext` is absent or empty (hook failed, MCP unavailable), fall back to the manual protocol: run discovery via `db_summarize_database` (see "Discover the user's `agent_id` namespace" above) and use a nil UUID for `conversation_id` until you can create a real one.
+If `additionalContext` is absent or empty (hook failed, MCP unavailable), ask the user for their `agent_id` — do not invent one. See `tools-agent-id-conventions.md`.
 
 ### Before potentially destructive actions
 
@@ -128,9 +182,11 @@ Before any action that deletes, overwrites, or restructures user content — `Wr
 
 ```
 memory_search(scope="read", query="destructive <action type> preferences feedback",
-              agent_id=<discovered>, conversation_id=<session_or_nil>)
+              agent_id=<your agent_id>, conversation_id=<session_conversation_id>)
 ```
 
+Also consider a second call with `agent_id="meko_agent"` to surface common-bucket feedback — preferences the user (or any other agent) wrote under the cross-project bucket. And a `knowledgebase_search` for team-wide guidance if the action is one the team has promoted policy on.
+
 If a relevant feedback memory exists (e.g., "always ask before deleting content"), confirm with the user before proceeding. If the search is empty, proceed, but treat the action as irreversible and prefer a dry-run / preview when one is available.
 
 ### Capture rules
@@ -144,41 +200,99 @@ If a relevant feedback memory exists (e.g., "always ask before deleting content"
 
 **Use only the required parameters. Do not guess optional parameters.**
 
+In the examples below, `<your-agent-id>` means the value the SessionStart hook injected into `additionalContext` — for Claude Code, something like `claude_code:meko-mcp-server`. Not the literal string `"<your-agent-id>"`.
+
 ### memory_add — correct call pattern
 ```
-memory_add(scope="write", text="User is VP of Product at YugabyteDB", agent_id="claude_code", conversation_id="00000000-0000-0000-0000-000000000000")
+memory_add(scope="write",
+           text="User is VP of Product at YugabyteDB",
+           agent_id="<your-agent-id>",
+           conversation_id="<session_conversation_id>")
 ```
-Required parameters: `scope`, `text`, `agent_id`, `conversation_id`. Use a nil UUID (`"00000000-0000-0000-0000-000000000000"`) for `conversation_id` unless you have a real one from `conversation_create`. NEVER use strings like `"current"` or `""`.
+Required parameters: `scope`, `text`, `conversation_id`. On **writes**, `conversation_id` must be a real UUID (from `conversation_create` or the SessionStart hook) — writes attached to a nil/empty conversation are orphaned in Langfuse traces. NEVER pass `"current"` or other non-UUID values. `agent_id` is technically optional — empty/missing routes the write into the `meko_agent` common bucket — but for project-scoped facts pass the SessionStart-injected value verbatim.
 
 ### memory_search — correct call pattern
 ```
-memory_search(scope="read", query="user role", agent_id="claude_code", conversation_id="00000000-0000-0000-0000-000000000000")
+memory_search(scope="read",
+              query="user role",
+              agent_id="<your-agent-id>",
+              conversation_id="<session_conversation_id>")
+```
+Required parameters: `scope`, `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." For conversation-scoped filtering use the separate `run_id` parameter.
+
+For cross-project common-bucket search (facts written under `agent_id="meko_agent"`, including everything you wrote with empty/missing agent_id), pass it explicitly:
+```
+memory_search(scope="read", query="user role",
+              agent_id="meko_agent", conversation_id="<session_conversation_id>")
+```
+
+Empty string also resolves to `meko_agent` server-side, but be explicit so it's obvious from the call you mean the common bucket. To search results across multiple specific projects (e.g. also see what was written from `claude_code:other-repo`), call `memory_search` once per agent_id — there's no single-call fan-out.
+
+### knowledgebase_search — correct call pattern
+```
+knowledgebase_search(scope="read",
+                     query="...",
+                     agent_id="<anything — ignored>",
+                     conversation_id="<session_conversation_id>",
+                     datapack_id="<datapack UUID>",
+                     limit=10)
 ```
-Required parameters: `scope`, `query`, `agent_id`, `conversation_id`. Use a nil UUID for `conversation_id`.
+Required parameters: `scope`, `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.
 
 ### Critical parameter rules
 
-- **agent_id**: Use the value you discovered at session start (see "Discover the user's `agent_id` namespace" above), not a literal tool name. The reference examples below use `claude_code` for illustration only — substitute the discovered value. Must use underscores, never hyphens (hyphens break PostgreSQL table names and produce SQL syntax errors). If you haven't run discovery yet, do it now before any memory call.
-- **conversation_id**: If required by the tool, use a nil UUID (`"00000000-0000-0000-0000-000000000000"`) unless you have a real one from `conversation_create`. NEVER use strings like `"current"`, `""`, or other non-UUID values.
-- **scope**: Only `"read"`, `"write"`, or `"admin"`. Nothing else.
+- **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**: Behavior varies by tool. 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 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.
+- **scope**: Only `"read"`, `"write"`, or `"admin"`. Nothing else. Use the minimum the code actually requires (the per-tool cookbook shows it).
 - **When in doubt about optional parameters, omit them.** The server has sensible defaults.
 
+### Verify after writing
+
+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.
+- **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.
+
+### First-run connection test
+
+On the first Meko tool call in a fresh session (no prior Meko tool call since process start), and whenever the user explicitly asks "is Meko working?" or "test Meko connection", run a canary round-trip before proceeding with their actual request. This is the user-visible proof that the MCP transport, auth, and datapack routing are wired correctly end-to-end — a silent failure at install time will otherwise only surface much later, when real memories go missing.
+
+**What it does.** Write a canary memory with the shape below, capture the `id` returned by `memory_add`, then verify with `memory_get_by_id` — a direct pgvector row lookup. If the row is returned, delete it (default) and tell the user "Meko connection OK". If any step fails, tell the user exactly which step failed — do not swallow the error. Do not retry: routing errors need to surface, not be papered over. (We use `memory_get_by_id` rather than `memory_search` deliberately: mem0 does not index metadata and is inconsistent about indexing the memory text for very short strings, so a search-based canary false-negatives against the real service.)
+
+**Canary memory shape.** This is the spec; keep the fields stable so support can grep for them.
+
+- `scope`: `"write"`
+- `agent_id`: the session's `agent_id` (from `additionalContext`); not a constant
+- `conversation_id`: the session's `conversation_id` (from `additionalContext`). If the hook failed and you truly have no conversation_id, call `conversation_create` first and use the returned id — do not use a nil UUID, it orphans the canary trace.
+- `text`: `"Meko connection test: <client> @ <installer-version> — <ISO timestamp>. Safe to delete."`
+- `metadata` (JSON): `{"type": "connection-test", "marker": "<uuid>", "client": "claude-code" | "claude-desktop" | "cursor", "installer_version": "<x.y.z>", "installed_at": "<ISO>"}`
+
+**Gating.** The canary runs at most once per session. Persist a one-line-per-session marker (JSON `{ "last_canary_at": "<ISO>", "result": "ok" | "failed", "marker": "<uuid>" }`) under `~/.claude/meko-capture/canary-<agent_id-slugified>.json` — mirroring the watermark-file convention the capture hook already uses. On session start, check the file's mtime; if it was written during this process's uptime, skip. On success, rewrite the file. When the user explicitly asks to test the connection, ignore the gate and run anyway.
+
+**Keeping the canary for support.** By default the canary is deleted after read-back. If the user passes `--keep-canary` (or equivalent) or is debugging an issue with support, leave it in place — the `metadata.type: "connection-test"` label makes it safe to identify and purge later.
+
+**Reporting.** This is user-visible — the whole point is to give the user concrete proof. On success: `"Meko connection OK (canary round-trip succeeded)"`. On failure, name the failing step and include the raw error: `"Meko canary failed at memory_add: <error>. Likely causes: wrong datapack, expired API key, server unreachable."`
+
 ## Key concepts
 
-1. **31 tools in 5 groups**: Database (3), RAG/Knowledge Base (3), Memory (7), Conversation (7), Datapack Management (11)
-2. **Scope hierarchy**: `read < write < admin` — every tool validates scope at entry. Only three valid values: `"read"`, `"write"`, `"admin"`. Using anything else (e.g., `"all"`) will fail.
-3. **datapack_id routing**: All DB, RAG, and memory tools accept optional `datapack_id` to target a specific datapack's database instead of the default
-4. **agent_id is a per-user namespace, not a per-tool label**: Memory and conversation tools use `agent_id` to isolate data. Discover the user's existing namespace via `db_summarize_database` at session start (see the section above) and use that value across every call — don't default to `claude_code` just because the current client is Claude Code. Must use underscores, never hyphens (hyphens are injected into PostgreSQL table names and cause SQL syntax errors). Issue [#10](https://github.com/amiramm/meko-mcp-server/issues/10) tracks the schema split that will eventually unbundle this.
-5. **Write guardrails**: `db_run_write_query` blocks dangerous SQL patterns and enforces configurable limits. One statement per call.
-6. **Conversation dedup**: `conversation_add_message` supports seed-based deterministic trace IDs to prevent duplicates
-7. **Known limitations**: Some tools have bugs or missing capabilities — see `tools-known-limitations.md` before attempting RAG cleanup or write operations
-8. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks
+1. **26 tools in 5 groups**: Memory (8), Conversation (6), Knowledge Base (4), Datapack (5), Database (3). On Cloud Meko today, all DB tools and the three KB ingestion tools return `{"error": "not_available"}` — only `knowledgebase_search` works in the KB group. See `tools-overview.md` for the full availability map.
+2. **Scope hierarchy**: `read < write < admin` — every tool validates scope at entry. Only three valid values: `"read"`, `"write"`, `"admin"`. Using anything else (e.g., `"all"`) will fail. Tool docstrings sometimes say `"Pass 'admin'"` but the code only requires `"read"` or `"write"` — use the minimum the code actually enforces.
+3. **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.
+4. **agent_id is multi-agent**: Each client+project uses its own `agent_id` (shape `<client>:<repo-basename>`). Writes are scoped to `(datapack_id, user_id, agent_id)`. Personal reads (`memory_search`, `memory_get_all`) filter strictly on this tuple. Empty/missing `agent_id` lands in the `meko_agent` common bucket — use it explicitly for cross-project facts. `knowledgebase_search` ignores `agent_id` entirely and returns the team-shared knowledge on the datapack. See `tools-agent-id-conventions.md`.
+5. **Personal memory vs. team-shared knowledge**: Un-promoted memories (`mem0_collection`) are scoped per-user and per-agent — only you see them. The user can promote important memories to Shared Knowledge via the Cloud UI's Learnings tab, which makes them visible to every team member on the datapack (user_id filter stripped). `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents. See `tools-memory-vs-conversation.md`.
+6. **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 (`/observe-hub?project=<langfuse_pid>&session=<conversation_id>`) or directly from a datapack's Conversations tab via the **Open in Observe** button. See `tools-memory-vs-conversation.md`.
+7. **Adding documents or growing a knowledge base is UI-only on Cloud today**: users upload 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`.
+8. **Conversation dedup**: `conversation_add_message` supports seed-based deterministic trace IDs to prevent duplicates.
+9. **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.
+10. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
+11. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks.
 
 ## Reference sections
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 31 tools with decision tree |
+| `tools-overview.md` | Complete catalog of all 26 tools with decision tree + cloud Free-Tier gating map |
 | `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 31 tools with a decision tree for choosing the right tool
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 26 tools with a decision tree and cloud Free-Tier gating map
 
 ## Tool-Specific Guidance
 - [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message

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

@@ -1,39 +1,101 @@
-# agent_id Naming Rules and Namespace Isolation
+# agent_id — multi-agent identity on Cloud Meko
 
-**WRONG:** `agent_id="my-support-agent"` → mem0 uses agent_id in table names (`my-support-agent_mem0_collection`), and hyphens are invalid PostgreSQL identifiers → table creation fails.
+`agent_id` identifies **which agent wrote a memory or created a conversation**. It is not a constant. Pick a value that represents the specific agent + project you're acting for, use it consistently for writes within this session, and use it to scope your own reads.
 
-## The Rule
+The Cloud UI (`cloud.mekodata.ai`) renders `agent_id` as a badge on every memory and conversation row — so the value you pick is user-visible. Multiple different agents with different `agent_id` values can write into the same datapack; each one's personal view is scoped to itself, and the UI shows the full cross-agent picture.
 
-**agent_id MUST NOT contain hyphens.** Use underscores. Stick to: lowercase letters, digits, and underscores.
+## The three buckets
+
+Memories segregate strictly by `agent_id`. Pick the right bucket up front:
+
+| Pattern | When to use | Example |
+|---|---|---|
+| `<client>:<repo-basename>` | Coding agents (Claude Code, Cursor) writing project-scoped facts. The default for almost every memory in a coding session. | `claude_code:meko-mcp-server` |
+| 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.
+
+For genuinely cross-project facts ("the user's name is Amiram", "the user prefers dark mode") write with `agent_id="meko_agent"` so future agents in different projects can read them.
+
+## Valid characters
+
+The server stores `agent_id` as a row-level column value — it never becomes a PostgreSQL identifier on Cloud. Any printable string works: colons, hyphens, dots, underscores, spaces. Stay within what's readable in the UI badge.
+
+Pre-existing data in real datapacks includes a mix of legacy shapes — `agent`, `claude-code`, `claude_code`, `cursor:<slug>`, `claude-code:-Users-...`. None of them cause errors. To query those rows, pass the literal legacy value as `agent_id` (e.g. `agent_id="agent"` for rows from before the rewrite). New writes should follow the table above.
+
+## How agent_id filters reads and writes
+
+### Writes — `memory_add`, `conversation_create`, `conversation_add_message`
+
+- The row stores `(meko_datapack_id, meko_user_id, meko_agent_id)` — the user_id comes from your cognito account; the datapack_id defaults or is explicit; the agent_id is what you pass.
+- If you pass an empty or whitespace-only `agent_id`, the server stores `meko_agent`. That's the common bucket — fine for cross-project facts; not what you want for project-scoped writes.
+
+### Personal reads — `memory_search`, `memory_get_all`, `conversation_list`, `conversation_get`
+
+Filter tuple: `(datapack_id, user_id, agent_id)`.
+
+- `user_id` is **always enforced**: you can only see memories and conversations you wrote (or that other team members shared with you via promotion — see below). One user cannot read another team member's un-promoted memories directly from MCP.
+- `agent_id` is **strictly matched**: a search with `agent_id="claude_code:meko-mcp-server"` returns only rows whose stored value is exactly that. A memory written by `agent_id="cursor:foo"` is invisible to it.
+- An empty `agent_id` is rewritten to `meko_agent` server-side, so a "broad" read with empty string returns only common-bucket rows — **not** a cross-agent fan-out. To search across multiple agent_ids, call once per known value.
+
+Empirically verified 2026-05-19 on Cloud prod (free-tier multitenant mode, segregation via row-level filter).
+
+### Team-shared reads — `knowledgebase_search`
+
+Filter tuple: `(datapack_id)` only. **`agent_id` on the request is ignored.** Whatever value you pass, `knowledgebase_search` returns every row on the datapack.
+
+This is the multi-user, multi-agent read path. Content in `knowledgebase_search` is shared across:
+- All agents on the datapack (any `agent_id` value)
+- All users with access to the datapack (`user_id` is not a column on the shared table)
+
+The originating `agent_id` is preserved in each result's `metadata_filters.agent_id` for provenance, but it does not affect which rows come back.
+
+## What lives where
 
 ```
-GOOD: "support_bot", "sales_agent_v2", "agent_001"
-BAD:  "support-bot", "sales-agent-v2", "my agent", "agent.one"
+memory_add(agent_id=X, text=...)
+   │
+   ▼
+mem0_collection  ── personal memories, scoped (datapack, user, agent)
+   │
+   │   UI "Promote to Knowledge" (Learnings tab)
+   │   ─────────────────────────────────────────
+   │   Strips user_id, keeps agent_id as metadata,
+   │   copies into team-shared table
+   ▼
+knowledge_base   ── team-shared, scoped (datapack) only
+   │
+   ▼
+knowledgebase_search(agent_id=anything, query=...)
 ```
 
-## Namespace Isolation
-
-`agent_id` is the primary isolation boundary for both memory and conversation tools:
+- **Personal memories** are what you get from `memory_search` / `memory_get_all`. Private to you.
+- **Shared Knowledge** is what you get from `knowledgebase_search`. Visible to every user and every agent on the datapack.
+- **Promotion is UI-only.** There is no MCP tool for promoting a memory to Shared Knowledge — the user triggers it from the datapack's Learnings tab in the Cloud UI.
 
-**Memory (mem0/pgvector + Apache AGE):**
-- Each agent_id gets its own pgvector collection (`{agent_id}_mem0_collection`) and AGE graph (`{agent_id}_mem0_graph`)
-- `memory_search` and `memory_get_all` only return data from the specified agent's namespace
+## When to use what — broad-query guidance
 
-**Conversations (Langfuse):**
-- Traces tagged with `agent:{agent_id}`, names prefixed with `{agent_id}:message`, `{agent_id}:start`, `{agent_id}:update`
-- `conversation_list` and `conversation_get` filter by and verify agent ownership
+If the user asks "what do you know about X?" and you want to maximize recall:
 
-## Consistency is Critical
+1. **First call**: `memory_search(agent_id="<your agent_id>", query="X")` — returns your own project's memories. Most relevant if the context is "what have you and I done in this repo."
+2. **Second call**: `memory_search(agent_id="meko_agent", query="X")` — returns the common cross-project bucket (user identity, global preferences). Anything you wrote with `agent_id="meko_agent"` from any agent or project, plus rows the server stored under that name when called with empty `agent_id`.
+3. **Third call**: `knowledgebase_search(agent_id="<anything>", datapack_id="<datapack>", query="X")` — returns team-shared knowledge. Useful when the answer may have been promoted by the user or a teammate.
 
-**WRONG:** Using `agent_id="support_bot"` for memory and `agent_id="supportBot"` for conversations — these are separate namespaces that will never see each other's data.
+For a true cross-agent fan-out (e.g. you also want to see what was written from `claude_code:other-repo` or `cursor:foo`), call `memory_search` once per known agent_id — the empty-string shortcut does not bypass the filter; the server rewrites empty to `meko_agent`.
 
-Use the same `agent_id` string across all memory and conversation calls for the same logical agent.
+Always tell the user what scope you searched, so they understand why the answer is or isn't there. Example wording: "I found this in your project memories" vs. "I found this in your common cross-project bucket" vs. "I found this in your team's shared knowledge."
 
-## Sub-Scoping
+## Sub-scoping within an agent
 
-Within a single agent_id, further scope with optional parameters:
-- `user_id` — per-user isolation
-- `app_id` — per-application (e.g., "web_app" vs "mobile_app")
+Optional parameters narrow further within the same `agent_id`:
+- `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` — per-execution run
 
 Available on `memory_add`, `memory_search`, `memory_get_all`, `memory_delete_all`, `conversation_create`, `conversation_list`.
+
+## Things I checked and found in-data on real Cloud datapacks
+
+- `agent_id="agent"` appears on many legacy rows — it was the previous canonical constant. New writes should use the schema in the table above; query legacy rows with `agent_id="agent"` explicitly.
+- Memory Summary UI (`/datapacks/<name>/memory-summary`) is agent-id-agnostic — shows every row in the datapack, renders the stored `agent_id` as a badge. The filtering is MCP-side only.
+- 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.