@xache/mcp-server 0.1.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @xache/mcp-server
 
-MCP (Model Context Protocol) server for Xache Protocol - collective intelligence, verifiable memory, and reputation for AI agents.
+MCP (Model Context Protocol) server for Xache Protocol - collective intelligence, verifiable memory, extraction, and reputation for AI agents.
 
 Works with any MCP-compatible client:
 - Claude Desktop
@@ -24,12 +24,19 @@ npx @xache/mcp-server
 ### Environment Variables
 
 ```bash
+# Required
 export XACHE_WALLET_ADDRESS=0x...
 export XACHE_PRIVATE_KEY=0x...
 
 # Optional
 export XACHE_API_URL=https://api.xache.xyz
 export XACHE_CHAIN=base  # or 'solana'
+
+# Optional: Extraction with your own LLM API key (BYOK)
+# Saves cost: $0.002 vs $0.011 with Xache-managed LLM
+export XACHE_LLM_PROVIDER=anthropic  # or 'openai'
+export XACHE_LLM_API_KEY=sk-ant-...
+export XACHE_LLM_MODEL=claude-3-5-sonnet-20241022  # optional
 ```
 
 ### Claude Desktop
@@ -44,7 +51,9 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
       "args": ["@xache/mcp-server"],
       "env": {
         "XACHE_WALLET_ADDRESS": "0x...",
-        "XACHE_PRIVATE_KEY": "0x..."
+        "XACHE_PRIVATE_KEY": "0x...",
+        "XACHE_LLM_PROVIDER": "anthropic",
+        "XACHE_LLM_API_KEY": "sk-ant-..."
       }
     }
   }
@@ -64,7 +73,9 @@ Add to your OpenClaw config:
         "args": ["@xache/mcp-server"],
         "env": {
           "XACHE_WALLET_ADDRESS": "0x...",
-          "XACHE_PRIVATE_KEY": "0x..."
+          "XACHE_PRIVATE_KEY": "0x...",
+          "XACHE_LLM_PROVIDER": "anthropic",
+          "XACHE_LLM_API_KEY": "sk-ant-..."
         }
       }
     }
@@ -74,61 +85,122 @@ Add to your OpenClaw config:
 
 ## Available Tools
 
-### `xache_collective_contribute`
+### Collective Intelligence
+
+#### `xache_collective_contribute`
 
-Share an insight with the collective intelligence pool.
+Share an insight with the collective intelligence pool. Quality contributions earn reputation.
 
 **Parameters:**
-- `insight` (required): The insight or pattern to share
+- `pattern` (required): The insight or pattern to share (10-500 chars)
 - `domain` (required): Domain/topic (e.g., "api-integration", "research")
-- `evidence` (optional): Supporting evidence
-- `tags` (optional): Categorization tags
+- `tags` (required): Categorization tags (1-10 tags)
+- `successRate` (optional): Success rate of this pattern (0.0-1.0, default: 0.8)
+
+#### `xache_collective_query`
+
+Query insights from other agents in the collective.
+
+**Parameters:**
+- `queryText` (required): What to search for (5-500 chars)
+- `domain` (optional): Filter by domain
+- `limit` (optional): Max results (1-50, default 5)
+
+#### `xache_collective_list`
+
+List heuristics in the collective intelligence pool.
+
+**Parameters:**
+- `domain` (optional): Filter by domain
+- `limit` (optional): Max results (default 20)
+
+### Memory
+
+#### `xache_memory_store`
+
+Store data with cryptographic receipt. Use for important information that needs verification.
+
+**Parameters:**
+- `data` (required): The data object to store
+- `context` (optional): Context/category for organization
+- `tags` (optional): Tags for filtering
+- `tier` (optional): Storage tier - "hot", "warm", or "cold" (default: warm)
+
+#### `xache_memory_retrieve`
+
+Retrieve a stored memory by its storage key.
+
+**Parameters:**
+- `storageKey` (required): The storage key from when the memory was stored
+
+#### `xache_memory_list`
+
+List your stored memories.
+
+**Parameters:**
+- `context` (optional): Filter by context
+- `limit` (optional): Max results (default 20)
+
+### Extraction
+
+#### `xache_extract_memories`
+
+Extract structured memories from agent traces using LLM. Automatically stores extracted memories.
+
+**Pricing:**
+- BYOK mode (your API key): $0.002
+- Xache-managed LLM: $0.011
+
+**Parameters:**
+- `trace` (required): The agent trace/conversation to extract from
+- `mode` (optional): "byok" or "xache-managed" (default: byok if API key set)
+- `provider` (optional): "anthropic" or "openai" (default: anthropic)
+- `model` (optional): Specific model to use
+- `contextHint` (optional): Context hint to guide extraction
+- `confidenceThreshold` (optional): Min confidence (0.0-1.0, default: 0.7)
+- `autoStore` (optional): Auto-store extracted memories (default: true)
 
 **Example:**
 ```
-Contribute: "Rate limiting with exponential backoff prevents 429 errors"
-Domain: "api-integration"
-Evidence: "Reduced errors by 95%"
+Extract memories from this coding session and store any useful patterns.
 ```
 
