@yugabytedb/meko-mcp 1.2.0 → 2.0.0

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

@@ -13,10 +13,14 @@ TRANSCRIPT_PATH="$(printf '%s' "$HOOK_INPUT" | node -e '
   process.stdout.write(p);
 ' 2>/dev/null)"
 
-# Spawn background checkpoint timer (periodic capture without interrupting the agent)
+# Spawn background checkpoint timer (periodic capture without interrupting the agent).
+# Send the daemon's stderr to a log file instead of /dev/null so startup
+# failures and crashes are diagnosable; stdout is still discarded.
 if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  MEKO_LOG_DIR="${MEKO_WATERMARK_DIR:-$HOME/.claude/meko-capture}"
+  mkdir -p "$MEKO_LOG_DIR"
   nohup node "$SCRIPT_DIR/lib/checkpoint-timer.js" "$TRANSCRIPT_PATH" \
-    </dev/null >/dev/null 2>&1 &
+    </dev/null >/dev/null 2>>"$MEKO_LOG_DIR/timer.log" &
   disown 2>/dev/null || true
 fi
 

package/assets/scripts/meko-statusline.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# meko-statusline.sh — Claude Code statusline contribution showing the active Meko datapack pin.
+#
+# Composable: if --inner-cmd is provided (or MEKO_INNER_STATUSLINE env var), runs it first and
+# appends our suffix. So a user with an existing statusLine doesn't lose it.
+#
+# Usage in ~/.claude/settings.json (after installer wires it):
+#   { "statusLine": { "type": "command", "command": "$HOME/.claude/meko-statusline.sh --inner-cmd <existing-cmd>" } }
+#
+# Or, if you maintain the inner command separately, set MEKO_INNER_STATUSLINE=<cmd> in env.
+#
+# Outputs nothing (empty string) when no pin is set, so the indicator is invisible until you pin.
+# The output goes on stdout — Claude Code displays it as-is, supporting ANSI color codes if you
+# wrap the suffix.
+#
+# Reads JSON from stdin (Claude Code passes session metadata) and forwards it verbatim to the inner
+# command. The inner command's stdout is printed first, then our suffix.
+
+set -u
+
+INNER_CMD=""
+if [[ "${1:-}" == "--inner-cmd" && -n "${2:-}" ]]; then
+  INNER_CMD="$2"
+elif [[ -n "${MEKO_INNER_STATUSLINE:-}" ]]; then
+  INNER_CMD="$MEKO_INNER_STATUSLINE"
+fi
+
+# Buffer stdin once so we can pipe the same JSON to both the inner command and our derivation.
+STDIN_PAYLOAD=""
+if [[ -p /dev/stdin || ! -t 0 ]]; then
+  STDIN_PAYLOAD="$(cat)"
+fi
+
+# --- Inner command first (preserves any pre-existing statusline content) ---
+
+if [[ -n "$INNER_CMD" ]]; then
+  if [[ -n "$STDIN_PAYLOAD" ]]; then
+    INNER_OUT="$(printf '%s' "$STDIN_PAYLOAD" | eval "$INNER_CMD" 2>/dev/null || true)"
+  else
+    INNER_OUT="$(eval "$INNER_CMD" 2>/dev/null || true)"
+  fi
+  # Strip a single trailing newline so our suffix appears on the same line.
+  INNER_OUT="${INNER_OUT%$'\n'}"
+  printf '%s' "$INNER_OUT"
+fi
+
+# --- Derive agent_id from cwd ---
+#
+# Mirrors deriveAgentId() in skills/hooks-handlers/lib/capture.js:51-65:
+#   - basename of cwd, lowercased
+#   - non-[a-z0-9-]+ → '-'
+#   - trim leading/trailing '-'
+#   - max 64 chars
+#   - prefix with 'claude_code:'
+#
+# Then mirrors datapackPinSlug() in capture.js:341-348:
+#   - non-[A-Za-z0-9._-]+ → '_'
+#   - trim leading/trailing '_'
+#
+# Prefer cwd from the JSON stdin payload (Claude Code's session metadata format), falling back
+# to PWD if stdin was empty / not piped.
+
+CWD="$PWD"
+if [[ -n "$STDIN_PAYLOAD" ]]; then
+  # Best-effort extraction without requiring jq. Look for "cwd":"…" first; fall back to "workspace":{"current_dir":"…"}.
+  # Isolate the exact key/value pair with grep -oE before extracting so a greedy `.*` can't grab a
+  # different key that merely ends in `cwd`/`current_dir` earlier on the same line.
+  EXTRACTED="$(printf '%s' "$STDIN_PAYLOAD" | grep -oE '"cwd"[[:space:]]*:[[:space:]]*"[^"]+"' | sed -E 's/.*"([^"]+)"$/\1/' | head -n 1)"
+  if [[ -z "$EXTRACTED" ]]; then
+    EXTRACTED="$(printf '%s' "$STDIN_PAYLOAD" | grep -oE '"current_dir"[[:space:]]*:[[:space:]]*"[^"]+"' | sed -E 's/.*"([^"]+)"$/\1/' | head -n 1)"
+  fi
+  if [[ -n "$EXTRACTED" ]]; then
+    CWD="$EXTRACTED"
+  fi
+fi
+
+# MEKO_AGENT_ID overrides the cwd-derived id, matching resolveSessionAgentId() in
+# capture.js (the env override wins verbatim when non-empty).
+if [[ -n "${MEKO_AGENT_ID:-}" ]]; then
+  AGENT_ID="$MEKO_AGENT_ID"
+else
+  BASENAME="$(basename "$CWD")"
+  PROJECT_SLUG="$(printf '%s' "$BASENAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]+/-/g; s/^-+|-+$//g')"
+  PROJECT_SLUG="${PROJECT_SLUG:0:64}"
+
+  if [[ -z "$PROJECT_SLUG" || "$PROJECT_SLUG" == "-" ]]; then
+    AGENT_ID="claude_code"
+  else
+    AGENT_ID="claude_code:$PROJECT_SLUG"
+  fi
+fi
+
+PIN_SLUG="$(printf '%s' "$AGENT_ID" | sed -E 's/[^A-Za-z0-9._-]+/_/g; s/^_+|_+$//g')"
+# Match datapackPinSlug() in capture.js: an empty slug falls back to the common bucket
+# (meko_agent), so both components look for the same pin file.
+if [[ -z "$PIN_SLUG" ]]; then
+  PIN_SLUG="meko_agent"
+fi
+PIN_FILE="${MEKO_WATERMARK_DIR:-$HOME/.claude/meko-capture}/pin-${PIN_SLUG}.json"
+
+# --- Read the pin file and append the suffix if a valid pin is present ---
+
+if [[ -f "$PIN_FILE" ]]; then
+  # grep -oE isolates the exact "datapack_name":"…" pair before extracting, so a
+  # greedy `.*` can't grab a different key that merely ends in datapack_name.
+  PIN_NAME="$(grep -oE '"datapack_name"[[:space:]]*:[[:space:]]*"[^"]+"' "$PIN_FILE" | sed -E 's/.*"([^"]+)"$/\1/' | head -n 1)"
+  if [[ -n "$PIN_NAME" ]]; then
+    SUFFIX="Meko: $PIN_NAME"
+    # Add a separator only if the inner command produced output.
+    if [[ -n "${INNER_OUT:-}" ]]; then
+      printf ' \xe2\x80\xa2 %s' "$SUFFIX"
+    else
+      printf '%s' "$SUFFIX"
+    fi
+  fi
+fi
+
+# Always finish with a newline so subsequent shell renders cleanly.
+printf '\n'

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

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

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

