thumbgate 0.9.10

package/scripts/xmemory-lite.js

@@ -0,0 +1,405 @@
+'use strict';
+
+const STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'been', 'before', 'but', 'by',
+  'for', 'from', 'had', 'has', 'have', 'into', 'its', 'more', 'not', 'now',
+  'our', 'out', 'that', 'the', 'their', 'them', 'then', 'they', 'this', 'too',
+  'was', 'were', 'what', 'when', 'with', 'without', 'your',
+]);
+
+const GENERIC_THEME_TAGS = new Set([
+  'feedback',
+  'positive',
+  'negative',
+  'rules',
+  'prevention',
+  'memory',
+  'research',
+  'paper',
+  'hf-papers',
+]);
+
+function normalizeKey(input, fallback = 'general') {
+  const value = String(input || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return value || fallback;
+}
+
+function uniqueList(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function tokenizeText(input) {
+  return uniqueList(
+    String(input || '')
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((token) => token.length > 2 && !STOPWORDS.has(token))
+  );
+}
+
+function summarizeText(input, maxChars = 180) {
+  return String(input || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maxChars);
+}
+
+function inferThemeKey(doc = {}) {
+  const metadata = doc.metadata || {};
+  const directCandidates = [
+    metadata.theme,
+    metadata.contentPillar,
+    metadata.domain,
+  ];
+
+  for (const candidate of directCandidates) {
+    if (typeof candidate === 'string' && candidate.trim()) {
+      return normalizeKey(candidate);
+    }
+  }
+
+  const tags = Array.isArray(doc.tags) ? doc.tags.map((tag) => String(tag).toLowerCase()) : [];
+  const meaningfulTag = tags.find((tag) => !GENERIC_THEME_TAGS.has(tag));
+  if (meaningfulTag) {
+    return normalizeKey(meaningfulTag);
+  }
+
+  if (tags.length > 0) {
+    return normalizeKey(tags[0]);
+  }
+
+  if (typeof doc.namespace === 'string' && doc.namespace.includes('memory/error')) return 'mistakes';
+  if (typeof doc.namespace === 'string' && doc.namespace.includes('memory/learning')) return 'learnings';
+  if (typeof doc.namespace === 'string' && doc.namespace.includes('raw_history')) return 'timeline';
+  if (typeof doc.namespace === 'string' && doc.namespace.includes('rules')) return 'rules';
+
+  const namespaceTail = String(doc.namespace || '').split('/').pop();
+  return normalizeKey(namespaceTail, 'general');
+}
+
+function collectDocumentTokens(doc = {}) {
+  return uniqueList([
+    ...tokenizeText(doc.title),
+    ...tokenizeText(summarizeText(doc.content, 240)),
+    ...(Array.isArray(doc.tags) ? doc.tags.flatMap((tag) => tokenizeText(tag)) : []),
+  ]);
+}
+
+function buildSemanticFingerprint(doc = {}) {
+  const metadata = doc.metadata || {};
+  if (typeof metadata.semanticKey === 'string' && metadata.semanticKey.trim()) {
+    return normalizeKey(metadata.semanticKey, 'semantic');
+  }
+
+  const tokens = collectDocumentTokens(doc).slice(0, 6);
+  if (tokens.length > 0) {
+    return normalizeKey(tokens.join('-'), 'semantic');
+  }
+
+  return normalizeKey(doc.title || doc.id || 'semantic', 'semantic');
+}
+
+function scoreTokenOverlap(queryTokens = [], candidateTokens = []) {
+  if (queryTokens.length === 0) return 0;
+  const tokenSet = new Set(candidateTokens);
+  let score = 0;
+
+  for (const token of queryTokens) {
+    if (tokenSet.has(token)) {
+      score += token.length >= 7 ? 3 : 2;
+    }
+  }
+
+  return score;
+}
+
+function recencyBoost(createdAt) {
+  if (!createdAt) return 0;
+  const createdMs = new Date(createdAt).getTime();
+  if (!Number.isFinite(createdMs)) return 0;
+
+  const ageHours = (Date.now() - createdMs) / 3_600_000;
+  if (ageHours < 24) return 2;
+  if (ageHours < 24 * 7) return 1;
+  return 0;
+}
+
+function selectRepresentative(members = [], queryTokens = [], scorer = null) {
+  return members
+    .slice()
+    .sort((left, right) => {
+      const leftScore = scoreDocumentForSelection(left, queryTokens, scorer);
+      const rightScore = scoreDocumentForSelection(right, queryTokens, scorer);
+      return rightScore - leftScore;
+    })[0] || null;
+}
+
+function scoreDocumentForSelection(doc, queryTokens = [], scorer = null) {
+  const overlapScore = scoreTokenOverlap(queryTokens, collectDocumentTokens(doc));
+  const baseScore = typeof scorer === 'function' ? scorer(doc, queryTokens) : 0;
+  return overlapScore + baseScore + recencyBoost(doc.createdAt);
+}
+
+function buildSemanticDigest(members = []) {
+  if (members.length === 0) return '';
+  const titles = uniqueList(members.map((member) => member.title).filter(Boolean)).slice(0, 2);
+  const summary = summarizeText(members[0].content, 140);
+  return [titles.join(' | '), summary].filter(Boolean).join(' | ');
+}
+
+function buildXMemoryHierarchy(documents = [], { query = '', scorer = null } = {}) {
+  const queryTokens = tokenizeText(query);
+  const themeMap = new Map();
+
+  for (const doc of documents) {
+    const themeKey = inferThemeKey(doc);
+    const semanticKey = `${themeKey}::${buildSemanticFingerprint(doc)}`;
+    const docTokens = collectDocumentTokens(doc);
+
+    let theme = themeMap.get(themeKey);
+    if (!theme) {
+      theme = {
+        id: themeKey,
+        label: themeKey.replace(/-/g, ' '),
+        tokens: [],
+        semantics: new Map(),
+        documents: [],
+      };
+      themeMap.set(themeKey, theme);
+    }
+
+    theme.tokens = uniqueList([...theme.tokens, ...docTokens, ...tokenizeText(theme.label)]);
+    theme.documents.push(doc);
+
+    let semantic = theme.semantics.get(semanticKey);
+    if (!semantic) {
+      semantic = {
+        id: semanticKey,
+        themeId: themeKey,
+        tokens: [],
+        members: [],
+      };
+      theme.semantics.set(semanticKey, semantic);
+    }
+
+    semantic.tokens = uniqueList([...semantic.tokens, ...docTokens]);
+    semantic.members.push(doc);
+  }
+
+  const themes = Array.from(themeMap.values()).map((theme) => {
+    const semantics = Array.from(theme.semantics.values()).map((semantic) => {
+      const representative = selectRepresentative(semantic.members, queryTokens, scorer);
+      const score = scoreTokenOverlap(queryTokens, semantic.tokens)
+        + recencyBoost(representative && representative.createdAt);
+
+      return {
+        ...semantic,
+        memberCount: semantic.members.length,
+        digest: buildSemanticDigest(semantic.members),
+        representative,
+        score,
+      };
+    }).sort((left, right) => right.score - left.score);
+
+    const topSemanticScore = semantics[0] ? semantics[0].score : 0;
+    const score = scoreTokenOverlap(queryTokens, theme.tokens)
+      + topSemanticScore
+      + recencyBoost(theme.documents[0] && theme.documents[0].createdAt);
+
+    return {
+      id: theme.id,
+      label: theme.label,
+      tokens: theme.tokens,
+      semanticCount: semantics.length,
+      documentCount: theme.documents.length,
+      score,
+      semantics,
+    };
+  }).sort((left, right) => right.score - left.score);
+
+  return {
+    query,
+    queryTokens,
+    themeCount: themes.length,
+    semanticCount: themes.reduce((sum, theme) => sum + theme.semanticCount, 0),
+    documentCount: documents.length,
+    themes,
+  };
+}
+
+function computeQueryCoverage(queryTokens = [], nodes = []) {
+  if (queryTokens.length === 0) return 1;
+
+  const tokenSet = new Set();
+  for (const node of nodes) {
+    for (const token of node.tokens || []) {
+      tokenSet.add(token);
+    }
+  }
+
+  const covered = queryTokens.filter((token) => tokenSet.has(token)).length;
+  return Number((covered / queryTokens.length).toFixed(4));
+}
+
+function shouldUseHierarchicalRetrieval(namespaces = []) {
+  if (!Array.isArray(namespaces) || namespaces.length === 0) return true;
+  return !namespaces.every((namespace) => namespace === 'research');
+}
+
+function retrieveHierarchicalDocuments({
+  documents = [],
+  query = '',
+  maxItems = 8,
+  maxChars = 6000,
+  scorer = null,
+  measureDocument = null,
+  coverageTarget = 0.6,
+} = {}) {
+  const hierarchy = buildXMemoryHierarchy(documents, { query, scorer });
+  const queryTokens = hierarchy.queryTokens;
+  const selectedDocuments = [];
+  const selectedSemantics = [];
+  const selectedDocumentIds = new Set();
+  const selectedSemanticIds = new Set();
+  let usedChars = 0;
+  let skippedByMaxChars = 0;
+
+  const semanticBudget = Math.max(1, Math.min(maxItems, Math.ceil(maxItems * 0.6)));
+  const rankedThemes = hierarchy.themes.filter((theme) => queryTokens.length === 0 || theme.score > 0);
+  const themeCursor = rankedThemes.map(() => 0);
+
+  function getDocumentChars(doc) {
+    if (typeof measureDocument === 'function') {
+      return measureDocument(doc);
+    }
+    return `${doc.title || ''}\n${doc.content || ''}`.length;
+  }
+
+  function trySelectDocument(doc) {
+    if (!doc || selectedDocumentIds.has(doc.id) || selectedDocuments.length >= maxItems) {
+      return false;
+    }
+
+    const docChars = getDocumentChars(doc);
+    if (usedChars + docChars > maxChars) {
+      skippedByMaxChars += 1;
+      return false;
+    }
+
+    selectedDocuments.push(doc);
+    selectedDocumentIds.add(doc.id);
+    usedChars += docChars;
+    return true;
+  }
+
+  function computeDocumentCoverage(candidateDocs) {
+    return computeQueryCoverage(
+      queryTokens,
+      candidateDocs.map((doc) => ({ tokens: collectDocumentTokens(doc) }))
+    );
+  }
+
+  while (selectedSemantics.length < semanticBudget && rankedThemes.length > 0) {
+    let progress = false;
+
+    for (let i = 0; i < rankedThemes.length; i += 1) {
+      const theme = rankedThemes[i];
+      const semantics = theme.semantics;
+      while (themeCursor[i] < semantics.length && selectedSemanticIds.has(semantics[themeCursor[i]].id)) {
+        themeCursor[i] += 1;
+      }
+
+      const semantic = semantics[themeCursor[i]];
+      if (!semantic) continue;
+
+      themeCursor[i] += 1;
+      if (!trySelectDocument(semantic.representative)) {
+        continue;
+      }
+
+      selectedSemanticIds.add(semantic.id);
+      selectedSemantics.push(semantic);
+      progress = true;
+
+      if (selectedSemantics.length >= semanticBudget) {
+        break;
+      }
+    }
+
+    if (!progress) break;
+    if (selectedDocuments.length >= maxItems) break;
+  }
+
+  let queryCoverage = computeDocumentCoverage(selectedDocuments);
+  const initialCoverage = queryCoverage;
+  const expansionCandidates = [];
+
+  for (const semantic of selectedSemantics) {
+    for (const member of semantic.members) {
+      if (member.id === (semantic.representative && semantic.representative.id)) continue;
+      const memberTokens = collectDocumentTokens(member);
+      const newCoverage = computeQueryCoverage(queryTokens, [
+        ...selectedDocuments.map((doc) => ({ tokens: collectDocumentTokens(doc) })),
+        { tokens: memberTokens },
+      ]);
+
+      expansionCandidates.push({
+        doc: member,
+        semanticId: semantic.id,
+        coverageGain: Number((newCoverage - queryCoverage).toFixed(4)),
+        score: scoreDocumentForSelection(member, queryTokens, scorer),
+      });
+    }
+  }
+
+  expansionCandidates.sort((left, right) => {
+    if (right.coverageGain !== left.coverageGain) {
+      return right.coverageGain - left.coverageGain;
+    }
+    return right.score - left.score;
+  });
+
+  let expandedEpisodes = 0;
+  for (const candidate of expansionCandidates) {
+    if (selectedDocuments.length >= maxItems) break;
+    if (queryCoverage >= coverageTarget && candidate.coverageGain <= 0) break;
+    if (!trySelectDocument(candidate.doc)) continue;
+    queryCoverage = computeDocumentCoverage(selectedDocuments);
+    expandedEpisodes += 1;
+  }
+
+  return {
+    items: selectedDocuments,
+    usedChars,
+    skippedByMaxChars,
+    hierarchy,
+    retrieval: {
+      strategy: 'hierarchical',
+      themeCount: hierarchy.themeCount,
+      semanticCount: hierarchy.semanticCount,
+      selectedThemes: uniqueList(selectedSemantics.map((semantic) => semantic.themeId)),
+      selectedSemanticGroups: selectedSemantics.map((semantic) => semantic.id),
+      representativeCount: Math.min(selectedSemantics.length, selectedDocuments.length),
+      expandedEpisodes,
+      queryCoverage,
+      initialCoverage,
+      coverageTarget,
+    },
+  };
+}
+
+module.exports = {
+  buildXMemoryHierarchy,
+  buildSemanticFingerprint,
+  collectDocumentTokens,
+  computeQueryCoverage,
+  inferThemeKey,
+  normalizeKey,
+  retrieveHierarchicalDocuments,
+  shouldUseHierarchicalRetrieval,
+  summarizeText,
+  tokenizeText,
+};

package/skills/agent-memory/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: Agent Memory
+description: Recall past mistakes and capture feedback so your agent stops repeating errors. Works locally via MCP server — no API key needed.
+---
+
+# Agent Memory
+
+Give your agent persistent memory across sessions. Before starting any task, recall what went wrong last time. After completing work, capture whether it succeeded or failed. Prevention rules are auto-generated from repeated mistakes.
+
+## Setup
+
+Add the MCP server (one-time):
+
+```bash
+claude mcp add thumbgate -- npx -y thumbgate serve
+```
+
+No API key needed. All data stays local.
+
+## When to Use
+
+- Starting a new task or session — recall past context first
+- After completing work that succeeded or failed — capture feedback
+- When the agent keeps making the same mistake — check prevention rules
+
+## Workflow
+
+### Step 1: Recall past context (do this FIRST on every task)
+
+Call the `recall` MCP tool with a description of your current task. The tool returns:
+
+- Past feedback relevant to this task (vector similarity search)
+- Active prevention rules (auto-generated from repeated failures)
+- Recent feedback summary with approval rate
+
+Read the prevention rules carefully. These are patterns that failed before — follow them.
+
+### Step 2: Do your work
+
+Complete the task as normal. Keep track of what you did and whether it worked.
+
+### Step 3: Capture feedback
+
+Call the `capture_feedback` MCP tool:
+
+**If succeeded:**
+- signal: `up`
+- context: What worked and why
+- tags: Category labels
+
+**If failed:**
+- signal: `down`
+- context: What you were trying to do
+- whatWentWrong: Specific failure description
+- whatToChange: How to avoid this next time
+- tags: Category labels
+
+Vague feedback like "it failed" will be rejected. Be specific.
+
+### Step 4: Check improvement (optional)
+
+Call the `feedback_stats` MCP tool to see approval rate, top failure domains, and whether the agent is trending better or worse.
+
+## Available MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `recall` | Search past feedback and prevention rules for current task |
+| `capture_feedback` | Record what worked or failed with structured context |
+| `prevention_rules` | View auto-generated rules from repeated mistakes |
+| `feedback_stats` | Approval rate, trend analysis, top failure domains |
+| `feedback_summary` | Human-readable summary of recent signals |
+
+## MCP Profiles
+
+| Profile | Tools | Use case |
+|---------|-------|----------|
+| `essential` | 5 core tools | Default — start here |
+| `commerce` | 6 tools + commerce_recall | Agentic commerce agents |
+| `default` | 12 tools | Full pipeline including DPO export |
+
+Set profile: `THUMBGATE_MCP_PROFILE=essential npx thumbgate serve`
+
+## How Prevention Rules Work
+
+1. Agent makes mistake A → you capture `down` feedback
+2. Agent makes mistake A again → you capture `down` feedback again
+3. System detects pattern → auto-generates prevention rule: "NEVER do A"
+4. Next session → `recall` returns the rule → agent follows it
+
+This is the core value. The agent doesn't learn — but it reads the rules and follows them.
+
+## Links
+
+- [GitHub](https://github.com/IgorGanapolsky/thumbgate)
+- [npm](https://www.npmjs.com/package/thumbgate)
+- [MCP Registry](https://registry.modelcontextprotocol.io)

package/skills/solve-architecture-autonomy/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: solve-architecture-autonomy
+description: Automated skill to handle architecture, autonomy, crisis, debug, deployment, error, execution, external-assessment, feedback, inefficiency, negative, railway, revenue, roi, simplification, user-frustration patterns efficiently.
+diagnosis: Repeated execution failure in this domain.
+status: materialized
+---
+
+# SOLVE-ARCHITECTURE-AUTONOMY Capability
+
+## Problem
+I provided a plan and research instead of immediately deploy
+
+## Automated Diagnosis
+Repeated execution failure in this domain.
+
+## Usage
+The agent should call the `handle_architecture` tool when tasks involve `architecture, autonomy, crisis, debug, deployment, error, execution, external-assessment, feedback, inefficiency, negative, railway, revenue, roi, simplification, user-frustration`.

package/skills/solve-architecture-autonomy/tool.js

@@ -0,0 +1,33 @@
+/**
+ * Automated Skill: solve-architecture-autonomy
+ * Generated: 2026-03-13T15:50:58.840Z
+ * 
+ * This tool was materialized by the EvoSkill loop to address:
+ * "I provided a plan and research instead of immediately deploy"
+ */
+
+const { execSync } = require('child_process');
+
+/**
+ * Fixes I provided a plan and research instead of immediately deploy
+ */
+async function handle_architecture(args) {
+  const { context } = args;
+  
+  // LOGIC: Materialized code should implement the fix derived from the diagnosis.
+  // For now, we provide a structured wrapper that logs intent and applies
+  // the suggested corrective action.
+  
+  console.log(`[EVOSKILL] Executing handle_architecture to resolve: I provided a plan and research instead of immediately deploy`);
+  
+  // Corrective action placeholder - in a full loop, this would be LLM-generated code
+  // derived from the 'how-to-avoid' fields in memory-log.jsonl.
+  
+  return {
+    status: 'success',
+    appliedFix: `Automated handling of I provided a plan and research instead of immediately deploy pattern.`,
+    context: context
+  };
+}
+
+module.exports = { handle_architecture };

package/skills/thumbgate/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: thumbgate
+description: >
+  ThumbGate provides pre-action gates for AI coding agents. It captures
+  thumbs-up/down feedback on agent actions, auto-promotes repeated failures
+  into prevention rules, and blocks known-bad tool calls via PreToolUse hooks.
+  Trigger when the user wants to add safety guardrails to an AI agent workflow,
+  capture structured feedback on agent output, generate prevention rules from
+  failure patterns, gate high-risk actions before execution, or export DPO
+  training pairs from production feedback. Works with any MCP-compatible agent
+  including Cursor, Codex, Gemini CLI, Amp, and OpenCode.
+---
+
+# ThumbGate
+
+Pre-action gates that stop AI coding agents from repeating known mistakes.
+
+## Quick Start
+
+```bash
+npx thumbgate init
+```
+
+This installs the MCP server and wires it into your agent's tool configuration. No API keys required for the free tier.
+
+Or install globally:
+
+```bash
+npm install -g thumbgate
+thumbgate init
+```
+
+### MCP Configuration
+
+Add to your agent's MCP config (e.g., `claude_desktop_config.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "thumbgate": {
+      "command": "npx",
+      "args": ["-y", "thumbgate"]
+    }
+  }
+}
+```
+
+## How It Works
+
+### Feedback Capture
+
+When an agent action succeeds or fails, capture structured feedback:
+
+- **Thumbs up**: Records what worked, tags it, and stores it as a reusable pattern.
+- **Thumbs down**: Records the failure context, what went wrong, and what to change. Repeated failures auto-promote into prevention rules.
+
+### Prevention Rules
+
+After a failure pattern repeats (default: 2 occurrences), ThumbGate auto-generates a prevention rule. These rules are injected into agent context before every tool call, blocking the known-bad pattern before it executes.
+
+### Pre-Action Gates
+
+Gates intercept tool calls via the MCP PreToolUse hook. Each gate checks the proposed action against:
+
+1. Prevention rules generated from past failures
+2. Thompson Sampling confidence scores (adaptive sensitivity)
+3. LanceDB vector similarity to known-bad patterns
+
+If a match is found, the gate blocks execution and surfaces the prior failure context.
+
+### Context Packs
+
+Bounded retrieval of relevant feedback history for the current task. The agent gets exactly the lessons that matter, not the entire history.
+
+## MCP Tools Provided
+
+| Tool | Description |
+|------|-------------|
+| `capture_feedback` | Record thumbs-up/down with structured context |
+| `search_lessons` | Query the lesson DB by keyword or semantic similarity |
+| `get_prevention_rules` | Retrieve active prevention rules for the current context |
+| `session_primer` | Get session handoff context (last task, next step, blockers) |
+| `export_dpo` | Export feedback pairs in DPO training format |
+
+## Tiers
+
+| | Free | Pro | Team |
+|---|---|---|---|
+| Feedback capture | Unlimited | Unlimited | Unlimited |
+| Lesson search | 5/day | Unlimited | Unlimited |
+| Active gates | 5 | Unlimited | Unlimited |
+| Dashboard | - | Yes | Yes |
+| DPO export | - | Yes | Yes |
+| Seats | 1 | 1 | Per-seat |
+| Price | $0 | $19/mo | $12/seat/mo |
+
+Start a 7-day free trial of Pro: <https://buy.stripe.com/fZu9AT3Ug6zcdWh0XN3sI08>
+
+## Compatibility
+
+ThumbGate works with any MCP-compatible agent:
+
+- Cursor
+- Codex
+- Gemini CLI
+- Amp
+- OpenCode
+- Any agent supporting the Model Context Protocol
+
+## Links
+
+- NPM: [thumbgate](https://www.npmjs.com/package/thumbgate)
+- Repository: [IgorGanapolsky/ThumbGate](https://github.com/IgorGanapolsky/ThumbGate)
+- Dashboard: <https://thumbgate-production.up.railway.app/dashboard>