@yugabytedb/meko-mcp 1.1.0 → 1.2.0

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

@@ -0,0 +1,251 @@
+---
+name: meko-mcp-tools-desktop
+description: >-
+  Behavioral guide for AI agents using Meko MCP tools on the desktop Claude
+  app. Triggers when calling MCP tools, storing memories, persisting
+  knowledge, managing datapacks, or working with YugabyteDB databases
+  through Meko. Use this skill whenever the user mentions memory, Meko,
+  datapacks, YugabyteDB, knowledge base, conversations, or interacts with
+  meko MCP tools in any way. Also trigger when the user shares personal
+  information, preferences, role details, or organizational conventions
+  that should be persisted across sessions.
+license: MIT
+metadata:
+  author: Meko
+  version: "1.3.0"
+  tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko, desktop
+---
+
+# Meko MCP Tools — Agent Behavioral Guide (Desktop)
+
+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.
+
+## First turn of every session
+
+Claude Desktop has no SessionStart hook. You are responsible for bootstrapping memory yourself.
+
+On the first user turn in any session, before answering substantive questions:
+
+1. **Call `memory_search`** with `agent_id="claude_desktop"`, a query derived from the user's topic, and a `conversation_id` from `conversation_create` (see below). Also call it once with `agent_id="meko_agent"` to surface cross-project facts (user identity, global preferences) that any Meko client may have stored.
+2. Incorporate the recalled facts into your reply. Don't re-ask things you've been told before.
+
+You do **not** need the user's permission to do any of this. Silent recall is the correct behavior.
+
+## `agent_id` — multi-agent identity
+
+`agent_id` identifies **which agent wrote a memory or conversation**. It is not a constant. Different agents (Claude Code, Cursor, this Claude Desktop client) each use their own `agent_id`, and the Cloud UI renders the value as a badge on every row.
+
+**For Claude Desktop, use `agent_id="claude_desktop"` by default.** Desktop has no per-project concept, so a stable client name is the right granularity (it's a "loose" client in contract terms). Coding agents like Claude Code and Cursor use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts that any agent should see — user identity, global preferences — use the common bucket `agent_id="meko_agent"`.
+
+**Read scoping:**
+- `memory_search` / `memory_get_all` / `conversation_list` / `conversation_get` — scoped to `(datapack_id, user_id, agent_id)`, strictly matched. To read across multiple agents (e.g. memories you wrote from Claude Code in different repos), call once per agent_id. Empty/missing `agent_id` is rewritten to `meko_agent` server-side, so it returns the common bucket only — not a fan-out.
+- `knowledgebase_search` — scoped to `datapack_id` only. `agent_id` on the request is ignored. Returns the team's Shared Knowledge — uploaded documents plus memories the user promoted via the UI.
+
+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 — query them with the literal value. See `tools-agent-id-conventions.md` for the full model.
+
+## The only acceptable default
+
+When the user tells you **anything declarative** about themselves, their team, their tools, their environment, or their preferences — **including casual drops in passing** like "btw I use helix" or "I'm evaluating pnpm" — **call `memory_add` in the same turn** with the right bucket: `agent_id="meko_agent"` for cross-project facts (user identity, global preferences), or `agent_id="claude_desktop"` for desktop-specific context. No "would you like me to remember this?" — just store it and continue. Ask permission only if the information is sensitive (credentials, legal, medical).
+
+There is no "substantive enough" threshold. Short casual drops are exactly the memories that matter most over time, because they accumulate into a profile of who the user is and how they work. Treat every declarative statement about the user as a save candidate by default.
+
+The failure mode to avoid: listening to the user, answering their question, and moving on without persisting anything. A turn later you have no record that the exchange happened. That is the single most common failure of this skill in practice — do not repeat it. Explicitly override your default "just answer and move on" reflex on open-ended prompts: if the user shared a declarative fact along the way, the save happens first, then the answer.
+
+### Deterministic memory flush (new in v1.2.0)
+
+Claude Desktop has no SessionStart / PreCompact / SessionEnd hooks — in practice the save-on-every-declarative rule above still gets missed on open-ended prompts. To compress the failure surface, call the server-side `flush_pending_memory_candidates` tool periodically:
+
+1. **At session start**, call:
+   ```
+   flush_pending_memory_candidates(scope="read", agent_id="claude_desktop")
+   ```
+2. **After every ~5 assistant turns**, call it again.
+3. The tool returns a directive telling you to scan recent user turns for unsaved facts and issue `memory_add` calls. **Follow the directive immediately** — that's the whole point. The server dedups on its side, so repeat calls are safe.
+
+This turns "remember to save" into "act on the checklist the server just handed you." The tool result is always read by the model, so this is a deterministic floor on memory capture even if the proactive rule misses the signal.
+
+## 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. Private to you (scoped per-user and per-agent).
+- **Team-shared knowledge** — Memories the user promotes from the Learnings tab in the Cloud UI become visible to every member of the datapack. Uploaded documents land in the same place. Both are 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.
+
+## When to use this skill
+
+- 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
+
+## Critical: Use Meko tools, not local storage
+
+**When Meko MCP tools are available, ALWAYS use them instead of local/built-in storage mechanisms.** Do not write to local memory 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.
+
+- User shares personal info → call `memory_add` on the MCP server, NOT write to a local file
+- User asks what you know → call `memory_search` on the MCP server, NOT read local files
+- Conversation worth preserving → call `conversation_create`, NOT save to a local log
+
+If a Meko tool call fails, you may fall back to local storage and tell the user — but Meko is always the first choice.
+
+## 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.
+
+Rules of thumb:
+
+- **Save-first, not save-later.** If a fact is worth remembering, store it in the same turn it appeared. Do not promise to remember it — actually call `memory_add`.
+- **One `memory_add` per distinct fact.** Don't batch five unrelated facts into a single long text field; Mem0 extracts atomic facts and batching hurts recall.
+- **Call it silently.** Don't interrupt the conversation with "I've saved that to memory." Just save and continue. A short acknowledgment is fine if the user explicitly asked you to remember something.
+- **Never log to local files as a memory substitute.** If `memory_add` fails, retry once; if it still fails, tell the user the call failed rather than writing a markdown note.
+
+### Proactive behavior rules
+
+| Signal in conversation | What to do | Tool to use |
+|---|---|---|
+| 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 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?" | Three-call sweep: desktop memories, then the cross-project common bucket, then team-shared knowledge | `memory_search(agent_id="claude_desktop")` → `memory_search(agent_id="meko_agent")` → `knowledgebase_search(datapack_id=<X>)` |
+| 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; 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 a narrative memory, 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
+
+When the user shares information, classify it before storing:
+
+```
+User says something → Classify:
+├── About themselves (name, role, preferences)
+│   → memory_add — personal profile
+├── About how their team/org works (conventions, standards, policies)
+│   → 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; 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)
+    → 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.
+```
+
+## Conversation capture
+
+Claude Desktop does not have automatic capture hooks. Preserve valuable sessions manually.
+
+### When to create a conversation
+
+Create a conversation container when starting substantive work — not for quick questions, but for sessions with multi-turn reasoning worth replaying or sharing. **Call `conversation_create` early so you have a real `conversation_id`** — memory writes require one (nil-UUID orphans the trace in Langfuse):
+
+```
+conversation_create(scope="write", agent_id="claude_desktop",
+    title="<descriptive topic>")
+```
+
+Save the returned `conversation_id` — use it for all subsequent calls in that session.
+
+### When to add messages
+
+After significant exchanges (3+ turns), save key exchanges:
+
+```
+conversation_add_message(scope="write", conversation_id="<id>",
+    agent_id="claude_desktop",
+    input="<exact user prompt>",
+    output="<exact assistant response>",
+    reasoning="<tool calls and reasoning, if any>")
+```
+
+### Capture rules
+
+- **Verbatim content only** — never summarize, rephrase, or condense any field
+- **Include tool calls** in the `reasoning` field — these are essential for session replay
+- **Extract key facts** with `memory_add` alongside conversation capture — memory is searchable, conversations are not
+- **Use seeds** for dedup: `seed="<conversation_id>:claude-desktop:<sequential_number>"`
+
+## Calling tools correctly on the first attempt
+
+**Use only the required parameters. Do not guess optional parameters.**
+
+### memory_add — correct call pattern
+```
+memory_add(scope="write",
+           text="User is VP of Product at YugabyteDB",
+           agent_id="claude_desktop",
+           conversation_id="<id from conversation_create>")
+```
+Required parameters: `scope`, `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.
+
+### memory_search — correct call pattern
+```
+memory_search(scope="read",
+              query="user role",
+              agent_id="claude_desktop",
+              conversation_id="<id from conversation_create>")
+```
+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; 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 written with empty/missing `agent_id`), pass it explicitly:
+```
+memory_search(scope="read", query="user role",
+              agent_id="meko_agent", conversation_id="<id>")
+```
+
+Empty string also resolves to `meko_agent` server-side. To search across other clients' specific buckets (e.g. `claude_code:some-repo`), call `memory_search` once per known 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="<id>",
+                     datapack_id="<datapack UUID>",
+                     limit=10)
+```
+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**: `"claude_desktop"` for this client's project-less personal writes/reads. Use `"meko_agent"` for the cross-project common bucket (genuinely global facts like user identity). Empty/missing routes to `meko_agent` server-side; that's not a cross-agent fan-out. 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` — 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.
+- **When in doubt about optional parameters, omit them.** The server has sensible defaults.
+
+## Key concepts
+
+1. **26 tools in 5 groups**: Memory (8, including `flush_pending_memory_candidates` — the Desktop deterministic-capture helper described above), 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`.
+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**: For Claude Desktop, use `agent_id="claude_desktop"` for desktop-personal writes and `agent_id="meko_agent"` for cross-project common facts. Writes are scoped to `(datapack_id, user_id, agent_id)`. Personal reads filter strictly on this tuple — to span agent_ids, call once per known value (the empty-string shortcut is not a fan-out; the server rewrites empty to `meko_agent`). `knowledgebase_search` ignores `agent_id` entirely. See `tools-agent-id-conventions.md`.
+5. **Personal memory vs. team-shared knowledge**: Un-promoted memories 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. `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents.
+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. See `tools-memory-vs-conversation.md`.
+7. **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`.
+8. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
+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 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-rag-workflow.md` | End-to-end RAG pipeline flow |
+| `tools-scope-permissions.md` | read/write/admin permission hierarchy |
+| `tools-troubleshooting.md` | Error recovery, retry strategies, stuck pipeline diagnosis |
+| `tools-known-limitations.md` | Broken tools, missing capabilities, permission gaps |

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

@@ -0,0 +1,150 @@
+# Meko MCP Tools — Claude Desktop Setup
+
+Use the Meko MCP tools skill natively in Claude Desktop. The skill teaches Claude to proactively store memories, classify information, use all 25 Meko MCP tools correctly, and handle errors gracefully.
+
+## Setup
+
+### Step 1: Install the skill
+
+**Option A — Plugin marketplace** (recommended):
+
+In Claude Desktop: Customize > Personal plugins > Browse plugin marketplace. Search for `meko-agent-skills-claude-desktop` and install.
+
+**Option B — .skill file:**
+
+Download `meko-mcp-tools-desktop.skill` from the [releases page](https://github.com/yugabyte/meko-mcp-server/releases) and drag it into Claude Desktop (or use Customize > Skills > Import).
+
+**Option C — Manual install:**
+
+```bash
+git clone https://github.com/yugabyte/meko-mcp-server.git
+```
+
+Copy `skills/skills/meko-mcp-tools-desktop/` into Claude Desktop's skill directory. The exact path depends on your Desktop version — check Customize > Skills for the install location.
+
+### Step 2: Configure the MCP server
+
+Add the Meko MCP server to your Claude Desktop configuration. Go to Claude > Settings > Developer > Edit Config and add a `mcpServers` entry.
+
+**Local HTTP** (for [meko-test](https://github.com/yugabyte/meko-test) docker-compose users):
+
+```json
+{
+  "mcpServers": {
+    "meko": {
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+**Local stdio** (running the server directly via uv):
+
+```json
+{
+  "mcpServers": {
+    "meko": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/meko-mcp-server",
+        "run",
+        "src/server.py"
+      ],
+      "env": {
+        "YUGABYTEDB_URL": "dbname=yugabyte host=localhost port=5433 user=yugabyte password=yugabyte",
+        "OPENAI_API_KEY": "your-openai-api-key",
+        "OPENAI_MODEL": "gpt-4.1-nano-2025-04-14",
+        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
+      }
+    }
+  }
+}
+```
+
+Replace `/path/to/meko-mcp-server` with your cloned repo path and set the correct database URL and API keys.
+
+**Managed instance:**
+
+```json
+{
+  "mcpServers": {
+    "meko": {
+      "url": "https://<your-instance>.mcp.mekodev.com/mcp"
+    }
+  }
+}
+```
+
+Get the URL from your team.
+
+Restart Claude Desktop after editing the configuration.
+
+### Step 3: Verify
+
+Start a new conversation and say:
+
+> Show me the tables in my database.
+
+Claude should call `db_summarize_database` and return the table schemas. If it works, the MCP server and skill are both connected.
+
+## Usage
+
+The skill triggers automatically based on context — just talk to Claude naturally:
+
+### Store personal info (triggers memory_add proactively)
+> I'm a backend engineer. We use Go and YugabyteDB for everything.
+
+### Recall memories (triggers memory_search)
+> What do you know about me?
+
+### Query the database (triggers db_summarize_database / db_run_read_only_query)
+> Show me the first 10 rows from the customers table.
+
+### Save conversations (triggers conversation_create + conversation_add_message)
+> Save this conversation.
+
+### Store structured data (triggers db_run_write_query)
+> Here's a CSV of our products: [paste CSV data]
+
+### Manage datapacks (triggers datapack_list / datapack_create)
+> List all datapacks.
+
+## Differences from Claude Code
+
+| Feature | Claude Code | Claude Desktop |
+|---------|-------------|----------------|
+| Skill name | `meko-mcp-tools` | `meko-mcp-tools-desktop` |
+| Installation | `claude plugin install meko-agent-skills` | Plugin marketplace / .skill file / manual |
+| MCP connection | `claude mcp add --transport http meko <url>` | `claude_desktop_config.json` |
+| Automatic capture | Hooks (SessionStart, PreCompact, SessionEnd) | Manual — ask to save conversations |
+| Periodic checkpoints | CronCreate (every 10 min) | Not available |
+| agent_id | `agent` | `agent` |
+
+## Troubleshooting
+
+### "Tools aren't available"
+
+1. Check that `claude_desktop_config.json` has valid JSON syntax
+2. Restart Claude Desktop after editing the config
+3. Check logs at `~/Library/Logs/Claude` (macOS) or `%APPDATA%\Claude\Logs` (Windows)
+
+### "Connection refused"
+
+Ensure the MCP server is running:
+- For docker-compose: `docker compose ps` — the `meko-mcp` service should be healthy
+- For stdio: the server starts automatically when Claude Desktop launches
+
+### "memory_add fails with SQL syntax error"
+
+On Cloud Meko, `agent_id` is a row-level column value — any string works, it never becomes a PostgreSQL identifier. Use `agent_id="claude_desktop"` for this client (or the value the skill tells you to use). Empty / missing `agent_id` is NOT rejected — the server resolves it to `meko_agent` (the cross-project common bucket). That's rarely what you want for Desktop, so always pass `agent_id="claude_desktop"` explicitly to keep this client's writes in the right bucket.
+
+### "Conversation tools don't work"
+
+Conversation tools require Langfuse credentials (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`). The other 19 tools work without Langfuse. If you don't need conversation persistence, you can skip this.
+
+### "Skill doesn't trigger"
+
+The skill activates when Claude detects relevant context (MCP tools, memory operations, database queries, etc.). If it doesn't trigger:
+1. Verify the skill appears in Customize > Skills and is enabled
+2. Try a more explicit prompt: "Use the Meko tools to store this in memory: I prefer Python."

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

@@ -0,0 +1,24 @@
+---
+title: Section Index
+description: Maps reference files to their topics for the meko-mcp-tools-desktop skill
+---
+
+# Reference Sections
+
+## Tool Selection & Catalog
+- [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-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
+- [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message, plus Desktop capture guidance
+- [tools-rag-workflow.md](tools-rag-workflow.md) — End-to-end RAG pipeline: source registration, index creation, status polling
+
+## Safety & Permissions
+- [tools-scope-permissions.md](tools-scope-permissions.md) — read/write/admin permission hierarchy and per-tool requirements
+
+## Practical Usage
+- [tools-cookbook.md](tools-cookbook.md) — Per-tool examples with correct parameters, expected responses, and common errors
+
+## Troubleshooting & Limitations
+- [tools-troubleshooting.md](tools-troubleshooting.md) — Error recovery, retry strategies, stuck pipeline diagnosis
+- [tools-known-limitations.md](tools-known-limitations.md) — Broken tools, missing capabilities, permission gaps

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

@@ -0,0 +1,99 @@
+# agent_id — multi-agent identity on Cloud Meko
+
+`agent_id` identifies **which agent wrote a memory or created a conversation**. It is not a constant. Pick a value that represents the specific agent + project you're acting for, use it consistently for writes within this session, and use it to scope your own reads.
+
+The Cloud UI (`cloud.mekodata.ai`) renders `agent_id` as a badge on every memory and conversation row — so the value you pick is user-visible. Multiple different agents with different `agent_id` values can write into the same datapack; each one's personal view is scoped to itself, and the UI shows the full cross-agent picture.
+
+## The three buckets
+
+Memories segregate strictly by `agent_id`. Pick the right bucket up front:
+
+| Pattern | When to use | Example |
+|---|---|---|
+| Loose client name | Claude Desktop and other non-coding clients — there's no per-project concept, so the bare client name is the right granularity. | `claude_desktop` |
+| `<client>:<repo-basename>` | Coding agents (Claude Code, Cursor) writing project-scoped facts. **Not used by Claude Desktop**, but you'll see these values on rows written by other clients in the same datapack. | `claude_code:meko-mcp-server` |
+| `meko_agent` | Cross-project common bucket — facts any agent should see regardless of project (user identity, global preferences). The server stores empty/missing `agent_id` here automatically. | `meko_agent` |
+
+**For Claude Desktop, the practical default is `claude_desktop` for personal context and `meko_agent` for genuinely cross-client facts.** When the user's information is project-agnostic ("the user is named Amiram", "the user prefers vim"), prefer `meko_agent` so other clients (Claude Code, Cursor) can see it too.
+
+## Valid characters
+
+The server stores `agent_id` as a row-level column value — it never becomes a PostgreSQL identifier on Cloud. Any printable string works: colons, hyphens, dots, underscores, spaces. Stay within what's readable in the UI badge.
+
+Pre-existing data in real datapacks includes a mix of legacy shapes — `agent`, `claude-code`, `claude_code`, `cursor:<slug>`, `claude-code:-Users-...`, `claude-desktop` (hyphenated). None of them cause errors. To query those rows, pass the literal legacy value as `agent_id`. New writes should follow the table above.
+
+## 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-client facts; not what you want for desktop-personal 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_desktop"` returns only rows whose stored value is exactly that. Memories written from `agent_id="claude_code:foo"` are invisible to it.
+- An empty `agent_id` is rewritten to `meko_agent` server-side, so a "broad" read with empty string returns only common-bucket rows — **not** a cross-client fan-out. To search across multiple agent_ids, call once per known value.
+
+Empirically verified 2026-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
+
+```
+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=...)
+```
+
+- **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.
+
+## When to use what — broad-query guidance
+
+If the user asks "what do you know about X?" and you want to maximize recall:
+
+1. **First call**: `memory_search(agent_id="claude_desktop", query="X")` — returns your desktop-personal memories.
+2. **Second call**: `memory_search(agent_id="meko_agent", query="X")` — returns the common cross-project bucket: anything written with `agent_id="meko_agent"` from any client, plus rows the server stored under that name when called with empty `agent_id`.
+3. **Third call**: `knowledgebase_search(agent_id="<anything>", datapack_id="<datapack>", query="X")` — returns team-shared knowledge. Useful when the answer may have been promoted by the user or a teammate.
+
+For a true cross-agent fan-out (e.g. you also want to see what was written from `claude_code:some-repo` or `cursor:foo`), call `memory_search` once per known agent_id — the empty-string shortcut does not bypass the filter; the server rewrites empty to `meko_agent`.
+
+Always tell the user what scope you searched, so they understand why the answer is or isn't there. Example wording: "I found this in your desktop personal memories" vs. "I found this in your common cross-project bucket" vs. "I found this in your team's shared knowledge."
+
+## Sub-scoping within an agent
+
+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 Desktop; 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 in the coding-agent skill.