@@ -1,16 +1,18 @@
 ---
 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.
+description: Behavioral guide for AI agents using Meko MCP tools. Triggers when calling MCP tools, storing memories, persisting knowledge, managing datapacks, or searching shared knowledge bases through Meko.
 license: MIT
 metadata:
   author: Meko
-  version: "2.3.0"
-  tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko
+  version: "3.0.0"
+  tags: mcp, 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 26 MCP tools — and more importantly, **when to use them proactively** without waiting to be asked.
+Meko is agent-native data infrastructure that enables continuous learning from context windows through collective memory and shared knowledge. This skill teaches you how to use Meko's 22 MCP tools.
+
+**Read this first.** On Claude Code, conversation capture is automatic (SessionStart / PreCompact / SessionEnd hooks) and the Meko server extracts durable memories from the captured turns on its own. Facts the user states in conversation are saved for you — you do **not** proactively call `memory_add` for them. Your active jobs are: **recall** what's already known (`memory_search`, `knowledgebase_search`), and the **few** save cases automatic extraction cannot reach. Details below.
 
 ## What Meko enables
 
@@ -54,15 +56,14 @@ See `tools-agent-id-conventions.md` for the full model, including how promotion
 
 Some pre-existing rows in real datapacks use the older `agent_id="agent"` constant or other ad-hoc shapes (`claude_code`, `cursor:<slug>`). They remain readable — query them with `agent_id="agent"` explicitly. New writes should follow the schema above.
 