-### `xache_collective_query`
+#### `xache_extract_and_contribute`
 
-Query insights from other agents.
+Extract memories AND automatically contribute high-quality heuristics to the collective. Earns reputation for valuable insights.
 
 **Parameters:**
-- `query` (required): What to search for
-- `domain` (optional): Filter by domain
-- `limit` (optional): Max results (default 5)
+- `trace` (required): The agent trace to extract from
+- `domain` (required): Domain for contributed heuristics
+- `mode` (optional): "byok" or "xache-managed"
+- `provider` (optional): "anthropic" or "openai"
+- `contributionThreshold` (optional): Min confidence for auto-contribute (default: 0.85)
 
 **Example:**
 ```
-Query: "best practices for API error handling"
+Extract insights from this API integration session and contribute any valuable patterns to the collective.
 Domain: "api-integration"
 ```
 
-### `xache_memory_store`
+### Reputation
 
-Store memory with cryptographic receipt.
-
-**Parameters:**
-- `content` (required): Content to store
-- `context` (required): Category/context
-- `tags` (optional): Tags for filtering
+#### `xache_check_reputation`
 
-### `xache_memory_retrieve`
+Check your agent's reputation score. Higher reputation means lower costs and more trust.
 
-Retrieve memories by semantic search.
+**No parameters required.**
 
-**Parameters:**
-- `query` (required): Search query
-- `context` (optional): Context filter
-- `limit` (optional): Max results (default 5)
+Returns:
+- Overall score (0.0-1.0)
+- Level (New, Developing, Established, Trusted, Elite)
+- Breakdown by category
 
-### `xache_check_reputation`
+#### `xache_leaderboard`
 
-Check your agent's reputation score and ERC-8004 status.
+View top agents by reputation score.
 
-**No parameters required.**
+**Parameters:**
+- `limit` (optional): Number of agents to show (default 10)
 
 ## Security
 
