agentdb 1.1.8 → 1.2.0

package/dist/cli/agentdb-cli.js

@@ -428,6 +428,64 @@ class AgentDBCLI {
 // ============================================================================
 // CLI Entry Point
 // ============================================================================
+async function handleMcpCommands(subcommand, args) {
+    if (!subcommand || subcommand === 'start') {
+        // Start the actual MCP server
+        const { spawn } = await import('child_process');
+        const mcpServerPath = path.join(__dirname, '../mcp/agentdb-mcp-server.js');
+
+        const proc = spawn('node', [mcpServerPath], {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                AGENTDB_PATH: process.env.AGENTDB_PATH || './agentdb.db'
+            }
+        });
+
+        proc.on('exit', (code) => {
+            process.exit(code || 0);
+        });
+
+        // Handle termination signals
+        process.on('SIGINT', () => {
+            proc.kill('SIGINT');
+        });
+
+        process.on('SIGTERM', () => {
+            proc.kill('SIGTERM');
+        });
+    }
+    else if (subcommand === 'list' || subcommand === 'tools') {
+        console.log('\n📦 AgentDB MCP Tools (15 total)\n');
+        console.log('Reflexion Memory:');
+        console.log('  1. reflexion_store    - Store episodes with critique');
+        console.log('  2. reflexion_retrieve - Retrieve relevant episodes');
+        console.log('  3. reflexion_critique_summary - Get critique lessons\n');
+        console.log('Skill Library:');
+        console.log('  4. skill_create       - Create reusable skill');
+        console.log('  5. skill_search       - Search skills');
+        console.log('  6. skill_consolidate  - Auto-create from episodes\n');
+        console.log('Causal Memory:');
+        console.log('  7. causal_add_edge    - Add causal edge');
+        console.log('  8. causal_query       - Query causal effects');
+        console.log('  9. causal_experiment_create - Create A/B test');
+        console.log('  10. causal_experiment_calculate - Calculate uplift\n');
+        console.log('Causal Recall:');
+        console.log('  11. recall_with_certificate - Retrieve with provenance\n');
+        console.log('Nightly Learner:');
+        console.log('  12. learner_discover  - Auto-discover patterns');
+        console.log('  13. learner_prune     - Clean low-quality edges\n');
+        console.log('Database:');
+        console.log('  14. db_stats          - Database statistics');
+        console.log('  15. db_export         - Export data\n');
+    }
+    else {
+        log.error(`Unknown mcp subcommand: ${subcommand}`);
+        console.log('\nUsage:');
+        console.log('  agentdb mcp [start]   - Start MCP server (stdio)');
+        console.log('  agentdb mcp list      - List available MCP tools');
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
@@ -458,6 +516,9 @@ async function main() {
         else if (command === 'db') {
             await handleDbCommands(cli, subcommand, args.slice(2));
         }
+        else if (command === 'mcp') {
+            await handleMcpCommands(subcommand, args.slice(2));
+        }
         else {
             log.error(`Unknown command: ${command}`);
             printHelp();
@@ -700,6 +761,13 @@ ${colors.bright}DATABASE COMMANDS:${colors.reset}
   agentdb db stats
     Show database statistics
 
+${colors.bright}MCP INTEGRATION:${colors.reset}
+  agentdb mcp [start]
+    Start MCP server for Claude Desktop integration
+
+  agentdb mcp list
+    List all available MCP tools
+
 ${colors.bright}ENVIRONMENT:${colors.reset}
   AGENTDB_PATH    Database file path (default: ./agentdb.db)
 

package/dist/mcp/agentdb-mcp-server.js

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+/**
+ * AgentDB MCP Server
+ * Production-ready MCP server for Claude Desktop integration
+ * Exposes AgentDB frontier memory features via MCP protocol
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import Database from 'better-sqlite3';
+import { CausalMemoryGraph } from '../controllers/CausalMemoryGraph.js';
+import { CausalRecall } from '../controllers/CausalRecall.js';
+import { ReflexionMemory } from '../controllers/ReflexionMemory.js';
+import { SkillLibrary } from '../controllers/SkillLibrary.js';
+import { NightlyLearner } from '../controllers/NightlyLearner.js';
+import { EmbeddingService } from '../controllers/EmbeddingService.js';
+import * as path from 'path';
+
+// ============================================================================
+// Initialize AgentDB Controllers
+// ============================================================================
+const dbPath = process.env.AGENTDB_PATH || './agentdb.db';
+const db = new Database(dbPath);
+
+// Initialize embedding service
+const embeddingService = new EmbeddingService({
+  model: 'Xenova/all-MiniLM-L6-v2',
+  cacheDir: './.agentdb/embeddings'
+});
+await embeddingService.initialize();
+
+// Initialize all controllers
+const causalGraph = new CausalMemoryGraph(db);
+const causalRecall = new CausalRecall(db, embeddingService);
+const reflexion = new ReflexionMemory(db, embeddingService);
+const skills = new SkillLibrary(db, embeddingService);
+const learner = new NightlyLearner(db, causalGraph, reflexion);
+
+// ============================================================================
+// MCP Server Setup
+// ============================================================================
+const server = new Server(
+  {
+    name: 'agentdb',
+    version: '1.2.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+const tools = [
+  {
+    name: 'reflexion_store',
+    description: 'Store an episode with self-critique for reflexion-based learning',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session identifier' },
+        task: { type: 'string', description: 'Task description' },
+        reward: { type: 'number', description: 'Task reward (0-1)' },
+        success: { type: 'boolean', description: 'Whether task succeeded' },
+        critique: { type: 'string', description: 'Self-critique reflection' },
+        input: { type: 'string', description: 'Task input' },
+        output: { type: 'string', description: 'Task output' },
+        latency_ms: { type: 'number', description: 'Execution latency' },
+        tokens: { type: 'number', description: 'Tokens used' },
+      },
+      required: ['session_id', 'task', 'reward', 'success'],
+    },
+  },
+  {
+    name: 'reflexion_retrieve',
+    description: 'Retrieve relevant past episodes for learning from experience',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'Task to find similar episodes for' },
+        k: { type: 'number', description: 'Number of episodes to retrieve', default: 5 },
+        only_failures: { type: 'boolean', description: 'Only retrieve failures' },
+        only_successes: { type: 'boolean', description: 'Only retrieve successes' },
+        min_reward: { type: 'number', description: 'Minimum reward threshold' },
+      },
+      required: ['task'],
+    },
+  },
+  {
+    name: 'skill_create',
+    description: 'Create a reusable skill in the skill library',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Skill name' },
+        description: { type: 'string', description: 'What the skill does' },
+        code: { type: 'string', description: 'Skill implementation code' },
+        success_rate: { type: 'number', description: 'Initial success rate' },
+      },
+      required: ['name', 'description'],
+    },
+  },
+  {
+    name: 'skill_search',
+    description: 'Search for applicable skills by semantic similarity',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'Task to find skills for' },
+        k: { type: 'number', description: 'Number of skills to return', default: 10 },
+        min_success_rate: { type: 'number', description: 'Minimum success rate filter' },
+      },
+      required: ['task'],
+    },
+  },
+  {
+    name: 'causal_add_edge',
+    description: 'Add a causal relationship between actions and outcomes',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cause: { type: 'string', description: 'Causal action/intervention' },
+        effect: { type: 'string', description: 'Observed effect/outcome' },
+        uplift: { type: 'number', description: 'Causal uplift magnitude' },
+        confidence: { type: 'number', description: 'Confidence in causal claim (0-1)', default: 0.95 },
+        sample_size: { type: 'number', description: 'Number of observations', default: 0 },
+      },
+      required: ['cause', 'effect', 'uplift'],
+    },
+  },
+  {
+    name: 'causal_query',
+    description: 'Query causal effects to understand what actions cause what outcomes',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cause: { type: 'string', description: 'Filter by cause (optional)' },
+        effect: { type: 'string', description: 'Filter by effect (optional)' },
+        min_confidence: { type: 'number', description: 'Minimum confidence', default: 0.5 },
+        min_uplift: { type: 'number', description: 'Minimum uplift', default: 0.0 },
+        limit: { type: 'number', description: 'Maximum results', default: 10 },
+      },
+    },
+  },
+  {
+    name: 'recall_with_certificate',
+    description: 'Retrieve memories with causal utility scoring and provenance certificate',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Query for memory retrieval' },
+        k: { type: 'number', description: 'Number of results', default: 12 },
+        alpha: { type: 'number', description: 'Similarity weight', default: 0.7 },
+        beta: { type: 'number', description: 'Causal uplift weight', default: 0.2 },
+        gamma: { type: 'number', description: 'Recency weight', default: 0.1 },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'learner_discover',
+    description: 'Automatically discover causal patterns from episode history',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        min_attempts: { type: 'number', description: 'Minimum attempts required', default: 3 },
+        min_success_rate: { type: 'number', description: 'Minimum success rate', default: 0.6 },
+        min_confidence: { type: 'number', description: 'Minimum statistical confidence', default: 0.7 },
+        dry_run: { type: 'boolean', description: 'Preview without storing', default: false },
+      },
+    },
+  },
+  {
+    name: 'db_stats',
+    description: 'Get database statistics showing record counts',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+];
+
+// ============================================================================
+// Tool Handlers
+// ============================================================================
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'reflexion_store': {
+        const episodeId = await reflexion.storeEpisode({
+          sessionId: args.session_id,
+          task: args.task,
+          reward: args.reward,
+          success: args.success,
+          critique: args.critique || '',
+          input: args.input || '',
+          output: args.output || '',
+          latencyMs: args.latency_ms || 0,
+          tokens: args.tokens || 0,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✅ Stored episode #${episodeId}\nTask: ${args.task}\nReward: ${args.reward}\nSuccess: ${args.success}`,
+            },
+          ],
+        };
+      }
+
+      case 'reflexion_retrieve': {
+        const episodes = await reflexion.retrieveRelevant({
+          task: args.task,
+          k: args.k || 5,
+          onlyFailures: args.only_failures,
+          onlySuccesses: args.only_successes,
+          minReward: args.min_reward,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `🔍 Retrieved ${episodes.length} episodes:\n\n` +
+                episodes.map((ep, i) =>
+                  `${i + 1}. Episode ${ep.id}\n   Task: ${ep.task}\n   Reward: ${ep.reward.toFixed(2)}\n   Similarity: ${ep.similarity?.toFixed(3) || 'N/A'}`
+                ).join('\n\n'),
+            },
+          ],
+        };
+      }
+
+      case 'skill_create': {
+        const skillId = await skills.createSkill({
+          name: args.name,
+          description: args.description,
+          signature: { inputs: {}, outputs: {} },
+          code: args.code || '',
+          successRate: args.success_rate || 0.0,
+          uses: 0,
+          avgReward: 0.0,
+          avgLatencyMs: 0.0,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✅ Created skill #${skillId}: ${args.name}`,
+            },
+          ],
+        };
+      }
+
+      case 'skill_search': {
+        const foundSkills = await skills.searchSkills({
+          task: args.task,
+          k: args.k || 10,
+          minSuccessRate: args.min_success_rate || 0.0,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `🔍 Found ${foundSkills.length} skills:\n\n` +
+                foundSkills.map((skill, i) =>
+                  `${i + 1}. ${skill.name}\n   ${skill.description}\n   Success: ${(skill.successRate * 100).toFixed(1)}%`
+                ).join('\n\n'),
+            },
+          ],
+        };
+      }
+
+      case 'causal_add_edge': {
+        const edgeId = causalGraph.addCausalEdge({
+          fromMemoryId: 0,
+          fromMemoryType: args.cause,
+          toMemoryId: 0,
+          toMemoryType: args.effect,
+          similarity: 0,
+          uplift: args.uplift,
+          confidence: args.confidence || 0.95,
+          sampleSize: args.sample_size || 0,
+          evidenceIds: [],
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✅ Added causal edge #${edgeId}\n${args.cause} → ${args.effect}\nUplift: ${args.uplift}`,
+            },
+          ],
+        };
+      }
+
+      case 'causal_query': {
+        const edges = causalGraph.queryCausalEffects({
+          interventionMemoryId: 0,
+          interventionMemoryType: args.cause || '',
+          outcomeMemoryId: args.effect ? 0 : undefined,
+          minConfidence: args.min_confidence || 0.5,
+          minUplift: args.min_uplift || 0.0,
+        });
+        const limited = edges.slice(0, args.limit || 10);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `🔍 Found ${edges.length} causal edges:\n\n` +
+                limited.map((edge, i) =>
+                  `${i + 1}. ${edge.cause} → ${edge.effect}\n   Uplift: ${edge.uplift.toFixed(3)} (confidence: ${edge.confidence.toFixed(2)})`
+                ).join('\n\n'),
+            },
+          ],
+        };
+      }
+
+      case 'recall_with_certificate': {
+        const result = await causalRecall.recall(
+          'mcp-' + Date.now(),
+          args.query,
+          args.k || 12,
+          undefined,
+          'internal'
+        );
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `🔍 Retrieved ${result.candidates.length} results:\n\n` +
+                result.candidates.slice(0, 5).map((r, i) =>
+                  `${i + 1}. ${r.type} ${r.id}\n   Similarity: ${r.similarity.toFixed(3)}\n   Uplift: ${r.uplift?.toFixed(3) || '0.000'}`
+                ).join('\n\n') +
+                `\n\n📜 Certificate ID: ${result.certificate.id}`,
+            },
+          ],
+        };
+      }
+
+      case 'learner_discover': {
+        const discovered = await learner.discover({
+          minAttempts: args.min_attempts || 3,
+          minSuccessRate: args.min_success_rate || 0.6,
+          minConfidence: args.min_confidence || 0.7,
+          dryRun: args.dry_run || false,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `🌙 Discovered ${discovered.length} causal patterns:\n\n` +
+                discovered.slice(0, 10).map((edge, i) =>
+                  `${i + 1}. ${edge.cause} → ${edge.effect}\n   Uplift: ${edge.uplift.toFixed(3)} (n=${edge.sampleSize})`
+                ).join('\n\n'),
+            },
+          ],
+        };
+      }
+
+      case 'db_stats': {
+        const stats = {
+          causal_edges: db.prepare('SELECT COUNT(*) as count FROM causal_edges').get().count,
+          causal_experiments: db.prepare('SELECT COUNT(*) as count FROM causal_experiments').get().count,
+          causal_observations: db.prepare('SELECT COUNT(*) as count FROM causal_observations').get().count,
+          episodes: db.prepare('SELECT COUNT(*) as count FROM episodes').get().count,
+        };
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `📊 Database Statistics:\n\n` +
+                `Causal Edges: ${stats.causal_edges}\n` +
+                `Experiments: ${stats.causal_experiments}\n` +
+                `Observations: ${stats.causal_observations}\n` +
+                `Episodes: ${stats.episodes}`,
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ Error: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ============================================================================
+// Start Server
+// ============================================================================
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('🚀 AgentDB MCP Server running on stdio');
+  console.error('📦 9 tools available for Claude Desktop');
+}
+
+main().catch(console.error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentdb",
-  "version": "1.1.8",
-  "description": "AgentDB - Frontier Memory Features: Causal reasoning, reflexion memory, skill library, explainable recall, and automated learning for AI agents. 150x faster vector search with HNSW indexing.",
+  "version": "1.2.0",
+  "description": "AgentDB - Frontier Memory Features with MCP Integration: Causal reasoning, reflexion memory, skill library, and automated learning. 150x faster vector search. Full Claude Desktop support via Model Context Protocol.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,10 +55,12 @@
   },
   "homepage": "https://agentdb.ruv.io",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.1",
     "@xenova/transformers": "^2.17.2",
     "better-sqlite3": "^11.7.0",
     "chalk": "^5.3.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",