-## Critical: Use Meko tools, not local storage
+## Critical: Use Meko, 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.
+**Meko is the memory store — never write memories to local 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. On Claude Code, memory reaches Meko two ways, and neither is a local file:
 
-- 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
+- **Automatic capture + extraction** (the dominant path) — the hooks capture this session's turns and the server extracts memories from them. Facts the user states are stored without any tool call from you.
+- **Explicit `memory_add`** (the narrow path) — only for the cases extraction can't reach (see "When to call memory_add" below).
 
-If a Meko tool call fails, you may fall back to local storage and tell the user — but Meko is always the first choice.
+To recall, call `memory_search` on the MCP server, NOT read local files. If a Meko read/write call fails, you may fall back to local storage and tell the user — but Meko is always the first choice.
 
 ## When spawning subagents
 
@@ -112,49 +113,38 @@ If the inherited block is **absent**, the subagent MUST NOT guess — see the se
 
 Subagents cannot auto-discover the parent's watermark today: Claude Code does not expose a `CLAUDE_PARENT_SESSION_ID` env var or any equivalent marker file to subagent processes (see the spike note in `skills/hooks-handlers/lib/capture.js`). Prompt injection is the only enforcement mechanism.
 
-## Core principle: Be Meko's persistent brain
+## Core principle: capture is automatic — recall, don't re-store
 
-**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.
+Meko is your long-term memory, but on Claude Code you do **not** build it by hand. The hooks capture every turn of this session and the server extracts durable memories from them automatically. **A fact the user states in conversation — name, role, preferences, org conventions, corrections, casual asides — is already saved. Calling `memory_add` for it just duplicates what extraction stored.** (Verified empirically: the server extracts conversationally-stated facts verbatim, including multi-fact turns and precise multi-clause facts.)
 
-### Proactive behavior rules
+So your Meko reflexes are:
 
-| 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; consider suggesting they promote it to Shared Knowledge from the Learnings tab | `memory_add` |
-| User corrects your behavior ("don't do X, do Y instead") | Store the correction as a learning | `memory_add` |
-| User asks "what do you know about X?" | Three-call sweep: your project's memories, then the cross-project common bucket, then team-shared knowledge | `memory_search(agent_id=<yours>)` → `memory_search(agent_id="meko_agent")` → `knowledgebase_search` |
-| User asks "what do we (as a team) know about X?" or about uploaded documents | Query the team's Shared Knowledge directly | `knowledgebase_search` (returns uploaded docs + promoted memories) |
-| Session produced a valuable multi-turn exchange | Preserve the full conversation | `conversation_create` + `conversation_add_message` |
-| Significant learnings accumulated during session | Offer to persist key takeaways; remind the user they can promote important ones to Shared Knowledge from the Cloud UI | Summarize and propose `memory_add` calls |
-| User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP on Cloud today — `db_run_write_query` returns `{"error": "not_available"}`. Store the key facts as memories or point the user at the UI's knowledge-base upload for file form | `memory_add` for facts, UI "Add Knowledge" for files |
-| User wants to add documents to the team's knowledge base | Point them at the Cloud UI flow — Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). The MCP ingestion tools are not available on Cloud. | UI only |
+1. **Recall first.** When the user asks what's known, or before you act on something they may have an opinion about, search — don't assume.
+2. **Save only what capture can't reach** (the three narrow cases below).
+3. **Never** re-store a fact the user just said. **Never** write memories to local files.
 
-### Information classification
+### When the user shares information
 