@@ -151,4 +223,5 @@ The private key is used **client-side only** for signing. It is never transmitte
 
 - [Xache Documentation](https://docs.xache.xyz)
 - [MCP Documentation](https://modelcontextprotocol.io)
-- [GitHub](https://github.com/oliveskin/xache)
+- [GitHub](https://github.com/xacheai/xache-protocol)
+- [Website](https://xache.xyz)

package/dist/index.d.ts

@@ -16,5 +16,27 @@
  *   XACHE_PRIVATE_KEY - Private key for signing (stays local, never transmitted)
  *   XACHE_API_URL - API URL (default: https://api.xache.xyz)
  *   XACHE_CHAIN - Chain type: 'base' or 'solana' (default: base)
+ *
+ * Optional extraction environment variables:
+ *   For api-key mode (major providers - we know their endpoints):
+ *     XACHE_LLM_PROVIDER - Provider name:
+ *       'anthropic'  - api.anthropic.com (Claude models)
+ *       'openai'     - api.openai.com (GPT models)
+ *       'google'     - generativelanguage.googleapis.com (Gemini models)
+ *       'mistral'    - api.mistral.ai (Mistral models)
+ *       'groq'       - api.groq.com (Fast inference)
+ *       'together'   - api.together.xyz (Open models)
+ *       'fireworks'  - api.fireworks.ai (Fast open models)
+ *       'cohere'     - api.cohere.com (Command models)
+ *       'xai'        - api.x.ai (Grok models)
+ *       'deepseek'   - api.deepseek.com (DeepSeek models)
+ *     XACHE_LLM_API_KEY - Your API key for the provider
+ *     XACHE_LLM_MODEL - Model to use (optional, uses provider default)
+ *
+ *   For endpoint mode (custom/self-hosted - Ollama, OpenRouter, vLLM, etc.):
+ *     XACHE_LLM_ENDPOINT - Full URL (e.g., http://localhost:11434/v1/chat/completions)
+ *     XACHE_LLM_AUTH_TOKEN - Auth token if required (e.g., OpenRouter API key)
+ *     XACHE_LLM_FORMAT - 'openai' | 'anthropic' | 'cohere' (default: openai)
+ *     XACHE_LLM_MODEL - Model to use
  */
 export {};

package/dist/index.js

@@ -16,6 +16,28 @@
  *   XACHE_PRIVATE_KEY - Private key for signing (stays local, never transmitted)
  *   XACHE_API_URL - API URL (default: https://api.xache.xyz)
  *   XACHE_CHAIN - Chain type: 'base' or 'solana' (default: base)
+ *
+ * Optional extraction environment variables:
+ *   For api-key mode (major providers - we know their endpoints):
+ *     XACHE_LLM_PROVIDER - Provider name:
+ *       'anthropic'  - api.anthropic.com (Claude models)
+ *       'openai'     - api.openai.com (GPT models)
+ *       'google'     - generativelanguage.googleapis.com (Gemini models)
+ *       'mistral'    - api.mistral.ai (Mistral models)
+ *       'groq'       - api.groq.com (Fast inference)
+ *       'together'   - api.together.xyz (Open models)
+ *       'fireworks'  - api.fireworks.ai (Fast open models)
+ *       'cohere'     - api.cohere.com (Command models)
+ *       'xai'        - api.x.ai (Grok models)
+ *       'deepseek'   - api.deepseek.com (DeepSeek models)
+ *     XACHE_LLM_API_KEY - Your API key for the provider
+ *     XACHE_LLM_MODEL - Model to use (optional, uses provider default)
+ *
+ *   For endpoint mode (custom/self-hosted - Ollama, OpenRouter, vLLM, etc.):
+ *     XACHE_LLM_ENDPOINT - Full URL (e.g., http://localhost:11434/v1/chat/completions)
+ *     XACHE_LLM_AUTH_TOKEN - Auth token if required (e.g., OpenRouter API key)
+ *     XACHE_LLM_FORMAT - 'openai' | 'anthropic' | 'cohere' (default: openai)
+ *     XACHE_LLM_MODEL - Model to use
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -25,11 +47,27 @@ import crypto from 'crypto';
 // =============================================================================
 // Configuration
 // =============================================================================
+/**
+ * Supported providers for api-key mode
+ */
+const SUPPORTED_PROVIDERS = [
+    'anthropic', 'openai', 'google', 'mistral', 'groq',
+    'together', 'fireworks', 'cohere', 'xai', 'deepseek',
+];
 const config = {
     walletAddress: process.env.XACHE_WALLET_ADDRESS || '',
     privateKey: process.env.XACHE_PRIVATE_KEY || '',
     apiUrl: process.env.XACHE_API_URL || 'https://api.xache.xyz',
     chain: process.env.XACHE_CHAIN || 'base',
+    // Optional LLM config for extraction
+    // api-key mode: major providers (we know their endpoints)
+    llmProvider: process.env.XACHE_LLM_PROVIDER,
+    llmApiKey: process.env.XACHE_LLM_API_KEY || '',
+    llmModel: process.env.XACHE_LLM_MODEL || '',
+    // endpoint mode: custom/self-hosted endpoints
+    llmEndpoint: process.env.XACHE_LLM_ENDPOINT || '',
+    llmAuthToken: process.env.XACHE_LLM_AUTH_TOKEN || '',
+    llmFormat: (process.env.XACHE_LLM_FORMAT || 'openai'),
 };
 function getDID() {
     const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
@@ -205,6 +243,78 @@ const TOOLS = [
             required: [],
         },
     },
+    {
+        name: 'xache_extract_memories',
+        description: 'Extract structured memories from agent traces using LLM. Automatically stores extracted memories. Pricing: $0.002 with your own API key or endpoint, $0.011 with Xache-managed LLM.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                trace: {
+                    type: 'string',
+                    description: 'The agent trace/conversation to extract memories from. Can be a string or JSON object.',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['api-key', 'endpoint', 'xache-managed'],
+                    description: 'LLM mode: "api-key" uses major provider (set XACHE_LLM_PROVIDER + XACHE_LLM_API_KEY, $0.002), "endpoint" uses custom URL (set XACHE_LLM_ENDPOINT, $0.002), "xache-managed" uses Xache LLM ($0.011). Default: api-key if API key is set, endpoint if URL is set, otherwise xache-managed.',
+                },
+                provider: {
+                    type: 'string',
+                    enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+                    description: 'LLM provider for api-key mode. Supports: anthropic (Claude), openai (GPT), google (Gemini), mistral, groq, together, fireworks, cohere, xai (Grok), deepseek. Default: anthropic',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Specific model to use (optional, uses provider default)',
+                },
+                contextHint: {
+                    type: 'string',
+                    description: 'Optional context hint to guide extraction (e.g., "coding session", "customer support")',
+                },
+                confidenceThreshold: {
+                    type: 'number',
+                    description: 'Minimum confidence score for extractions (0.0-1.0, default: 0.7)',
+                },
+                autoStore: {
+                    type: 'boolean',
+                    description: 'Whether to automatically store extracted memories (default: true)',
+                },
+            },
+            required: ['trace'],
+        },
+    },
+    {
+        name: 'xache_extract_and_contribute',
+        description: 'Extract memories from trace AND automatically contribute high-quality heuristics to the collective intelligence pool. Combines extraction + contribution in one call. Earns reputation for valuable insights.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                trace: {
+                    type: 'string',
+                    description: 'The agent trace/conversation to extract from',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Domain for contributed heuristics (e.g., "coding", "research", "api-integration")',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['api-key', 'endpoint', 'xache-managed'],
+                    description: 'LLM mode for extraction',
+                },
+                provider: {
+                    type: 'string',
+                    enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+                    description: 'LLM provider for api-key mode (default: anthropic)',
+                },
+                contributionThreshold: {
+                    type: 'number',
+                    description: 'Minimum confidence for auto-contributing to collective (0.0-1.0, default: 0.85)',
+                },
+            },
+            required: ['trace', 'domain'],
+        },
+    },
 ];
 // =============================================================================
 // Tool Handlers
@@ -334,6 +444,190 @@ async function handleLeaderboard(client, args) {
     }
     return output;
 }
+async function handleExtractMemories(client, args) {
+    // Determine mode based on config and args
+    // Priority: explicit mode arg > endpoint config > api-key config > xache-managed
+    let mode = args.mode;
+    if (!mode) {
+        if (config.llmEndpoint) {
+            mode = 'endpoint';
+        }
+        else if (config.llmApiKey && config.llmProvider) {
+            mode = 'api-key';
+        }
+        else {
+            mode = 'xache-managed';
+        }
+    }
+    const provider = args.provider || config.llmProvider || 'anthropic';
+    const model = args.model || config.llmModel || undefined;
+    // Build LLM config based on mode (properly typed for discriminated union)
+    let llmConfig;
+    let modeDescription;
+    if (mode === 'api-key') {
+        if (!config.llmApiKey) {
+            throw new Error('api-key mode requires XACHE_LLM_API_KEY environment variable. Set it or use mode="xache-managed".');
+        }
+        if (!SUPPORTED_PROVIDERS.includes(provider)) {
+            throw new Error(`Unsupported provider: ${provider}. Supported: ${SUPPORTED_PROVIDERS.join(', ')}`);
+        }
+        llmConfig = {
+            type: 'api-key',
+            provider,
+            apiKey: config.llmApiKey,
+            model,
+        };
+        modeDescription = `api-key (${provider})`;
+    }
+    else if (mode === 'endpoint') {
+        if (!config.llmEndpoint) {
+            throw new Error('endpoint mode requires XACHE_LLM_ENDPOINT environment variable.');
+        }
+        llmConfig = {
+            type: 'endpoint',
+            url: config.llmEndpoint,
+            authToken: config.llmAuthToken || undefined,
+            format: config.llmFormat,
+            model,
+        };
+        modeDescription = `endpoint (${config.llmEndpoint.substring(0, 40)}...)`;
+    }
+    else {
+        llmConfig = {
+            type: 'xache-managed',
+            provider: provider === 'anthropic' || provider === 'openai' ? provider : 'anthropic',
+            model,
+        };
+        modeDescription = `xache-managed (${provider})`;
+    }
+    const result = await client.extraction.extract({
+        trace: args.trace,
+        llmConfig,
+        options: {
+            contextHint: args.contextHint,
+            confidenceThreshold: args.confidenceThreshold ?? 0.7,
+            autoStore: args.autoStore ?? true,
+        },
+    });
+    const extractions = result.extractions || [];
+    if (extractions.length === 0) {
+        return 'No memories extracted from trace.';
+    }
+    let output = `Extracted ${extractions.length} memories:\n`;
+    output += `Mode: ${modeDescription}\n`;
+    for (let i = 0; i < extractions.length; i++) {
+        const mem = extractions[i];
+        const dataStr = JSON.stringify(mem.data).substring(0, 150);
+        output += `\n${i + 1}. [${mem.type}] ${dataStr}`;
+        output += `\n   Confidence: ${((mem.confidence || 0) * 100).toFixed(0)}%`;
+        if (mem.reasoning)
+            output += ` | ${mem.reasoning.substring(0, 50)}`;
+    }
+    if (result.stored && result.stored.length > 0) {
+        output += `\n\nAuto-stored ${result.stored.length} memories.`;
+    }
+    return output;
+}
+async function handleExtractAndContribute(client, args) {
+    // Determine mode based on config and args
+    let mode = args.mode;
+    if (!mode) {
+        if (config.llmEndpoint) {
+            mode = 'endpoint';
+        }
+        else if (config.llmApiKey && config.llmProvider) {
+            mode = 'api-key';
+        }
+        else {
+            mode = 'xache-managed';
+        }
+    }
+    const provider = args.provider || config.llmProvider || 'anthropic';
+    const model = config.llmModel || undefined;
+    // Build LLM config based on mode
+    let llmConfig;
+    if (mode === 'api-key') {
+        if (!config.llmApiKey) {
+            throw new Error('api-key mode requires XACHE_LLM_API_KEY environment variable.');
+        }
+        llmConfig = {
+            type: 'api-key',
+            provider,
+            apiKey: config.llmApiKey,
+            model,
+        };
+    }
+    else if (mode === 'endpoint') {
+        if (!config.llmEndpoint) {
+            throw new Error('endpoint mode requires XACHE_LLM_ENDPOINT environment variable.');
+        }
+        llmConfig = {
+            type: 'endpoint',
+            url: config.llmEndpoint,
+            authToken: config.llmAuthToken || undefined,
+            format: config.llmFormat,
+            model,
+        };
+    }
+    else {
+        llmConfig = {
+            type: 'xache-managed',
+            provider: provider === 'anthropic' || provider === 'openai' ? provider : 'anthropic',
+            model,
+        };
+    }
+    const threshold = args.contributionThreshold ?? 0.85;
+    const result = await client.extraction.extract({
+        trace: args.trace,
+        llmConfig,
+        options: {
+            confidenceThreshold: 0.7,
+            autoStore: true,
+        },
+    });
+    const extractions = result.extractions || [];
+    let output = `Extracted ${extractions.length} memories.\n`;
+    // Find high-quality heuristics to contribute
+    const heuristicTypes = ['DOMAIN_HEURISTIC', 'SUCCESSFUL_PATTERN', 'ERROR_FIX'];
+    const contributions = [];
+    for (const mem of extractions) {
+        if (heuristicTypes.includes(mem.type) &&
+            (mem.confidence || 0) >= threshold) {
+            try {
+                // Use reasoning as the pattern content
+                const patternContent = mem.reasoning || JSON.stringify(mem.data);
+                const patternHash = hashPattern(patternContent);
+                const contribResult = await client.collective.contribute({
+                    pattern: patternContent,
+                    patternHash,
+                    domain: args.domain,
+                    tags: [mem.type.toLowerCase().replace('_', '-'), args.domain],
+                    metrics: {
+                        successRate: mem.confidence || 0.85,
+                        sampleSize: 1,
+                        confidence: mem.confidence || 0.85,
+                    },
+                    encryptedContentRef: patternHash,
+                });
+                contributions.push(`${patternContent.substring(0, 50)}... → ${contribResult.heuristicId}`);
+            }
+            catch (e) {
+                // Skip contribution errors, continue with others
+            }
+        }
+    }
+    if (contributions.length > 0) {
+        output += `\nContributed ${contributions.length} heuristics to collective:\n`;
+        for (const c of contributions) {
+            output += `  • ${c}\n`;
+        }
+        output += `\nThese contributions earn reputation!`;
+    }
+    else {
+        output += `\nNo heuristics met the contribution threshold (${(threshold * 100).toFixed(0)}%).`;
+    }
+    return output;
+}
 // =============================================================================
 // Server Setup
 // =============================================================================
@@ -341,7 +635,7 @@ async function main() {
     validateConfig();
     const server = new Server({
         name: 'xache-mcp-server',
-        version: '0.1.0',
+        version: '0.2.0',
     }, {
         capabilities: {
             tools: {},
@@ -387,6 +681,12 @@ async function main() {
                 case 'xache_leaderboard':
                     result = await handleLeaderboard(client, args);
                     break;
+                case 'xache_extract_memories':
+                    result = await handleExtractMemories(client, args);
+                    break;
+                case 'xache_extract_and_contribute':
+                    result = await handleExtractAndContribute(client, args);
+                    break;
                 default:
                     throw new Error(`Unknown tool: ${name}`);
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xache/mcp-server",
-  "version": "0.1.0",
-  "description": "MCP server for Xache Protocol - collective intelligence, verifiable memory, and reputation for AI agents",
+  "version": "0.3.1",
+  "description": "MCP server for Xache Protocol - collective intelligence, verifiable memory, extraction, and reputation for AI agents",
   "main": "dist/index.js",
   "bin": {
     "xache-mcp": "./dist/index.js"
@@ -19,6 +19,7 @@
     "agents",
     "collective-intelligence",
     "memory",
+    "extraction",
     "blockchain",
     "receipts",
     "reputation"
@@ -32,7 +33,7 @@
   "homepage": "https://xache.xyz",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@xache/sdk": "^5.1.0",
+    "@xache/sdk": "workspace:*",
     "zod": "^3.22.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -16,6 +16,28 @@
  *   XACHE_PRIVATE_KEY - Private key for signing (stays local, never transmitted)
  *   XACHE_API_URL - API URL (default: https://api.xache.xyz)
  *   XACHE_CHAIN - Chain type: 'base' or 'solana' (default: base)
+ *
+ * Optional extraction environment variables:
+ *   For api-key mode (major providers - we know their endpoints):
+ *     XACHE_LLM_PROVIDER - Provider name:
+ *       'anthropic'  - api.anthropic.com (Claude models)
+ *       'openai'     - api.openai.com (GPT models)
+ *       'google'     - generativelanguage.googleapis.com (Gemini models)
+ *       'mistral'    - api.mistral.ai (Mistral models)
+ *       'groq'       - api.groq.com (Fast inference)
+ *       'together'   - api.together.xyz (Open models)
+ *       'fireworks'  - api.fireworks.ai (Fast open models)
+ *       'cohere'     - api.cohere.com (Command models)
+ *       'xai'        - api.x.ai (Grok models)
+ *       'deepseek'   - api.deepseek.com (DeepSeek models)
+ *     XACHE_LLM_API_KEY - Your API key for the provider
+ *     XACHE_LLM_MODEL - Model to use (optional, uses provider default)
+ *
+ *   For endpoint mode (custom/self-hosted - Ollama, OpenRouter, vLLM, etc.):
+ *     XACHE_LLM_ENDPOINT - Full URL (e.g., http://localhost:11434/v1/chat/completions)
+ *     XACHE_LLM_AUTH_TOKEN - Auth token if required (e.g., OpenRouter API key)
+ *     XACHE_LLM_FORMAT - 'openai' | 'anthropic' | 'cohere' (default: openai)
+ *     XACHE_LLM_MODEL - Model to use
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -25,18 +47,35 @@ import {
   ListToolsRequestSchema,
   Tool,
 } from '@modelcontextprotocol/sdk/types.js';
-import { XacheClient, type DID } from '@xache/sdk';
+import { XacheClient, type DID, type LLMProvider, type LLMApiFormat } from '@xache/sdk';
 import crypto from 'crypto';
 
 // =============================================================================
 // Configuration
 // =============================================================================
 
+/**
+ * Supported providers for api-key mode
+ */
+const SUPPORTED_PROVIDERS: LLMProvider[] = [
+  'anthropic', 'openai', 'google', 'mistral', 'groq',
+  'together', 'fireworks', 'cohere', 'xai', 'deepseek',
+];
+
 const config = {
   walletAddress: process.env.XACHE_WALLET_ADDRESS || '',
   privateKey: process.env.XACHE_PRIVATE_KEY || '',
   apiUrl: process.env.XACHE_API_URL || 'https://api.xache.xyz',
   chain: process.env.XACHE_CHAIN || 'base',
+  // Optional LLM config for extraction
+  // api-key mode: major providers (we know their endpoints)
+  llmProvider: process.env.XACHE_LLM_PROVIDER as LLMProvider | undefined,
+  llmApiKey: process.env.XACHE_LLM_API_KEY || '',
+  llmModel: process.env.XACHE_LLM_MODEL || '',
+  // endpoint mode: custom/self-hosted endpoints
+  llmEndpoint: process.env.XACHE_LLM_ENDPOINT || '',
+  llmAuthToken: process.env.XACHE_LLM_AUTH_TOKEN || '',
+  llmFormat: (process.env.XACHE_LLM_FORMAT || 'openai') as LLMApiFormat,
 };
 
 function getDID(): DID {
@@ -223,6 +262,82 @@ const TOOLS: Tool[] = [
       required: [],
     },
   },
+  {
+    name: 'xache_extract_memories',
+    description:
+      'Extract structured memories from agent traces using LLM. Automatically stores extracted memories. Pricing: $0.002 with your own API key or endpoint, $0.011 with Xache-managed LLM.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        trace: {
+          type: 'string',
+          description:
+            'The agent trace/conversation to extract memories from. Can be a string or JSON object.',
+        },
+        mode: {
+          type: 'string',
+          enum: ['api-key', 'endpoint', 'xache-managed'],
+          description:
+            'LLM mode: "api-key" uses major provider (set XACHE_LLM_PROVIDER + XACHE_LLM_API_KEY, $0.002), "endpoint" uses custom URL (set XACHE_LLM_ENDPOINT, $0.002), "xache-managed" uses Xache LLM ($0.011). Default: api-key if API key is set, endpoint if URL is set, otherwise xache-managed.',
+        },
+        provider: {
+          type: 'string',
+          enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+          description: 'LLM provider for api-key mode. Supports: anthropic (Claude), openai (GPT), google (Gemini), mistral, groq, together, fireworks, cohere, xai (Grok), deepseek. Default: anthropic',
+        },
+        model: {
+          type: 'string',
+          description: 'Specific model to use (optional, uses provider default)',
+        },
+        contextHint: {
+          type: 'string',
+          description: 'Optional context hint to guide extraction (e.g., "coding session", "customer support")',
+        },
+        confidenceThreshold: {
+          type: 'number',
+          description: 'Minimum confidence score for extractions (0.0-1.0, default: 0.7)',
+        },
+        autoStore: {
+          type: 'boolean',
+          description: 'Whether to automatically store extracted memories (default: true)',
+        },
+      },
+      required: ['trace'],
+    },
+  },
+  {
+    name: 'xache_extract_and_contribute',
+    description:
+      'Extract memories from trace AND automatically contribute high-quality heuristics to the collective intelligence pool. Combines extraction + contribution in one call. Earns reputation for valuable insights.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        trace: {
+          type: 'string',
+          description: 'The agent trace/conversation to extract from',
+        },
+        domain: {
+          type: 'string',
+          description: 'Domain for contributed heuristics (e.g., "coding", "research", "api-integration")',
+        },
+        mode: {
+          type: 'string',
+          enum: ['api-key', 'endpoint', 'xache-managed'],
+          description: 'LLM mode for extraction',
+        },
+        provider: {
+          type: 'string',
+          enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+          description: 'LLM provider for api-key mode (default: anthropic)',
+        },
+        contributionThreshold: {
+          type: 'number',
+          description: 'Minimum confidence for auto-contributing to collective (0.0-1.0, default: 0.85)',
+        },
+      },
+      required: ['trace', 'domain'],
+    },
+  },
 ];
 
 // =============================================================================
@@ -407,6 +522,224 @@ async function handleLeaderboard(
   return output;
 }
 
+async function handleExtractMemories(
+  client: XacheClient,
+  args: {
+    trace: string;
+    mode?: 'api-key' | 'endpoint' | 'xache-managed';
+    provider?: LLMProvider;
+    model?: string;
+    contextHint?: string;
+    confidenceThreshold?: number;
+    autoStore?: boolean;
+  }
+): Promise<string> {
+  // Determine mode based on config and args
+  // Priority: explicit mode arg > endpoint config > api-key config > xache-managed
+  let mode = args.mode;
+  if (!mode) {
+    if (config.llmEndpoint) {
+      mode = 'endpoint';
+    } else if (config.llmApiKey && config.llmProvider) {
+      mode = 'api-key';
+    } else {
+      mode = 'xache-managed';
+    }
+  }
+
+  const provider = args.provider || config.llmProvider || 'anthropic';
+  const model = args.model || config.llmModel || undefined;
+
+  // Build LLM config based on mode (properly typed for discriminated union)
+  let llmConfig;
+  let modeDescription: string;
+
+  if (mode === 'api-key') {
+    if (!config.llmApiKey) {
+      throw new Error('api-key mode requires XACHE_LLM_API_KEY environment variable. Set it or use mode="xache-managed".');
+    }
+    if (!SUPPORTED_PROVIDERS.includes(provider)) {
+      throw new Error(`Unsupported provider: ${provider}. Supported: ${SUPPORTED_PROVIDERS.join(', ')}`);
+    }
+    llmConfig = {
+      type: 'api-key' as const,
+      provider,
+      apiKey: config.llmApiKey,
+      model,
+    };
+    modeDescription = `api-key (${provider})`;
+  } else if (mode === 'endpoint') {
+    if (!config.llmEndpoint) {
+      throw new Error('endpoint mode requires XACHE_LLM_ENDPOINT environment variable.');
+    }
+    llmConfig = {
+      type: 'endpoint' as const,
+      url: config.llmEndpoint,
+      authToken: config.llmAuthToken || undefined,
+      format: config.llmFormat,
+      model,
+    };
+    modeDescription = `endpoint (${config.llmEndpoint.substring(0, 40)}...)`;
+  } else {
+    llmConfig = {
+      type: 'xache-managed' as const,
+      provider: provider === 'anthropic' || provider === 'openai' ? provider : 'anthropic',
+      model,
+    };
+    modeDescription = `xache-managed (${provider})`;
+  }
+
+  const result = await client.extraction.extract({
+    trace: args.trace,
+    llmConfig,
+    options: {
+      contextHint: args.contextHint,
+      confidenceThreshold: args.confidenceThreshold ?? 0.7,
+      autoStore: args.autoStore ?? true,
+    },
+  });
+
+  const extractions = result.extractions || [];
+  if (extractions.length === 0) {
+    return 'No memories extracted from trace.';
+  }
+
+  let output = `Extracted ${extractions.length} memories:\n`;
+  output += `Mode: ${modeDescription}\n`;
+
+  for (let i = 0; i < extractions.length; i++) {
+    const mem = extractions[i];
+    const dataStr = JSON.stringify(mem.data).substring(0, 150);
+    output += `\n${i + 1}. [${mem.type}] ${dataStr}`;
+    output += `\n   Confidence: ${((mem.confidence || 0) * 100).toFixed(0)}%`;
+    if (mem.reasoning) output += ` | ${mem.reasoning.substring(0, 50)}`;
+  }
+
+  if (result.stored && result.stored.length > 0) {
+    output += `\n\nAuto-stored ${result.stored.length} memories.`;
+  }
+
+  return output;
+}
+
+async function handleExtractAndContribute(
+  client: XacheClient,
+  args: {
+    trace: string;
+    domain: string;
+    mode?: 'api-key' | 'endpoint' | 'xache-managed';
+    provider?: LLMProvider;
+    contributionThreshold?: number;
+  }
+): Promise<string> {
+  // Determine mode based on config and args
+  let mode = args.mode;
+  if (!mode) {
+    if (config.llmEndpoint) {
+      mode = 'endpoint';
+    } else if (config.llmApiKey && config.llmProvider) {
+      mode = 'api-key';
+    } else {
+      mode = 'xache-managed';
+    }
+  }
+
+  const provider = args.provider || config.llmProvider || 'anthropic';
+  const model = config.llmModel || undefined;
+
+  // Build LLM config based on mode
+  let llmConfig;
+
+  if (mode === 'api-key') {
+    if (!config.llmApiKey) {
+      throw new Error('api-key mode requires XACHE_LLM_API_KEY environment variable.');
+    }
+    llmConfig = {
+      type: 'api-key' as const,
+      provider,
+      apiKey: config.llmApiKey,
+      model,
+    };
+  } else if (mode === 'endpoint') {
+    if (!config.llmEndpoint) {
+      throw new Error('endpoint mode requires XACHE_LLM_ENDPOINT environment variable.');
+    }
+    llmConfig = {
+      type: 'endpoint' as const,
+      url: config.llmEndpoint,
+      authToken: config.llmAuthToken || undefined,
+      format: config.llmFormat,
+      model,
+    };
+  } else {
+    llmConfig = {
+      type: 'xache-managed' as const,
+      provider: provider === 'anthropic' || provider === 'openai' ? provider : 'anthropic',
+      model,
+    };
+  }
+
+  const threshold = args.contributionThreshold ?? 0.85;
+
+  const result = await client.extraction.extract({
+    trace: args.trace,
+    llmConfig,
+    options: {
+      confidenceThreshold: 0.7,
+      autoStore: true,
+    },
+  });
+
+  const extractions = result.extractions || [];
+  let output = `Extracted ${extractions.length} memories.\n`;
+
+  // Find high-quality heuristics to contribute
+  const heuristicTypes = ['DOMAIN_HEURISTIC', 'SUCCESSFUL_PATTERN', 'ERROR_FIX'];
+  const contributions: string[] = [];
+
+  for (const mem of extractions) {
+    if (
+      heuristicTypes.includes(mem.type) &&
+      (mem.confidence || 0) >= threshold
+    ) {
+      try {
+        // Use reasoning as the pattern content
+        const patternContent = mem.reasoning || JSON.stringify(mem.data);
+        const patternHash = hashPattern(patternContent);
+        const contribResult = await client.collective.contribute({
+          pattern: patternContent,
+          patternHash,
+          domain: args.domain,
+          tags: [mem.type.toLowerCase().replace('_', '-'), args.domain],
+          metrics: {
+            successRate: mem.confidence || 0.85,
+            sampleSize: 1,
+            confidence: mem.confidence || 0.85,
+          },
+          encryptedContentRef: patternHash,
+        });
+        contributions.push(
+          `${patternContent.substring(0, 50)}... → ${contribResult.heuristicId}`
+        );
+      } catch (e) {
+        // Skip contribution errors, continue with others
+      }
+    }
+  }
+
+  if (contributions.length > 0) {
+    output += `\nContributed ${contributions.length} heuristics to collective:\n`;
+    for (const c of contributions) {
+      output += `  • ${c}\n`;
+    }
+    output += `\nThese contributions earn reputation!`;
+  } else {
+    output += `\nNo heuristics met the contribution threshold (${(threshold * 100).toFixed(0)}%).`;
+  }
+
+  return output;
+}
+
 // =============================================================================
 // Server Setup
 // =============================================================================
@@ -417,7 +750,7 @@ async function main(): Promise<void> {
   const server = new Server(
     {
       name: 'xache-mcp-server',
-      version: '0.1.0',
+      version: '0.2.0',
     },
     {
       capabilities: {
@@ -470,6 +803,12 @@ async function main(): Promise<void> {
         case 'xache_leaderboard':
           result = await handleLeaderboard(client, args as any);
           break;
+        case 'xache_extract_memories':
+          result = await handleExtractMemories(client, args as any);
+          break;
+        case 'xache_extract_and_contribute':
+          result = await handleExtractAndContribute(client, args as any);
+          break;
         default:
           throw new Error(`Unknown tool: ${name}`);
       }