@yugabytedb/meko-mcp 1.1.0 → 2.0.0

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

@@ -0,0 +1,327 @@
+# Tool Cookbook — Complete Usage Examples
+
+Every tool example below shows the correct parameters, expected response, and common errors. Use `scope="read"` for reads and `scope="write"` for writes — never `"all"` or any other value.
+
+> **Note on `agent_id` in the examples below.** The string `"agent"` appears in these examples as a placeholder shorthand; it is NOT a required constant. Substitute **your** client's bucket: for Claude Desktop, the bare client name `claude_desktop`; for Claude Code/Cursor, `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts (user identity, global preferences) write/read with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
+
+---
+
+## Memory Tools
+
+**Critical:** Pass your session's `agent_id` on every memory call. For Claude Desktop that's `claude_desktop` for client-personal context, or `meko_agent` for genuinely cross-project facts (user identity, global preferences). Personal writes are scoped strictly by `agent_id` — other agents won't see your writes on personal reads unless they pass the same exact value.
+
+### memory_add
+
+**When to use:** NOT for facts the user states — those are captured when you post the turn with `conversation_add_message` and the server extracts them. Reserve `memory_add` for the three cases per-turn capture can't reach: (1) the user explicitly says "remember this"; (2) a durable fact only in your output or a tool result, never in a user turn; (3) overwriting a negated/corrected fact (pair with `memory_delete_by_id`, since extraction is additive).
+
+```
+memory_add(scope="write", agent_id="claude_desktop",
+    text="Remember: deploy scripts must be run from the repo root, never a subdir.")
+```
+
+**Response:**
+```json
+{"results": [{"id": "mem-uuid-123", "memory": "User Amiram is VP of Product at YugabyteDB. Prefers concise responses."}]}
+```
+
+**With user scoping:**
+```
+memory_add(scope="write", agent_id="agent", user_id="amiram",
+    text="Prefers Python for backend, Go for infrastructure.")
+```
+
+**What NOT to store via memory_add:**
+- Full conversations (use `conversation_create` + `conversation_add_message`)
+- Large documents (use the UI's Datapack → Actions → Add Knowledge upload flow)
+
+**Common errors:**
+- `syntax error at or near "-"` — legacy error from the pre-multi-tenancy schema when `agent_id` became part of a PostgreSQL identifier. No longer applies on Cloud (agent_id is a TEXT column value, any string is accepted). If you hit it on a deployment that still uses the old schema, use underscores instead of hyphens.
+- `connection already closed` — Retry once. If it fails again, the memory subsystem is down.
+
+---
+
+### memory_search
+
+**When to use:** Find relevant memories by meaning. Always try this before asking the user to repeat information.
+
+```
+memory_search(scope="read", query="What programming language does the team use?", agent_id="agent")
+```
+
+**Response:**
+```json
+{"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
+```
+
+**With limit:**
+```
+memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
+```
+
+---
+
+### memory_get_all
+
+**When to use:** List everything stored for an agent. Useful at session start to load context.
+
+```
+memory_get_all(scope="read", agent_id="agent")
+```
+
+**With user scoping:**
+```
+memory_get_all(scope="read", agent_id="agent", user_id="amiram")
+```
+
+---
+
+### memory_get_by_id
+
+```
+memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
+```
+
+---
+
+### memory_update
+
+**When to use:** Overwrite a specific memory's text. Requires the memory UUID.
+
+```
+memory_update(scope="write", memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="agent")
+```
+
+---
+
+### memory_delete_by_id
+
+```
+memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="agent")
+```
+
+---
+
+### memory_delete_all
+
+**Destructive. Requires admin scope.** Deletes all memories for the agent.
+
+```
+memory_delete_all(scope="admin", agent_id="agent")
+```
+
+---
+
+## Conversation Tools
+
+### conversation_create
+
+**When to use:** Start storing a multi-turn exchange. Do this when the session contains valuable dialog worth preserving.
+
+```
+conversation_create(scope="write", agent_id="agent", user_id="amiram",
+    title="Debugging the auth middleware")
+```
+
+**Response:**
+```json
+{"id": "conv-uuid-123", "title": "Debugging the auth middleware"}
+```
+
+---
+
+### conversation_add_message
+
+**When to use:** Add a user/assistant exchange to an existing conversation. **All fields must be verbatim** — never summarize or rephrase.
+
+Pass `index_for_search=True` on substantive turns so this conversation is embedded into the shared conversation-history cache (searchable later via `conversation_search` / `contextual_prominence_search`). This isn't limited to WorkbenchLM — pass it for agent-harness conversations too.
+
+```
+conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    input="Why is the auth middleware returning 401?",
+    output="The token validation is checking the wrong issuer claim...",
+    reasoning="Checked the middleware source, found issuer mismatch between config and JWT...",
+    index_for_search=True)
+```
+
+**With dedup seed (use when client hooks also write to Langfuse):**
+```
+conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    input="Why is the auth middleware returning 401?",
+    output="The token validation is checking the wrong issuer claim...",
+    seed="conv-uuid-123:agent:Why is the auth middleware returning 401?",
+    index_for_search=True)
+```
+
+---
+
+### conversation_get
+
+```
+conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="agent",
+    include_messages=True, limit=50)
+```
+
+---
+
+### conversation_list
+
+```
+conversation_list(scope="read", agent_id="agent", limit=20)
+```
+
+---
+
+### conversation_update
+
+```
+conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    title="Resolved: Auth middleware issuer mismatch")
+```
+
+---
+
+### conversation_delete
+
+**Destructive. Requires admin scope.**
+
+```
+conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="agent")
+```
+
+---
+
+## Knowledge Base Tools
+
+**KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` is the one KB tool exposed via MCP.
+
+See `tools-rag-workflow.md` for the decision table.
+
+### knowledgebase_search
+
+**When to use:** Retrieve chunks from a populated KB. Works on cloud today.
+
+```
+knowledgebase_search(
+    scope="read",
+    query="natural-language question",
+    agent_id="agent",
+    conversation_id="<uuid from conversation_create>",
+    datapack_id="<datapack UUID — REQUIRED here, no default>",
+    limit=10)
+```
+
+Unlike memory tools, `datapack_id` has no default — you must pass it explicitly.
+
+**Response (empty KB, verified 2026-05-07):**
+```json
+{"results": [], "count": 0}
+```
+
+Populated KBs return results with chunk content and similarity scores. An empty/nonexistent KB is not an error — just `count: 0`.
+
+---
+
+## Artifact Tools
+
+### artifact_put
+
+**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
+
+```
+artifact_put(
+    scope="write",
+    filename="analysis_report.csv",
+    content_type="text/csv",
+    content_base64="<base64-encoded bytes>",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop"
+)
+```
+
+**Response:**
+```json
+{
+  "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
+  "filename": "analysis_report.csv",
+  "content_type": "text/csv",
+  "size_bytes": 4096,
+  "stored_in": "db"
+}
+```
+
+Save the `content_hash` — it's the retrieval key for `artifact_get`.
+
+**Common errors:**
+- `invalid_base64` — `content_base64` is not valid base64.
+- `artifact_too_large` — file exceeds 5 MiB (default). Set `MEKO_MAX_ARTIFACT_UPLOAD_BYTES` to raise the limit.
+
+---
+
+### artifact_get
+
+**When to use:** Retrieve a file previously uploaded with `artifact_put`.
+
+**Small files (< 1 MB) — content returned inline:**
+```
+artifact_get(
+    scope="read",
+    content_hash="a665a45920422f9d417e4867efdc4fb8a5f1f89ea5b8440b1ad4c4c6b8a7e4d3",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop"
+)
+```
+
+**Response (inline):**
+```json
+{
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8...",
+  "filename": "analysis_report.csv",
+  "stored_in": "db",
+  "content_base64": "<base64-encoded bytes>"
+}
+```
+
+**Large files (≥ 1 MB) — written to local disk:**
+```json
+{
+  "content_hash": "a665a45920422f9d417e4867efdc4fb8...",
+  "filename": "dataset.parquet",
+  "stored_in": "s3",
+  "local_path": "/Users/you/.meko/artifacts/a665a4.../dataset.parquet"
+}
+```
+
+For large files use `local_path` to read the file. S3 URLs are never exposed.
+
+**Common errors:**
+- `ARTIFACT_NOT_FOUND` — no artifact with that hash in this datapack.
+- `ARTIFACT_EXPIRED` — free-tier TTL has elapsed (30 days of no access).
+
+---
+
+## Datapack Management Tools
+
+### datapack_create / datapack_list / datapack_describe
+
+```
+datapack_create(scope="write", name="analytics_prod")
+datapack_list(scope="read")  # returns datapack_id for each datapack
+datapack_describe(scope="read", datapack_id="<uuid>", include_status=True)
+```
+
+### datapack_update / datapack_delete
+
+```
+datapack_update(scope="write", datapack_id="<uuid>", connection_string="postgresql://...")
+datapack_delete(scope="admin", datapack_id="<uuid>")  # Irreversible!
+```
+
+### Agent and knowledge-base management (NOT MCP — control-plane only)
+
+Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/list/delete agents or KB sources, don't invent a tool call — point them at the control plane:
+
+- REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (agents), `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases` (KB sources).
+- Or the Meko UI at `app.mekodev.com` → Datapacks → agents / knowledge-bases.
+
+KB ingestion specifically lives in the UI today: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). Agents querying a populated index use `knowledgebase_search` — see `tools-rag-workflow.md`.

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

@@ -0,0 +1,63 @@
+# Known Limitations
+
+These are current limitations of the Meko MCP tools. Know them upfront to avoid wasted tool calls.
+
+## No delete tools for RAG artifacts
+
+There are no MCP tools to:
+- Delete a vector index
+- Remove a source from an index
+- Clear stuck work queue entries
+- Reset a failed pipeline
+
+KB-source deletion happens via the Meko control plane (REST: `DELETE /datapacks/:datapack_id/knowledge-bases`, or the UI), which removes the registration from the Meko API — but does **not** touch the actual `dist_rag` index, source records, or vector data in the datapack's database.
+
+**Workaround:** For stuck or failed indexes, create a new index with a different name. Stale indexes remain in the database until manually cleaned up by an admin.
+
+## RAG ingestion is UI-only
+
+KB ingestion (creating an index, adding sources, polling build status) is not exposed via MCP. Documents go in through the Cloud UI's **Add Knowledge** flow (Datapack → Actions → Add Knowledge) — PDF/TXT/MD/JSON/MP4 up to 5 MB each, 10 per batch.
+
+To **query** a built index, use `knowledgebase_search` — it returns both uploaded documents and memories the user promoted from the Learnings tab.
+
+## Memory tools unreliable for structured/tabular data
+
+`memory_add` passes text through Mem0's fact extraction pipeline. This works well for:
+- Facts: "Alice works at Acme Corp"
+- Preferences: "User prefers dark mode"
+- Entity relationships: "Amiram reports to Karthik"
+
+It works **poorly** for:
+- CSV rows or tabular data — columns and rows get dropped
+- Data dictionaries — only partial information extracted
+- Structured schemas — relationships between fields lost
+
+**Structured data is not natively supported via MCP.** The options are:
+
+1. **Write a single narrative summary** as a memory — one call, not row-by-row:
+   ```
+   memory_add(scope="write",
+       agent_id="<your session agent_id>",
+       conversation_id="<session conversation_id>",
+       text="Customer Complaints dataset has fields: Complaint ID (int PK), Date Submitted (date), Product (text, e.g. Mortgage/Credit Card), Sub-product (text), Issue (text), Company Response (text), State (text, 2-letter code), ZIP Code (text)")
+   ```
+2. **Upload the schema doc** through the Cloud UI's **Add Knowledge** flow (Datapack → Actions → Add Knowledge). Accepts PDF/TXT/MD/JSON — convert CSV to MD or JSON first. That makes it queryable via `knowledgebase_search`.
+3. **Tell the user** that structured-data storage via MCP isn't supported and let them decide how to proceed.
+
+Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
+
+## Activation is model-judged on Desktop (no hooks)
+
+Claude Desktop has no lifecycle hooks, so this skill activates only when the model judges it relevant from the skill's `description`. Reliable triggers: recall questions ("what do you know about me"), explicit save requests ("remember this"), and mentions of memory/Meko/datapacks. **Best-effort** triggers: task-shaped prompts where a durable fact appears only in passing ("I'm evaluating pnpm; I already use Turborepo") — the skill may not fire and the turn goes uncaptured. Also, when the model resolves a tool directly via tool search it may call `memory_add`/`memory_search` without reading this skill at all.
+
+The skill description is tuned to its 1024-char ceiling; broadening it further does not close the task-shaped-prompt gap (empirically confirmed in Phase-9 testing). Mitigations, in order of leverage:
+
+1. **Personal-preferences snippet** (always-on) — paste the snippet from the Desktop setup README's "Make Desktop proactive" step into Claude's profile preferences; it is injected into every conversation regardless of prompt shape. This is the only true fix for task-shaped misses.
+2. **Server-side guidance** — the `agent_id` tool docstrings and the server's connect-time instructions name `claude_desktop` as this client's bucket, so even a skill-less tool-search call avoids the wrong-bucket (`claude_code`) write.
+3. Nothing is lost when the *user* explicitly recalls or saves — only passive capture of in-passing facts is best-effort.
+
+## No conversation search
+
+`conversation_list` returns conversations by agent, but there is no semantic search across conversation content. To find a specific past exchange, you need to list conversations and inspect them individually with `conversation_get`.
+
+For finding past knowledge by meaning, use `memory_search` instead — which is why storing key facts via `memory_add` alongside conversations is important.

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

@@ -0,0 +1,214 @@
+# When to Use Memory Tools vs Conversation Tools
+
+**WRONG:** `memory_add(text="User asked about pricing. I explained tiers. User chose Pro.")` — mem0 extracts facts, discarding conversational structure, turn ordering, and reasoning traces.
+
+## Use `memory_add` when storing:
+
+- A **fact**: "User prefers dark mode"
+- A **preference**: "Customer budget is $50k"
+- An **entity relationship**: "Alice works at Acme Corp"
+
+Memory is backed by pgvector (semantic search) and Apache AGE (entity-relationship graph). It retrieves relevant facts by meaning, not by conversation order.
+
+```
+memory_add(scope="write", agent_id="support_bot",
+    text="Customer Alice (alice@acme.com) prefers email, has Pro plan.", user_id="alice_123")
+
+memory_search(scope="read", query="What plan does Alice have?", agent_id="support_bot")
+```
+
+## Use `conversation_create` + `conversation_add_message` when storing:
+
+- A **full dialog exchange** with input/output pairs
+- A **chain-of-thought** reasoning trace alongside the response
+- A **multi-turn chat** where turn order matters
+
+Conversations are backed by Langfuse sessions and traces. They preserve full structure: who said what, in what order, with what reasoning.
+
+```
+conversation_create(scope="write", agent_id="support_bot", user_id="alice_123", title="Pricing discussion")
+-- Returns: {"id": "conv-uuid-here"}
+
+conversation_add_message(scope="write", conversation_id="conv-uuid-here", agent_id="support_bot",
+    input="What are your pricing tiers?",
+    output="We offer Starter ($10/mo), Pro ($50/mo), and Enterprise (custom).",
+    reasoning="Retrieved pricing page data. No special discounts apply.")
+```
+
+## Decision Matrix
+
+| Signal | Tool |
+|--------|------|
+| "remember that...", "note that...", "keep in mind..." | `memory_add` |
+| "store this conversation", "save this chat" | `conversation_create` + `conversation_add_message` |
+| "what do you know about X?", "recall..." | `memory_search` |
+| "show me our past conversation about..." | `conversation_list` + `conversation_get` |
+| "the user prefers...", "their budget is..." | `memory_add` |
+| "save my query and your response" | `conversation_add_message` |
+
+## Verbatim Content Rules for conversation_add_message
+
+**WRONG:** Summarizing or rephrasing content before storing:
+```
+conversation_add_message(...,
+    input="User inquired about database performance",        -- rephrased
+    output="I provided optimization suggestions",            -- summarized
+    reasoning="Analyzed the query and suggested improvements" -- condensed
+)
+```
+
+All three fields — `input`, `output`, and `reasoning` — must contain the **exact, verbatim text**. Never summarize, rephrase, editorialize, or condense any field:
+
+- **`input`**: The user's exact prompt, word for word
+- **`output`**: The assistant's complete response, word for word — including code blocks, formatting, and all detail
+- **`reasoning`**: The full chain-of-thought or internal reasoning trace, unedited
+
+The purpose of conversation storage is to create a faithful, replayable record. A rephrased summary loses the original wording, tone, and detail — making the stored conversation useless for review, debugging, or audit.
+
+## Personal memory vs. team-shared knowledge — the three read paths
+
+Agents on Cloud Meko have three distinct read surfaces. Pick the right one for the question.
+
+| Read path | What it returns | How to call |
+|---|---|---|
+| Your own desktop memories | Memories you wrote under this `agent_id`, filtered by `(datapack_id, user_id, agent_id)` | `memory_search(agent_id="claude_desktop", query="...", ...)` |
+| Cross-project common bucket | Memories any agent (including this one) wrote with `agent_id="meko_agent"` — the empty-default bucket for genuinely cross-project facts | `memory_search(agent_id="meko_agent", query="...", ...)` |
+| Team's shared knowledge | Promoted memories + uploaded documents, visible to every member of the datapack | `knowledgebase_search(agent_id="<anything>", datapack_id="<datapack UUID>", query="...")` — `agent_id` is ignored |
+
+For a true fan-out across other clients' buckets (e.g. also see what was written from `claude_code:some-repo` or `cursor:foo`), call `memory_search` once per agent_id — there's no single-call shortcut. Empty string is rewritten to `meko_agent` server-side; it does not drop the filter.
+
+### How content gets into each surface
+
+- **Personal memories** — written by `memory_add`. Scoped per-user and per-agent from the moment of write. Only the writer sees them via MCP reads.
+- **Team-shared Shared Knowledge** — arrives two ways:
+  1. The **user** (never the agent) promotes a personal memory to Knowledge via the Cloud UI's Learnings tab. That copies the row into the shared `knowledge_base` table with the `user_id` stripped, making it team-wide. Originating `agent_id` is preserved in metadata for provenance.
+  2. The user uploads a file via Datapack → Actions → **Add Knowledge** in the Cloud UI. PDF/TXT/MD/JSON/MP4 up to 5MB each.
+
+  Both show up in `knowledgebase_search`, tagged `metadata_filters.source: "memory"` vs other values so the agent can distinguish provenance in responses.
+
+**No MCP tool promotes to Shared Knowledge.** The agent can flag memories it thinks are worth promoting and suggest the user do it from the UI — but the action is user-initiated.
+
+### When the user asks "what do you know about X?"
+
+A full sweep is three calls (budget for it — each is 2-6 seconds):
+
+```
+memory_search(agent_id="claude_desktop", query="X", conversation_id=..., ...)
+memory_search(agent_id="meko_agent", query="X", conversation_id=..., ...)  # cross-project common bucket
+knowledgebase_search(agent_id="<anything>", datapack_id="<uuid>", query="X", conversation_id=..., ...)
+```
+
+When you answer, be explicit about scope so the user knows why something is or isn't there:
+
+- "I found this in your own desktop memories…"
+- "I found this in your common cross-project bucket (something you or another agent wrote under `meko_agent`)…"
+- "I found this in your team's Shared Knowledge — someone (you or a teammate) promoted it earlier…"
+- "I couldn't find anything in your personal memories. You might want to check the Cloud UI's Memory Summary tab for a cross-agent view."
+
+For a true fan-out across other clients' buckets (e.g. also see what was written from `claude_code:some-repo` or `cursor:foo`), call `memory_search` once per known agent_id — empty string just resolves to `meko_agent`, not a fan-out.
+
+## Memory limitations for structured data
+
+**WRONG:** Using `memory_add` to ingest CSV rows, data dictionaries, or tabular schemas — Mem0 extracts individual facts and may drop columns, rows, or structural relationships.
+
+There is no MCP-side "just put it in a database table" option — raw SQL access isn't part of the MCP surface. Workarounds:
+
+1. **Write a single narrative summary** as a memory: `"The Customer Complaints dataset has fields: Complaint ID (int), Date Submitted (date), Product (text), Sub-product (text), Issue (text)..."` — one call, not row-by-row.
+2. **Suggest the user upload the file** via the Cloud UI's Add Knowledge flow if it's a document (CSV files aren't in the supported list — PDF/TXT/MD/JSON/MP4 are; for CSV, convert to MD or JSON first).
+3. **Never ingest CSV row-by-row** into memory — each row becomes a fragmented fact with lost context.
+
+## Memory Storage: capture the turn, don't proactively memory_add
+
+Do **not** proactively `memory_add` facts the user states. On Claude Desktop, post each substantive turn with `conversation_add_message` and the server extracts durable memories from it automatically — personal info, team conventions, domain knowledge, and corrections the user states are all captured that way. A separate `memory_add` just duplicates what extraction produces.
+
+Explicit `memory_add` is reserved for the three cases per-turn capture can't reach:
+
+- **Explicit request** → the user says "remember this" / "save this."
+- **Output-only / tool-derived fact** → a durable fact only in your output or a tool result, never in a user turn (extraction reads the user side of the turn).
+- **Overwriting correction** → a prior fact was negated and the stale memory must not survive. Extraction is additive, so `memory_search` for the old memory and `memory_update` / `memory_delete_by_id`.
+
+Use `memory_search` at the start of sessions to recall what you already know before asking the user to repeat themselves.
+
+## Using Both Together
+
+Posting the turn does both jobs: it preserves the full conversation (structure) and feeds the extractor (searchable memory). Add an explicit `memory_add` only for the three cases above.
+
+## Key Retrieval Difference
+
+- `memory_search`: **semantic similarity** across all memories via pgvector. Returns relevant facts regardless of when stored.
+- `conversation_get`: **ordered list of message turns** for a specific conversation. No semantic search. Requires `conversation_id`.
+
+## Conversation Capture (Desktop: agent-driven)
+
+Claude Desktop has **no capture hooks** — you are the capture mechanism. Post each substantive turn with `conversation_add_message`, and the server extracts memories from the posted turns automatically (extraction runs inside `conversation_add_message`). Coding clients like Claude Code get the same effect from SessionStart / PreCompact / SessionEnd hooks; on Desktop it's your responsibility per turn.
+
+### What to capture
+
+The full transcript including:
+- **User prompts** — verbatim text (the `input` field)
+- **Assistant responses** — all text blocks (the `output` field)
+- **Tool calls** — tool name + input parameters (the `reasoning` field)
+- **Tool results** — output from tool executions (appended to `reasoning`)
+
+This is more than just text — tool calls and results are critical context for session replay, cross-agent sharing, and compaction.
+
+### Seed-based deduplication
+
+Each message's seed is `<conversation_id>:<user_message_uuid>`. All three capture mechanisms generate the same seed for the same exchange, producing the same deterministic trace ID via `sha256(seed)[:16].hex()`. This means duplicate writes from overlapping captures are idempotent.
+
+### When to manually store conversations
+
+Automatic capture handles the raw exchange. You should still manually use `conversation_create` + `conversation_add_message` when:
+- The user explicitly asks to "save this conversation"
+- You want to add curated `reasoning` traces beyond raw tool calls
+- You want to store a selected subset of the conversation with a descriptive title
+
+### Watermark coordination
+
+A shared watermark file at `~/.claude/meko-capture/<session-id>.watermark.json` tracks what has been saved. Both hooks and the agent's periodic checkpoint use this to avoid reprocessing already-captured exchanges.
+
+## Observability: conversation_id IS the Langfuse trace ID
+
+This is the feature agents tend to miss. Verified live 2026-05-07 in the Meko UI's Observe hub.
+
+- `conversation_create` returns a `conversation_id` (e.g. `d71fc8b61a7f45d585eea9a6436e0c3f`).
+- That ID is also the **Langfuse trace_id** for the conversation. Not a separate trace — literally the same identifier.
+- Every subsequent MCP tool call made while passing that `conversation_id` becomes a **span under that trace**, named after the tool: `Memory Add (Meko MCP)`, `Memory Search (Meko MCP)`, `Knowledgebase Search (Meko MCP)`, `Conversation Add Message (Meko MCP)`, etc.
+- Child spans reveal internals. Observed structure:
+  - `memory_add`: `Memory Add (Meko MCP)` → `Create a new memory in Mem0` → `Bulk Payload Update (yugabytedb / vector)` → `Execute Query (yugabytedb / vector)`
+  - `memory_search`: `Memory Search (Meko MCP)` → `Search for memories based on a query in Mem0` (Retriever)
+  - `conversation_add_message`: `Conversation Add Message (Meko MCP)` → `Conversation Message Added` span → `Reasoning` generation (the `reasoning` field is stored as a Langfuse *generation*-typed span, not a plain text field)
+  - `knowledgebase_search`: `Knowledgebase Search (Meko MCP)` → multiple `Execute Query (yugabytedb)` child spans
+- Trace tags include `agent:<agent_id>` and the Meko org UUID. Both are searchable/filterable in Langfuse.
+- Each datapack has its own Langfuse project — traces for a tool call land in the project for whichever `datapack_id` was on the call (or the default datapack if omitted).
+
+### Finding a trace in the UI
+
+Two navigation paths, both verified in the Meko UI:
+
+1. **Datapack → Conversations tab** — every row has an **Open in Observe** button that deep-links to the trace with `session=<conversation_id>` pre-filled. Fastest when you know which conversation to inspect.
+2. **Observe hub** — browse all traces across a datapack. URL shape: `/observe-hub?project=<langfuse_project_id>&session=<conversation_id>`.
+
+The Conversations-tab row preview shows the first user turn verbatim, plus the agent_id tag, message count, and started-at timestamp. If you want a conversation to be recognizable in the UI, call `conversation_add_message` with a clean first-turn `input` early in the session.
+
+### Observed latencies on prod (2026-05-07)
+
+From real traces, not the docstring happy path:
+
+| Tool | Latency per call |
+|---|---|
+| `memory_add` | 12-21 seconds (calls OpenAI for extraction, then writes to vector + graph) |
+| `memory_search` | 1.8-5.9 seconds |
+| `knowledgebase_search` | 0.6 seconds (empty index; will grow with index size) |
+| `conversation_add_message` | 0.11 seconds (fire-and-forget; queued to Langfuse) |
+
+`memory_add` is the expensive one. If you're capturing a long conversation, batch through `conversation_add_message` (cheap, queued) and let the server-side Mem0 extractor handle the heavy lifting on its own schedule, rather than firing `memory_add(messages=...)` per turn.
+
+### Proactive diagnostic pattern
+
+If a user reports "my memory_add didn't seem to save", open the Observe hub for their datapack, filter on their `conversation_id`, and look at the span tree. You will see either:
+
+- A `Memory Add (Meko MCP)` span with `Create a new memory in Mem0` child → the call reached Mem0. The fact extractor may have returned `"results": []` (common on short or non-fact-shaped text; not a bug, but lossy).
+- No span at all → the call never reached the server. Likely a transport / auth / `conversation_id` mismatch issue.
+
+The mem0 extractor is lossy — it extracts atomic facts and graph triples, and may drop prose that doesn't look fact-shaped to it. Observed 2026-05-07: 2 of 5 `memory_add` calls returned `"results": []` and only the graph side landed. When preserving authoritative text matters, store it via `conversation_add_message` (verbatim in `input`/`output`/`reasoning`) — the conversation path preserves text without LLM re-extraction.