-When the user shares information, classify it before storing:
+| Signal in conversation | What to do |
+|---|---|
+| User states a fact about themselves, their team, tools, or preferences | **Nothing — automatic capture + extraction stores it.** Just answer. |
+| User corrects your behavior or negates a prior fact ("actually, we use Nomad now") | The new fact is captured automatically, but extraction is **additive** — it does not remove the old one. If a stale, contradicted memory must not survive, `memory_search` for it and `memory_update` / `memory_delete_by_id`. |
+| User explicitly says "remember this" / "save this to memory" | `memory_add` (verbatim). This is the clearest explicit-save case. |
+| A durable fact appears only in YOUR output or a tool result, never in the user's words | `memory_add`. Extraction reads only the **user** turn, so facts you derive or a tool surfaces are never captured otherwise. |
+| User asks "what do you know about X?" | Three-call sweep: `memory_search(agent_id=<yours>)` → `memory_search(agent_id="meko_agent")` → `knowledgebase_search`. |
+| User asks "what do we (as a team) know about X?" or about uploaded documents | `knowledgebase_search` (returns uploaded docs + promoted memories). |
+| User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP. Point the user at the UI's Add Knowledge upload; do not `memory_add` row-by-row. |
+| 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). MCP ingestion tools are not available on Cloud. |
 
-```
-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.
-```
+### When to call memory_add (the whole list)
+
+Automatic capture handles the rest, so explicit `memory_add` is reserved for exactly three cases:
+
+1. **Explicit request** — the user says "remember this" / "save this."
+2. **Output-only / tool-derived fact** — a durable fact that lives only in the assistant's output or a tool result, never in a user turn (extraction only sees the user turn).
+3. **Overwriting correction** — a prior fact was negated and the stale memory must not survive (extraction is additive; pair `memory_add`/`memory_update` with a `memory_delete_by_id` of the old one).
+
+When you do call it, store the fact verbatim in the user's own words; do not summarize.
 
 ## Automatic conversation capture
 
@@ -203,9 +193,11 @@ If a relevant feedback memory exists (e.g., "always ask before deleting content"
 In the examples below, `<your-agent-id>` means the value the SessionStart hook injected into `additionalContext` — for Claude Code, something like `claude_code:meko-mcp-server`. Not the literal string `"<your-agent-id>"`.
 
 ### memory_add — correct call pattern
+
+Only for the three narrow cases in "When to call memory_add" above — not for facts the user stated in conversation (those are captured automatically). The example below is an explicit "remember this" save:
 ```
 memory_add(scope="write",
-           text="User is VP of Product at YugabyteDB",
+           text="Remember: deploy scripts must be run from the repo root, never a subdir",
            agent_id="<your-agent-id>",
            conversation_id="<session_conversation_id>")
 ```
@@ -276,7 +268,7 @@ On the first Meko tool call in a fresh session (no prior Meko tool call since pr
 
 ## Key concepts
 
-1. **26 tools in 5 groups**: Memory (8), Conversation (6), Knowledge Base (4), Datapack (5), Database (3). On Cloud Meko today, all DB tools and the three KB ingestion tools return `{"error": "not_available"}` — only `knowledgebase_search` works in the KB group. See `tools-overview.md` for the full availability map.
+1. **22 tools in 5 groups**: Memory (8), Conversation (6), Knowledge Base (1 — `knowledgebase_search`), Datapack (5), Artifacts (2 — `artifact_put`, `artifact_get`). KB ingestion is UI-only (Datapack → Actions → Add Knowledge); raw SQL is not exposed. 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**: Each client+project uses its own `agent_id` (shape `<client>:<repo-basename>`). Writes are scoped to `(datapack_id, user_id, agent_id)`. Personal reads (`memory_search`, `memory_get_all`) filter strictly on this tuple. Empty/missing `agent_id` lands in the `meko_agent` common bucket — use it explicitly for cross-project facts. `knowledgebase_search` ignores `agent_id` entirely and returns the team-shared knowledge on the datapack. See `tools-agent-id-conventions.md`.
@@ -292,7 +284,7 @@ On the first Meko tool call in a fresh session (no prior Meko tool call since pr
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 26 tools with decision tree + cloud Free-Tier gating map |
+| `tools-overview.md` | Complete catalog of all 22 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 |

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

@@ -6,7 +6,7 @@ description: Maps reference files to their topics for the meko-mcp-tools skill
 # Reference Sections
 
 ## Tool Selection & Catalog
-- [tools-overview.md](tools-overview.md) — Complete catalog of all 26 tools with a decision tree and cloud Free-Tier gating map
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 22 tools with a decision tree
 
 ## Tool-Specific Guidance
 - [tools-memory-vs-conversation.md](tools-memory-vs-conversation.md) — Decision framework: memory_add vs conversation_create/conversation_add_message