@yugabytedb/meko-mcp 1.0.3

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

@@ -0,0 +1,373 @@
+# 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 examples use `agent_id="claude_code"` for readability, but `agent_id` is a **per-user namespace**, not a per-tool label. At runtime, use the value you discovered via `db_summarize_database` at session start (see the main SKILL.md). Substitute it anywhere you see `claude_code` in the examples. Issue [#10](https://github.com/amiramm/meko-mcp-server/issues/10) tracks the eventual schema fix.
+
+---
+
+## Database Tools
+
+### db_summarize_database
+
+**When to use:** First thing in a session to understand what's in the database. Prefer this over writing your own `information_schema` query.
+
+```
+db_summarize_database(scope="read", schema="public")
+```
+
+**Response:**
+```json
+[
+  {
+    "table_name": "customers",
+    "schema": [
+      {"column_name": "id", "data_type": "uuid"},
+      {"column_name": "name", "data_type": "text"}
+    ],
+    "row_count": 1523
+  }
+]
+```
+
+**With datapack:**
+```
+db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
+```
+
+**Common errors:**
+- `Insufficient scope: 'all'` — Use `scope="read"`, not `"all"`
+- Empty result — The schema may not exist, try `schema="public"`
+
+---
+
+### db_run_read_only_query
+
+**When to use:** Any SELECT query. Always add `LIMIT` on exploratory queries.
+
+```
+db_run_read_only_query(scope="read", query="SELECT id, name FROM customers LIMIT 10")
+```
+
+**Response:** JSON array of row objects.
+```json
+[{"id": "abc-123", "name": "Alice"}, {"id": "def-456", "name": "Bob"}]
+```
+
+**Best practices:**
+- Always use `LIMIT` on unfamiliar tables to avoid flooding context
+- Select specific columns rather than `SELECT *` to keep responses small
+- For non-public schemas: `SELECT * FROM analytics."monthly_revenue" LIMIT 5`
+- Escape single quotes in values: `WHERE name = 'O''Brien'`
+
+**Common errors:**
+- `cannot execute INSERT in a read-only transaction` — Use `db_run_write_query` for writes
+- `permission denied for table X` — MCP user lacks access to this table (server-side config issue, not fixable via MCP)
+- `connection already closed` — Retry once. If persistent, the DB pool is unhealthy.
+
+---
+
+### db_run_write_query
+
+**When to use:** INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE INDEX.
+
+```
+db_run_write_query(scope="write", query="INSERT INTO customers (id, name) VALUES ('abc-123', 'Alice')")
+```
+
+**Response:**
+```json
+{"rows_affected": 1}
+```
+
+**One statement per call.** This is wrong:
+```
+db_run_write_query(scope="write", query="CREATE TABLE a (id INT); CREATE TABLE b (id INT);")
+```
+Split into two separate calls.
+
+**Bulk inserts:** Maximum 1000 rows per INSERT VALUES. For more, use `INSERT ... SELECT` or batch into multiple calls.
+
+**Common errors:**
+- `Multi-statement queries not allowed` — Send one statement per call
+- `DROP SCHEMA is not allowed` — See `tools-write-guardrails.md` for blocked operations
+- `'dict' object has no attribute 'guardrail_config'` — Known server bug in some deployments. Write operations may be unavailable.
+
+---
+
+## Memory Tools
+
+**Critical:** `agent_id` must not contain hyphens. Use `"claude_code"`, not `"claude-code"`.
+
+### memory_add
+
+**When to use:** Store facts, preferences, user profile info, org conventions, corrections, learnings. Use proactively — don't wait for the user to ask.
+
+```
+memory_add(scope="write", agent_id="claude_code",
+    text="User Amiram is VP of Product at YugabyteDB. Prefers concise responses.")
+```
+
+**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="claude_code", user_id="amiram",
+    text="Prefers Python for backend, Go for infrastructure.")
+```
+
+**What NOT to store via memory_add:**
+- CSV rows or tabular data (use `db_run_write_query` instead)
+- Full conversations (use `conversation_create` + `conversation_add_message`)
+- Large documents (use knowledge base ingestion)
+
+**Common errors:**
+- `syntax error at or near "-"` — Your `agent_id` contains a hyphen. Use underscores.
+- `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="claude_code")
+```
+
+**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="claude_code", 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="claude_code")
+```
+
+**With user scoping:**
+```
+memory_get_all(scope="read", agent_id="claude_code", user_id="amiram")
+```
+
+---
+
+### memory_get_by_id
+
+```
+memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="claude_code")
+```
+
+---
+
+### 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="claude_code")
+```
+
+---
+
+### memory_delete_by_id
+
+```
+memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="claude_code")
+```
+
+---
+
+### memory_delete_all
+
+**Destructive. Requires admin scope.** Deletes all memories for the agent.
+
+```
+memory_delete_all(scope="admin", agent_id="claude_code")
+```
+
+---
+
+## 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="claude_code", 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.
+
+```
+conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="claude_code",
+    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...")
+```
+
+**With dedup seed (use when client hooks also write to Langfuse):**
+```
+conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="claude_code",
+    input="Why is the auth middleware returning 401?",
+    output="The token validation is checking the wrong issuer claim...",
+    seed="conv-uuid-123:claude_code:Why is the auth middleware returning 401?")
+```
+
+---
+
+### conversation_get
+
+```
+conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="claude_code",
+    include_messages=True, limit=50)
+```
+
+---
+
+### conversation_list
+
+```
+conversation_list(scope="read", agent_id="claude_code", limit=20)
+```
+
+---
+
+### conversation_update
+
+```
+conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="claude_code",
+    title="Resolved: Auth middleware issuer mismatch")
+```
+
+---
+
+### conversation_delete_message
+
+```
+conversation_delete_message(scope="write", conversation_id="conv-uuid-123",
+    agent_id="claude_code", trace_id="trace-uuid-456")
+```
+
+---
+
+### conversation_delete
+
+**Destructive. Requires admin scope.**
+
+```
+conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="claude_code")
+```
+
+---
+
+## RAG / Knowledge Base Tools
+
+### knowledgebase_trigger_index_creation
+
+**When to use:** Create a new vector index from source URIs. This is the only way to start a RAG pipeline.
+
+```
+knowledgebase_trigger_index_creation(scope="write",
+    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
+    index_name="company_docs")
+```
+
+**Response:**
+```json
+{"source_ids": ["src-uuid-1", "src-uuid-2"], "index_name": "company_docs", "status": "build_triggered"}
+```
+
+**Optional parameters:**
+- `ai_provider="OPENAI"` (default)
+- `embedding_model="text-embedding-3-large"` (default)
+- `embedding_dimensions=1536` (default)
+- `chunk_size=1024` (default)
+- `chunk_overlap=256` (default)
+- `datapack_id=None`
+
+**Warning:** Each call creates a new index. Do NOT retry on failure — you'll get duplicate indexes (e.g., `docs_v1`, `docs_v2`, `docs_v3`).
+
+---
+
+### knowledgebase_check_index_status
+
+**When to use:** Poll for build completion after triggering creation.
+
+```
+knowledgebase_check_index_status(scope="read", index_name="company_docs")
+```
+
+**Polling strategy:** Check every 1-2 minutes. If `pipeline_details` is empty or documents remain at `INIT` for more than 5 minutes, the pipeline is likely stuck. Stop polling after 3 consecutive no-progress checks — see `tools-troubleshooting.md`.
+
+---
+
+### knowledgebase_add_source_to_index
+
+**Known bug:** This tool has a parameter mismatch (`r_index_name` vs `r_index_id`) and may fail. Prefer `knowledgebase_trigger_index_creation` with all sources at once instead.
+
+```
+knowledgebase_add_source_to_index(scope="write", index_name="company_docs",
+    source_id="src-uuid-new")
+```
+
+---
+
+## Datapack Management Tools
+
+### datapack_create / datapack_list / datapack_describe
+
+```
+datapack_create(scope="write", name="analytics_prod")
+datapack_list(scope="read")
+datapack_describe(scope="read", name="analytics_prod", include_status=True)
+```
+
+### datapack_update / datapack_delete
+
+```
+datapack_update(scope="write", name="analytics_prod", connection_string="postgresql://...")
+datapack_delete(scope="admin", name="analytics_prod")  # Irreversible!
+```
+
+### Agent management within datapacks
+
+```
+datapack_create_agent(scope="write", datapack_name="analytics_prod", agent_name="analytics_bot")
+datapack_list_agents(scope="read", datapack_name="analytics_prod")
+datapack_delete_agent(scope="admin", datapack_name="analytics_prod", agent_name="analytics_bot")
+```
+
+### Knowledge base source management within datapacks
+
+```
+datapack_add_knowledge_base(scope="write", datapack_name="analytics_prod", url="s3://data/reports/")
+datapack_list_knowledge_bases(scope="read", datapack_name="analytics_prod")
+datapack_delete_knowledge_base(scope="admin", datapack_name="analytics_prod", url="s3://data/reports/")
+```
+
+**Note:** `datapack_delete_knowledge_base` removes the source registration from the Meko API. It does NOT delete the actual vector index, source records, or vector data from the database.

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

@@ -0,0 +1,56 @@
+# Datapack Lifecycle and datapack_id Routing
+
+**WRONG:** Creating a datapack then calling `db_summarize_database(scope="read")` without `datapack_id` — this queries the DEFAULT database, not the datapack.
+
+## Always pass datapack_id for datapack-scoped operations
+
+```
+datapack_create(scope="write", name="analytics_prod")
+-- Returns: {"id": "dp-uuid-123", ...}
+
+db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
+db_run_read_only_query(scope="read", query="SELECT * FROM customers LIMIT 10", datapack_id="dp-uuid-123")
+```
+
+## How datapack_id routing works
+
+1. When `datapack_id` is **omitted**: uses the default pool from `YUGABYTEDB_URL`
+2. When `datapack_id` is **provided**: resolves connection string via Meko API, creates/reuses a cached pool for that datapack
+
+## Which tools accept datapack_id?
+
+All **Database**, **RAG**, and **Memory** tools accept `datapack_id`.
+
+**Conversation** tools do NOT — they always use Langfuse.
+**Datapack management** tools do NOT — they operate on the Meko API itself.
+
+## How to obtain a datapack_id
+
+- From `datapack_create` response (`"id"` field)
+- From `datapack_list` (each entry has `"id"`)
+- From `datapack_describe` response
+
+## Datapack lifecycle
+
+### Creation and setup
+
+```
+datapack_create(scope="write", name="sales_analytics")
+datapack_create_agent(scope="write", datapack_name="sales_analytics", agent_name="sales_agent")
+datapack_add_knowledge_base(scope="write", datapack_name="sales_analytics", url="s3://company-docs/sales/")
+db_run_write_query(scope="write", query="CREATE TABLE leads (...)", datapack_id="dp-uuid-from-step-1")
+```
+
+### Teardown (requires admin scope)
+
+Delete child resources before the datapack:
+
+```
+datapack_delete_knowledge_base(scope="admin", datapack_name="sales_analytics", url="s3://company-docs/sales/")
+datapack_delete_agent(scope="admin", datapack_name="sales_analytics", agent_name="sales_agent")
+datapack_delete(scope="admin", name="sales_analytics")
+```
+
+## Common mistake: mixing default and datapack databases
+
+If you created a table with a `datapack_id`, always query it with the same `datapack_id`. Creating in default DB and querying in a datapack (or vice versa) will fail with "table not found".

package/assets/skills/meko-mcp-tools/references/tools-db-query-patterns.md

@@ -0,0 +1,38 @@
+# Read-Only vs Write Query Execution Patterns
+
+**WRONG:** `db_run_write_query(scope="write", query="SELECT * FROM users")` — requires write scope unnecessarily, triggers guardrail validation, returns `{"rows_affected": -1}` instead of data.
+**WRONG:** `db_run_read_only_query(scope="read", query="INSERT INTO ...")` — fails: "cannot execute INSERT in a read-only transaction."
+
+## How Each Tool Works
+
+**`db_run_read_only_query`:** `BEGIN READ ONLY` → execute → `ROLLBACK`. Returns JSON array of row objects.
+
+**`db_run_write_query`:** Guardrail validation → execute → `COMMIT`. Returns `{"rows_affected": N}`.
+
+## When to Use db_summarize_database
+
+Use instead of writing your own `information_schema` query when you need a table overview:
+
+```
+db_summarize_database(scope="read", schema="public")
+-- Returns table names, column schemas, AND row counts in one call
+```
+
+## SQL Best Practices
+
+**Schema qualification:** For non-public schemas, use `analytics."monthly_revenue"` and pass `schema="analytics"` to `db_summarize_database`.
+
+**String escaping:** Queries are passed directly to `cur.execute()` — no parameter placeholders. Escape values in SQL: `WHERE name = 'O''Brien'`.
+
+**LIMIT on exploratory queries:**
+```
+db_run_read_only_query(scope="read", query="SELECT * FROM large_table LIMIT 25")
+```
+
+**Batch large writes:** Due to the 1000-row INSERT cap, split large inserts. Or use `INSERT ... SELECT` for unlimited rows from an existing table.
+
+**One statement per call:**
+```
+WRONG: "CREATE TABLE a (id INT); CREATE TABLE b (id INT);"
+RIGHT: Two separate db_run_write_query calls
+```

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

@@ -0,0 +1,61 @@
+# 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
+
+The `datapack_delete_knowledge_base` tool only removes the KB source **registration** from the Meko API. It does NOT touch the actual `dist_rag` index, source records, or vector data in the 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.
+
+## No MCP tool to query a built RAG index
+
+The RAG tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) handle index **creation and monitoring** only.
+
+To actually **query** a built index, use `db_run_read_only_query` with `dist_rag` SQL functions directly. The specific query syntax depends on the `dist_rag` extension API.
+
+## 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
+
+**Use instead:** `db_run_write_query` to CREATE TABLE and INSERT the data as proper database rows. Then query it with `db_run_read_only_query`.
+
+If you must store a schema overview in memory, write a single narrative summary:
+```
+memory_add(scope="write", agent_id="claude_code",
+    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)")
+```
+
+## MCP user permission gaps
+
+The MCP database user may not have read access to all tables within a datapack, particularly:
+- Data tables created by the provisioning system
+- Tables in non-public schemas
+
+If `db_run_read_only_query` returns "permission denied", this is a server-side configuration issue. Use `db_summarize_database` to see which tables are accessible.
+
+## Currently broken tools
+
+**`db_run_write_query`** — May fail with `'dict' object has no attribute 'guardrail_config'` in some deployments. When this happens, all write operations are blocked for the session.
+
+**`knowledgebase_add_source_to_index`** — SQL parameter mismatch: tool passes `r_index_name` (string) but the DB function expects `r_index_id` (UUID). Workaround: use `knowledgebase_trigger_index_creation` with all sources at once.
+
+## 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/references/tools-memory-vs-conversation.md

@@ -0,0 +1,128 @@
+# 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.
+
+## 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.
+
+For tabular data, prefer:
+1. **Create a table** via `db_run_write_query` and insert the data as rows — preserves all structure
+2. **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
+3. **Never ingest CSV row-by-row** into memory — each row becomes a fragmented fact with lost context
+
+## Proactive Memory Storage
+
+Don't wait for the user to say "remember this." Store context proactively when you detect:
+
+- **Personal info** → `memory_add`: "User is VP of Product, prefers concise responses"
+- **Team conventions** → `memory_add`: "Team uses Python for backend, Go for infrastructure"
+- **Domain knowledge** → `memory_add`: "Meko traces are decision traces that capture how and why decisions were made"
+- **Corrections** → `memory_add`: "User corrected: always use 'resilience' instead of 'high availability'"
+
+Use `memory_search` at the start of sessions to recall what you already know before asking the user to repeat themselves.
+
+## Using Both Together
+
+A common pattern: store the full conversation (preserves structure) AND extract key facts with `memory_add` (enables semantic search later).
+
+## 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`.
+
+## Automatic Conversation Capture
+
+The Meko plugin captures conversations automatically via three mechanisms:
+
+1. **Periodic checkpoint (~10 min)** — Agent-driven via CronCreate, uses `conversation_add_message` MCP tool directly
+2. **PreCompact hook** — Shell script that fires before Claude Code's auto-compaction, captures via MCP JSON-RPC
+3. **SessionEnd hook** — Shell script that fires at session termination, captures final exchanges
+
+### What gets captured
+
+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.