@yugabytedb/meko-mcp 1.0.3

package/assets/hooks-handlers/lib/checkpoint-timer.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * checkpoint-timer.js — Background daemon for periodic conversation capture.
+ *
+ * Spawned by session-start.sh at session start. Runs capture.js in checkpoint
+ * mode every MEKO_CHECKPOINT_INTERVAL seconds (default: 600 = 10 minutes).
+ *
+ * Writes PID to ~/.claude/meko-capture/<session-id>.timer.pid for cleanup
+ * by session-end.sh.
+ *
+ * Usage: node checkpoint-timer.js <transcript_path>
+ *
+ * Environment:
+ *   MEKO_CHECKPOINT_INTERVAL  Seconds between ticks (default: 600)
+ *   MEKO_WATERMARK_DIR        Watermark directory (default: ~/.claude/meko-capture)
+ *   MEKO_MCP_URL              Inherited by capture.js
+ *   MEKO_API_KEY              Inherited by capture.js
+ */
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const INTERVAL_SECS = parseInt(process.env.MEKO_CHECKPOINT_INTERVAL || "600", 10);
+const WATERMARK_DIR =
+  process.env.MEKO_WATERMARK_DIR ||
+  path.join(process.env.HOME || "~", ".claude", "meko-capture");
+
+const transcriptPath = process.argv[2];
+if (!transcriptPath) {
+  process.stderr.write("[meko-timer] Usage: checkpoint-timer.js <transcript_path>\n");
+  process.exit(1);
+}
+
+const sessionId = path.basename(transcriptPath, ".jsonl");
+const pidFile = path.join(WATERMARK_DIR, `${sessionId}.timer.pid`);
+const captureScript = path.join(__dirname, "capture.js");
+
+// Write PID file
+fs.mkdirSync(WATERMARK_DIR, { recursive: true });
+fs.writeFileSync(pidFile, String(process.pid));
+
+function cleanup() {
+  try { fs.unlinkSync(pidFile); } catch { /* already gone */ }
+  process.exit(0);
+}
+
+process.on("SIGTERM", cleanup);
+process.on("SIGINT", cleanup);
+
+function tick() {
+  // Skip if transcript doesn't exist (session ended but we weren't killed yet)
+  if (!fs.existsSync(transcriptPath)) {
+    cleanup();
+    return;
+  }
+
+  const hookInput = JSON.stringify({ transcript_path: transcriptPath });
+
+  try {
+    execFileSync("node", [captureScript, "checkpoint"], {
+      input: hookInput,
+      timeout: 30000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err) {
+    // Best-effort: log and continue
+    process.stderr.write(`[meko-timer] Checkpoint tick failed: ${err.message}\n`);
+  }
+}
+
+setInterval(tick, INTERVAL_SECS * 1000);

package/assets/hooks-handlers/pre-compact.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# PreCompact hook — delegates to Node.js capture script.
+exec node "$(dirname "$0")/lib/capture.js" pre-compact

package/assets/hooks-handlers/session-end.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# SessionEnd hook — kills the checkpoint timer, then delegates to capture.js
+# for a final transcript capture.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Read stdin into variable (need it for both timer cleanup and capture.js)
+HOOK_INPUT="$(cat)"
+
+# Extract transcript_path and kill checkpoint timer
+TRANSCRIPT_PATH="$(printf '%s' "$HOOK_INPUT" | node -e '
+  const d = JSON.parse(require("fs").readFileSync(0,"utf-8"));
+  const p = d.transcript_path || (d.hookSpecificInput||{}).transcript_path || "";
+  process.stdout.write(p);
+' 2>/dev/null)"
+
+if [ -n "$TRANSCRIPT_PATH" ]; then
+  SESSION_ID="$(basename "$TRANSCRIPT_PATH" .jsonl)"
+  PID_FILE="${MEKO_WATERMARK_DIR:-$HOME/.claude/meko-capture}/${SESSION_ID}.timer.pid"
+  if [ -f "$PID_FILE" ]; then
+    kill "$(cat "$PID_FILE")" 2>/dev/null || true
+    rm -f "$PID_FILE"
+  fi
+fi
+
+# Run final capture
+printf '%s' "$HOOK_INPUT" | node "$SCRIPT_DIR/lib/capture.js" session-end

package/assets/hooks-handlers/session-start.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# SessionStart hook — creates Meko conversation + watermark via capture.js,
+# injects additionalContext, and spawns the background checkpoint timer.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Read hook input from stdin (capture.js needs it, and we need transcript_path)
+HOOK_INPUT="$(cat)"
+TRANSCRIPT_PATH="$(printf '%s' "$HOOK_INPUT" | node -e '
+  const d = JSON.parse(require("fs").readFileSync(0,"utf-8"));
+  const p = d.transcript_path || (d.hookSpecificInput||{}).transcript_path || "";
+  process.stdout.write(p);
+' 2>/dev/null)"
+
+# Spawn background checkpoint timer (periodic capture without interrupting the agent)
+if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  nohup node "$SCRIPT_DIR/lib/checkpoint-timer.js" "$TRANSCRIPT_PATH" \
+    </dev/null >/dev/null 2>&1 &
+  disown 2>/dev/null || true
+fi
+
+# Create conversation + watermark via capture.js, output additionalContext
+printf '%s' "$HOOK_INPUT" | node "$SCRIPT_DIR/lib/capture.js" session-start

package/assets/hooks-handlers/test_single_conversation.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+#
+# test_single_conversation.sh — Verify that exactly ONE Meko conversation
+# is created per session, regardless of how many hook modes fire.
+#
+# Simulates the full hook lifecycle: session-start → checkpoint → pre-compact → session-end.
+# Asserts the watermark conversation_id stays the same throughout.
+#
+# Usage:
+#   ./test_single_conversation.sh [MCP_URL]
+#
+# Environment:
+#   MEKO_MCP_URL  MCP server URL (default: http://localhost:8000/mcp)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CAPTURE_JS="$SCRIPT_DIR/lib/capture.js"
+MCP_URL="${1:-${MEKO_MCP_URL:-http://localhost:8000/mcp}}"
+AGENT_ID="${MEKO_AGENT_ID:-claude_code}"
+
+# Temp dirs for isolation
+WATERMARK_DIR="$(mktemp -d -t meko-test-wm-XXXXXX)"
+TRANSCRIPT_DIR="$(mktemp -d -t meko-test-tx-XXXXXX)"
+SESSION_ID="test-dedup-$(uuidgen | tr '[:upper:]' '[:lower:]')"
+TRANSCRIPT_PATH="$TRANSCRIPT_DIR/${SESSION_ID}.jsonl"
+WATERMARK_PATH="$WATERMARK_DIR/${SESSION_ID}.watermark.json"
+
+PASS=0
+FAIL=0
+CONV_IDS_SEEN=()
+
+cleanup() {
+  rm -rf "$WATERMARK_DIR" "$TRANSCRIPT_DIR"
+}
+trap cleanup EXIT
+
+log()  { printf "  %-50s" "$1"; }
+pass() { printf "\033[32mPASS\033[0m %s\n" "${1:-}"; PASS=$((PASS + 1)); }
+fail() { printf "\033[31mFAIL\033[0m %s\n" "${1:-}"; FAIL=$((FAIL + 1)); }
+
+read_watermark_conv_id() {
+  if [ -f "$WATERMARK_PATH" ]; then
+    node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('$WATERMARK_PATH','utf-8')).conversation_id||'')"
+  fi
+}
+
+# Create mock transcript
+USER_UUID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
+cat > "$TRANSCRIPT_PATH" <<JSONL
+{"type":"user","uuid":"$USER_UUID","message":{"content":"What is YugabyteDB?"}}
+{"type":"assistant","uuid":"$(uuidgen | tr '[:upper:]' '[:lower:]')","message":{"content":"YugabyteDB is a distributed SQL database."}}
+{"type":"user","uuid":"$(uuidgen | tr '[:upper:]' '[:lower:]')","message":{"content":"Does it support PostgreSQL extensions?"}}
+{"type":"assistant","uuid":"$(uuidgen | tr '[:upper:]' '[:lower:]')","message":{"content":"Yes, including Apache AGE for graph queries."}}
+JSONL
+
+export MEKO_MCP_URL="$MCP_URL"
+export MEKO_AGENT_ID="$AGENT_ID"
+export MEKO_WATERMARK_DIR="$WATERMARK_DIR"
+
+echo "============================================================"
+echo "Test: Single Conversation Per Session (Dedup)"
+echo "============================================================"
+echo "  MCP URL:      $MCP_URL"
+echo "  Session ID:   $SESSION_ID"
+echo "  Transcript:   $TRANSCRIPT_PATH ($(wc -l < "$TRANSCRIPT_PATH") lines)"
+echo "  Watermark:    $WATERMARK_DIR"
+echo ""
+
+# --- Step 1: session-start ---
+echo "--- Step 1: session-start ---"
+
+HOOK_INPUT=$(printf '{"transcript_path":"%s"}' "$TRANSCRIPT_PATH")
+STDOUT=$(printf '%s' "$HOOK_INPUT" | node "$CAPTURE_JS" session-start 2>/dev/null || true)
+
+log "Watermark file created"
+if [ -f "$WATERMARK_PATH" ]; then
+  pass
+else
+  fail "not found at $WATERMARK_PATH"
+fi
+
+CONV_A=$(read_watermark_conv_id)
+log "Conversation ID assigned"
+if [ -n "$CONV_A" ]; then
+  pass "$CONV_A"
+  CONV_IDS_SEEN+=("$CONV_A")
+else
+  fail "empty conversation_id in watermark"
+fi
+
+log "Hook output contains conversation ID"
+if echo "$STDOUT" | grep -q "$CONV_A" 2>/dev/null; then
+  pass
+else
+  fail "stdout did not contain $CONV_A"
+fi
+
+# --- Step 2: checkpoint ---
+echo ""
+echo "--- Step 2: checkpoint ---"
+
+printf '%s' "$HOOK_INPUT" | node "$CAPTURE_JS" checkpoint 2>/dev/null || true
+
+CONV_B=$(read_watermark_conv_id)
+log "Watermark conversation unchanged after checkpoint"
+if [ "$CONV_B" = "$CONV_A" ]; then
+  pass "$CONV_B"
+else
+  fail "expected $CONV_A, got $CONV_B"
+  CONV_IDS_SEEN+=("$CONV_B")
+fi
+
+# --- Step 3: pre-compact ---
+echo ""
+echo "--- Step 3: pre-compact ---"
+
+printf '%s' "$HOOK_INPUT" | node "$CAPTURE_JS" pre-compact 2>/dev/null || true
+
+CONV_C=$(read_watermark_conv_id)
+log "Watermark conversation unchanged after pre-compact"
+if [ "$CONV_C" = "$CONV_A" ]; then
+  pass "$CONV_C"
+else
+  fail "expected $CONV_A, got $CONV_C"
+  CONV_IDS_SEEN+=("$CONV_C")
+fi
+
+# --- Step 4: session-end ---
+echo ""
+echo "--- Step 4: session-end ---"
+
+printf '%s' "$HOOK_INPUT" | node "$CAPTURE_JS" session-end 2>/dev/null || true
+
+CONV_D=$(read_watermark_conv_id)
+log "Watermark conversation unchanged after session-end"
+if [ "$CONV_D" = "$CONV_A" ]; then
+  pass "$CONV_D"
+else
+  fail "expected $CONV_A, got $CONV_D"
+  CONV_IDS_SEEN+=("$CONV_D")
+fi
+
+# --- Step 5: Verify exactly one conversation in Meko ---
+echo ""
+echo "--- Step 5: Verify single conversation ---"
+
+UNIQUE_IDS=($(printf '%s\n' "${CONV_IDS_SEEN[@]}" | sort -u))
+log "Unique conversation IDs across all hooks"
+if [ ${#UNIQUE_IDS[@]} -eq 1 ]; then
+  pass "1 (${UNIQUE_IDS[0]})"
+else
+  fail "${#UNIQUE_IDS[@]} distinct IDs: ${UNIQUE_IDS[*]}"
+fi
+
+# --- Summary ---
+echo ""
+echo "============================================================"
+TOTAL=$((PASS + FAIL))
+echo "  Total: $TOTAL  |  Passed: $PASS  |  Failed: $FAIL"
+echo "============================================================"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo "  RESULT: FAILED"
+  exit 1
+else
+  echo "  RESULT: ALL PASSED"
+  exit 0
+fi

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

@@ -0,0 +1,192 @@
+---
+name: meko-mcp-tools
+description: Behavioral guide for AI agents using Meko MCP tools. Triggers when calling MCP tools, storing memories, persisting knowledge, managing datapacks, or working with YugabyteDB databases through Meko.
+license: MIT
+metadata:
+  author: Meko
+  version: "2.1.0"
+  tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko
+---
+
+# Meko MCP Tools — Agent Behavioral Guide
+
+Meko is agent-native data infrastructure that enables continuous learning from context windows through collective memory and shared knowledge. This skill teaches you how to use Meko's 31 MCP tools — and more importantly, **when to use them proactively** without waiting to be asked.
+
+## What Meko enables
+
+Meko turns your volatile context window into persistent, shareable knowledge:
+
+- **Personal memory** — Store who the user is, their preferences, role, and working style. Survives across sessions.
+- **Team/org memory** — Store organizational conventions, coding standards, tooling choices. Shared across agents and team members.
+- **Shared knowledge** — Persist domain knowledge (product specs, data dictionaries, research) into a searchable knowledge base via RAG.
+- **Conversation history** — Preserve full dialog exchanges with reasoning traces for audit, replay, and learning transfer.
+- **Decision traces** — Capture how and why decisions were made, enabling debugging and continuous improvement.
+- **Structured data** — Store and query tabular data in a real database, not squeezed into memory.
+
+## When to use this skill
+
+- You are calling tools on a Meko / YugabyteDB MCP server
+- You need to decide what to store, where, and how
+- You are constructing SQL queries for `db_run_read_only_query` or `db_run_write_query`
+- You are setting up a RAG knowledge base pipeline
+- You are managing datapacks, agents, or knowledge base sources
+- You want to understand scope/permission requirements, `agent_id` constraints, or `datapack_id` routing
+
+## Discover the user's `agent_id` namespace — don't guess it
+
+`agent_id` is currently overloaded: it doubles as a user-namespace key and an agent-type label. Treat it as the **user's namespace**, not as "which tool am I." See [issue #10](https://github.com/amiramm/meko-mcp-server/issues/10) for why this matters.
+
+Defaulting to `claude_code` because you are Claude Code **fragments the user's memory across tools.** Don't do it.
+
+### The discovery protocol (run once per session, before any memory call)
+
+1. Call `db_summarize_database(scope="read", conversation_id="00000000-0000-0000-0000-000000000000")`.
+2. Inspect the returned tables. Mem0 stores memories in `<agent_id>_mem0_collection`. For each such table with `row_count > 0`, that's an `agent_id` the user is already using.
+3. Pick the namespace:
+   - **Exactly one `<x>_mem0_collection` has rows** → use `agent_id="<x>"`.
+   - **Multiple candidates with rows** → pick the one with the highest `row_count` (that's the user's primary namespace). Mention the other(s) briefly so the user can steer if they want memory written elsewhere.
+   - **No `<x>_mem0_collection` has rows** → use `agent_id="agent"`. This is the fallback for a fresh user.
+4. Cache the chosen value. Use it for every `memory_*` and `conversation_*` call in this session.
+
+Never pick `claude_code` just because you're running in Claude Code. Pick what the user already uses. If you're wrong, the next `memory_search` returns nothing and you'll notice.
+
+The SessionStart hook may seed a `conversation_id` in the watermark, but it does not pick `agent_id` for you — discovery still applies.
+
+## 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.
+
+### 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?" | Search memory first, then DB | `memory_search` then `db_run_read_only_query` |
+| Session produced a valuable multi-turn exchange | Preserve the full conversation | `conversation_create` + `conversation_add_message` |
+| Significant learnings accumulated during session | Offer to persist key takeaways | Summarize and propose `memory_add` calls |
+| User provides structured/tabular data (CSV, data dictionary) | Store as database table, NOT memory | `db_run_write_query` (CREATE TABLE + INSERT) |
+
+### 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 — organizational memory
+├── Domain knowledge (facts, definitions, specs, research)
+│   → memory_add for quick recall + KB ingestion for search at scale
+├── A correction or learning ("don't do X", "always do Y")
+│   → memory_add — behavioral feedback
+├── Full conversation worth preserving (multi-turn, reasoning traces)
+│   → conversation_create + conversation_add_message — verbatim
+└── Structured/tabular data (CSV rows, schemas, data dictionaries)
+    → db_run_write_query (CREATE TABLE + INSERT) — NOT memory_add
+```
+
+**Why not memory_add for tabular data?** Mem0 extracts individual facts from text. Passing CSV rows through it loses columns, rows, and structural relationships. Use the database for structured data.
+
+## Automatic conversation capture
+
+The Meko plugin automatically captures conversations via three mechanisms that coordinate through a shared watermark file:
+
+1. **Background checkpoint timer** — runs every 10 minutes, captures new exchanges without interrupting the agent
+2. **PreCompact hook** — fires before context compaction, captures everything before compaction discards context
+3. **SessionEnd hook** — fires at session end, captures remaining exchanges
+
+All three are handled automatically. **Do NOT set up CronCreate for conversation capture** — it interrupts running tool calls and causes disruptive retry cycles.
+
+### What to do at session start
+
+The SessionStart hook has already done the setup for you:
+
+1. **Created a Meko conversation** — `conversation_id` is injected into `additionalContext` on the first turn. Use that value for all subsequent MCP tool calls that accept `conversation_id`.
+2. **Discovered and cached `agent_id`** — also injected into `additionalContext`. Use the injected value as-is; do not re-run `db_summarize_database` unless `additionalContext` shows discovery failed (falls back to a default).
+3. **Preloaded recent memories** — `additionalContext` may include a `### Memories from prior sessions` block. Inspect it before acting so you don't re-ask questions the user has already answered.
+
+If `additionalContext` is absent or empty (hook failed, MCP unavailable), fall back to the manual protocol: run discovery via `db_summarize_database` (see "Discover the user's `agent_id` namespace" above) and use a nil UUID for `conversation_id` until you can create a real one.
+
+### Before potentially destructive actions
+
+Before any action that deletes, overwrites, or restructures user content — `Write` overwriting an existing file, large `Edit` deletions, `rm` / `rm -rf`, `git reset --hard`, destructive SQL (`DROP`, `TRUNCATE`, `DELETE` without `WHERE`) — run a `memory_search` for relevant feedback:
+
+```
+memory_search(scope="read", query="destructive <action type> preferences feedback",
+              agent_id=<discovered>, conversation_id=<session_or_nil>)
+```
+
+If a relevant feedback memory exists (e.g., "always ask before deleting content"), confirm with the user before proceeding. If the search is empty, proceed, but treat the action as irreversible and prefer a dry-run / preview when one is available.
+
+### Capture rules
+
+- **Verbatim content only** — never summarize, rephrase, or condense. See `tools-memory-vs-conversation.md`.
+- **Include tool calls and results** — store tool_use name + input in `reasoning`, tool results as follow-up reasoning entries. These are essential for session replay and compaction context.
+- **Always use a seed** — enables dedup across the three capture mechanisms.
+- **Graceful failure** — if `conversation_add_message` fails, log the error and continue. Do not retry more than once.
+
+## 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_code", conversation_id="00000000-0000-0000-0000-000000000000")
+```
+Required parameters: `scope`, `text`, `agent_id`, `conversation_id`. Use a nil UUID (`"00000000-0000-0000-0000-000000000000"`) for `conversation_id` unless you have a real one from `conversation_create`. NEVER use strings like `"current"` or `""`.
+
+### memory_search — correct call pattern
+```
+memory_search(scope="read", query="user role", agent_id="claude_code", conversation_id="00000000-0000-0000-0000-000000000000")
+```
+Required parameters: `scope`, `query`, `agent_id`, `conversation_id`. Use a nil UUID for `conversation_id`.
+
+### Critical parameter rules
+
+- **agent_id**: Use the value you discovered at session start (see "Discover the user's `agent_id` namespace" above), not a literal tool name. The reference examples below use `claude_code` for illustration only — substitute the discovered value. Must use underscores, never hyphens (hyphens break PostgreSQL table names and produce SQL syntax errors). If you haven't run discovery yet, do it now before any memory call.
+- **conversation_id**: If required by the tool, use a nil UUID (`"00000000-0000-0000-0000-000000000000"`) unless you have a real one from `conversation_create`. NEVER use strings like `"current"`, `""`, or other non-UUID values.
+- **scope**: Only `"read"`, `"write"`, or `"admin"`. Nothing else.
+- **When in doubt about optional parameters, omit them.** The server has sensible defaults.
+
+## Key concepts
+
+1. **31 tools in 5 groups**: Database (3), RAG/Knowledge Base (3), Memory (7), Conversation (7), Datapack Management (11)
+2. **Scope hierarchy**: `read < write < admin` — every tool validates scope at entry. Only three valid values: `"read"`, `"write"`, `"admin"`. Using anything else (e.g., `"all"`) will fail.
+3. **datapack_id routing**: All DB, RAG, and memory tools accept optional `datapack_id` to target a specific datapack's database instead of the default
+4. **agent_id is a per-user namespace, not a per-tool label**: Memory and conversation tools use `agent_id` to isolate data. Discover the user's existing namespace via `db_summarize_database` at session start (see the section above) and use that value across every call — don't default to `claude_code` just because the current client is Claude Code. Must use underscores, never hyphens (hyphens are injected into PostgreSQL table names and cause SQL syntax errors). Issue [#10](https://github.com/amiramm/meko-mcp-server/issues/10) tracks the schema split that will eventually unbundle this.
+5. **Write guardrails**: `db_run_write_query` blocks dangerous SQL patterns and enforces configurable limits. One statement per call.
+6. **Conversation dedup**: `conversation_add_message` supports seed-based deterministic trace IDs to prevent duplicates
+7. **Known limitations**: Some tools have bugs or missing capabilities — see `tools-known-limitations.md` before attempting RAG cleanup or write operations
+8. **Error recovery**: Connection errors are common with memory tools — see `tools-troubleshooting.md` for retry strategies and fallbacks
+
+## Reference sections
+
+| File | What it covers |
+|------|---------------|
+| `tools-overview.md` | Complete catalog of all 31 tools with decision tree |
+| `tools-cookbook.md` | Per-tool examples with correct parameters, responses, and error cases |
+| `tools-memory-vs-conversation.md` | When to use memory tools vs conversation tools |
+| `tools-datapack-workflow.md` | Datapack lifecycle and datapack_id routing |
+| `tools-rag-workflow.md` | End-to-end RAG pipeline flow |
+| `tools-write-guardrails.md` | Blocked SQL patterns and configurable limits |
+| `tools-scope-permissions.md` | read/write/admin permission hierarchy |
+| `tools-agent-id-conventions.md` | Naming rules and constraints for agent_id |
+| `tools-conversation-dedup.md` | Seed-based trace deduplication |
+| `tools-db-query-patterns.md` | Read-only vs write query execution patterns |
+| `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/references/_sections.md

@@ -0,0 +1,31 @@
+---
+title: Section Index
+description: Maps reference files to their topics for the meko-mcp-tools skill
+---
+
+# Reference Sections
+
+## Tool Selection & Catalog
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 31 tools with a decision tree for choosing the right tool
+
+## Tool-Specific Guidance
+- [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message
+- [tools-datapack-workflow.md](tools-datapack-workflow.md) — Datapack lifecycle, datapack_id routing, and multi-database patterns
+- [tools-rag-workflow.md](tools-rag-workflow.md) — End-to-end RAG pipeline: source registration, index creation, status polling
+- [tools-db-query-patterns.md](tools-db-query-patterns.md) — Read-only vs write query execution patterns and SQL conventions
+
+## Safety & Permissions
+- [tools-write-guardrails.md](tools-write-guardrails.md) — Blocked SQL operations, bulk insert limits, WHERE clause enforcement
+- [tools-scope-permissions.md](tools-scope-permissions.md) — read/write/admin permission hierarchy and per-tool requirements
+
+## Conventions & Deduplication
+- [tools-agent-id-conventions.md](tools-agent-id-conventions.md) — agent_id naming rules, hyphen prohibition, and namespace isolation
+- [tools-user-id-conventions.md](tools-user-id-conventions.md) — user_id vs agent_id: when to pass each, and how they scope memory
+- [tools-conversation-dedup.md](tools-conversation-dedup.md) — Seed-based deterministic trace IDs for Langfuse deduplication
+
+## 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/references/tools-agent-id-conventions.md

@@ -0,0 +1,39 @@
+# agent_id Naming Rules and Namespace Isolation
+
+**WRONG:** `agent_id="my-support-agent"` → mem0 uses agent_id in table names (`my-support-agent_mem0_collection`), and hyphens are invalid PostgreSQL identifiers → table creation fails.
+
+## The Rule
+
+**agent_id MUST NOT contain hyphens.** Use underscores. Stick to: lowercase letters, digits, and underscores.
+
+```
+GOOD: "support_bot", "sales_agent_v2", "agent_001"
+BAD:  "support-bot", "sales-agent-v2", "my agent", "agent.one"
+```
+
+## Namespace Isolation
+
+`agent_id` is the primary isolation boundary for both memory and conversation tools:
+
+**Memory (mem0/pgvector + Apache AGE):**
+- Each agent_id gets its own pgvector collection (`{agent_id}_mem0_collection`) and AGE graph (`{agent_id}_mem0_graph`)
+- `memory_search` and `memory_get_all` only return data from the specified agent's namespace
+
+**Conversations (Langfuse):**
+- Traces tagged with `agent:{agent_id}`, names prefixed with `{agent_id}:message`, `{agent_id}:start`, `{agent_id}:update`
+- `conversation_list` and `conversation_get` filter by and verify agent ownership
+
+## Consistency is Critical
+
+**WRONG:** Using `agent_id="support_bot"` for memory and `agent_id="supportBot"` for conversations — these are separate namespaces that will never see each other's data.
+
+Use the same `agent_id` string across all memory and conversation calls for the same logical agent.
+
+## Sub-Scoping
+
+Within a single agent_id, further scope with optional parameters:
+- `user_id` — per-user isolation
+- `app_id` — per-application (e.g., "web_app" vs "mobile_app")
+- `run_id` — per-execution run
+
+Available on `memory_add`, `memory_search`, `memory_get_all`, `memory_delete_all`, `conversation_create`, `conversation_list`.

package/assets/skills/meko-mcp-tools/references/tools-conversation-dedup.md

@@ -0,0 +1,49 @@
+# Seed-Based Trace Deduplication for Conversations
+
+## The Problem
+
+When MCP clients have built-in Langfuse hooks (Cursor, Claude Code), both the client hook and the MCP server may write a trace for the same message → duplicate traces, doubled message counts, corrupted conversation retrieval.
+
+**WRONG:** Neither `seed` nor `trace_id` provided → both sides generate random IDs → two traces per message.
+
+## Solution: Use seed for deterministic trace IDs
+
+```
+conversation_add_message(
+    scope="write", conversation_id="conv-uuid", agent_id="my_agent",
+    input="What is our Q3 revenue?",
+    output="Q3 revenue was $4.2M, up 15% from Q2.",
+    seed="conv-uuid:my_agent:What is our Q3 revenue?"
+)
+```
+
+Both sides hash the same seed string to produce the same trace ID. Langfuse treats the second write as an upsert → exactly one trace.
+
+## Priority Rules
+
+1. **`trace_id`** — if provided, used directly (highest precedence)
+2. **`seed`** — if provided, hashed to produce deterministic trace ID
+3. **Neither** — random trace ID generated
+
+## Choosing a Good Seed
+
+The seed should be deterministic and unique per message:
+
+```
+seed = f"{conversation_id}:{agent_id}:{input_text}"
+-- or, if message order matters:
+seed = f"{conversation_id}:{agent_id}:{message_index}"
+```
+
+## When to Use Each
+
+| Scenario | Use |
+|----------|-----|
+| Client hook + MCP server both write to Langfuse | `seed` |
+| Only the MCP server writes (no client hook) | Neither (random is fine) |
+| Migrating from another system with existing IDs | `trace_id` |
+| Replaying messages idempotently | `seed` |
+
+## session_id on conversation_create
+
+Optional `session_id` serves a similar dedup purpose for the conversation container. If provided, the same session_id reconnects to an existing Langfuse session.