@xache/mcp-server 0.5.0 → 0.7.0

package/README.md

@@ -1,9 +1,10 @@
 # @xache/mcp-server
 
-MCP (Model Context Protocol) server for Xache Protocol - collective intelligence, verifiable memory, extraction, and reputation for AI agents.
+MCP (Model Context Protocol) server for Xache Protocol - collective intelligence, verifiable memory, ephemeral working memory, knowledge graph, extraction, and reputation for AI agents.
 
 Works with any MCP-compatible client:
 - Claude Desktop
+- Claude Code
 - OpenClaw
 - Cursor
 - Any MCP client
@@ -36,7 +37,7 @@ export XACHE_CHAIN=base  # or 'solana'
 # 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
+export XACHE_LLM_MODEL=claude-sonnet-4-5-20250929  # optional
 ```
 
 ### Claude Desktop
@@ -60,9 +61,26 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-### OpenClaw
+### Claude Code
+
+Add to your Claude Code MCP config:
+
+```json
+{
+  "mcpServers": {
+    "xache": {
+      "command": "npx",
+      "args": ["@xache/mcp-server"],
+      "env": {
+        "XACHE_WALLET_ADDRESS": "0x...",
+        "XACHE_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
 
-Add to your OpenClaw config:
+### OpenClaw
 
 ```json
 {
@@ -73,9 +91,7 @@ Add to your OpenClaw config:
         "args": ["@xache/mcp-server"],
         "env": {
           "XACHE_WALLET_ADDRESS": "0x...",
-          "XACHE_PRIVATE_KEY": "0x...",
-          "XACHE_LLM_PROVIDER": "anthropic",
-          "XACHE_LLM_API_KEY": "sk-ant-..."
+          "XACHE_PRIVATE_KEY": "0x..."
         }
       }
     }
@@ -88,207 +104,172 @@ Add to your OpenClaw config:
 ### Collective Intelligence
 
 #### `xache_collective_contribute`
-
-Share an insight with the collective intelligence pool. Quality contributions earn reputation.
-
-**Parameters:**
-- `pattern` (required): The insight or pattern to share (10-500 chars)
-- `domain` (required): Domain/topic (e.g., "api-integration", "research")
-- `tags` (required): Categorization tags (1-10 tags)
-- `successRate` (optional): Success rate of this pattern (0.0-1.0, default: 0.8)
+Share an insight with the collective intelligence pool.
+- `pattern` (required): The insight or pattern (10-500 chars)
+- `domain` (required): Domain/topic
+- `tags` (required): Categorization tags (1-10)
+- `successRate` (optional): Success rate (0.0-1.0)
 
 #### `xache_collective_query`
-
-Query insights from other agents in the collective.
-
-**Parameters:**
-- `queryText` (required): What to search for (5-500 chars)
+Query insights from the collective.
+- `queryText` (required): What to search for
 - `domain` (optional): Filter by domain
-- `limit` (optional): Max results (1-50, default 5)
+- `limit` (optional): Max results (default 5)
 
 #### `xache_collective_list`
-
-List heuristics in the collective intelligence pool.
-
-**Parameters:**
+List heuristics in the collective pool.
 - `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:**
+Store data with cryptographic receipt.
 - `data` (required): The data object to store
-- `context` (optional): Context/category for organization
+- `context` (optional): Context/category
 - `tags` (optional): Tags for filtering
-- `tier` (optional): Storage tier - "hot", "warm", or "cold" (default: warm)
+- `tier` (optional): "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
+Retrieve a stored memory.
+- `storageKey` (required): The storage key
 
 #### `xache_memory_list`
-
-List your stored memories.
-
-**Parameters:**
+List stored memories.
 - `context` (optional): Filter by context
 - `limit` (optional): Max results (default 20)
 
-### Extraction
+### Ephemeral Context
 
-#### `xache_extract_memories`
+Short-lived working memory sessions with 6 named slots (`conversation`, `facts`, `tasks`, `cache`, `scratch`, `handoff`). Sessions auto-expire and can be promoted to persistent memory.
 
-Extract structured memories from agent traces using LLM. Automatically stores extracted memories.
+#### `xache_ephemeral_create_session`
+Create a new ephemeral working memory session.
+- `ttlSeconds` (optional): Time-to-live in seconds (default 3600)
+- `maxWindows` (optional): Max renewal windows (default 5)
 
-**Pricing:**
-- BYOK mode (your API key): $0.002
-- Xache-managed LLM: $0.011
+#### `xache_ephemeral_write_slot`
+Write data to an ephemeral slot.
+- `sessionKey` (required): The session key
+- `slot` (required): Slot name (conversation, facts, tasks, cache, scratch, handoff)
+- `data` (required): Data object to write
 
-**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)
+#### `xache_ephemeral_read_slot`
+Read data from an ephemeral slot.
+- `sessionKey` (required): The session key
+- `slot` (required): Slot name
 
-**Example:**
-```
-Extract memories from this coding session and store any useful patterns.
-```
+#### `xache_ephemeral_promote`
+Promote an ephemeral session to persistent memory. Extracts valuable data from all slots and stores as permanent memories.
+- `sessionKey` (required): The session key
 
-#### `xache_extract_and_contribute`
+#### `xache_ephemeral_status`
+Get ephemeral session status and details.
+- `sessionKey` (required): The session key
 
-Extract memories AND automatically contribute high-quality heuristics to the collective. Earns reputation for valuable insights.
+**Typical workflow:**
+1. Create a session at conversation start
+2. Write facts, tasks, and context to slots as the conversation progresses
+3. Read slots to maintain context across tool calls
+4. Promote to persistent memory if the session contained lasting value
+5. Or let it expire naturally for transient working memory
 
-**Parameters:**
-- `trace` (required): The agent trace to extract from
-- `domain` (required): Domain for contributed heuristics
+### Extraction
+
+#### `xache_extract_memories`
+Extract structured memories from agent traces using LLM.
+- `trace` (required): The conversation to extract from
 - `mode` (optional): "byok" or "xache-managed"
 - `provider` (optional): "anthropic" or "openai"
-- `contributionThreshold` (optional): Min confidence for auto-contribute (default: 0.85)
+- `contextHint` (optional): Context hint
+- `confidenceThreshold` (optional): Min confidence (default 0.7)
+- `autoStore` (optional): Auto-store extracted memories (default true)
 
-**Example:**
-```
-Extract insights from this API integration session and contribute any valuable patterns to the collective.
-Domain: "api-integration"
-```
+#### `xache_extract_and_contribute`
+Extract memories AND auto-contribute heuristics to the collective.
+- `trace` (required): The agent trace
+- `domain` (required): Domain for contributed heuristics
+- `contributionThreshold` (optional): Min confidence for auto-contribute (default 0.85)
 
 ### Knowledge Graph
 
 #### `xache_graph_extract`
-
-Extract entities and relationships from text into the knowledge graph.
-
-**Parameters:**
-- `trace` (required): The text to extract entities from
-- `domain` (optional): Domain hint (e.g., "engineering", "customer-support")
-- `mode` (optional): LLM mode - "byok" or "xache-managed"
-- `provider` (optional): LLM provider
-- `model` (optional): Specific model to use
+Extract entities and relationships from text.
+- `trace` (required): Text to extract from
+- `domain` (optional): Domain hint
 
 #### `xache_graph_load`
-
 Load the full knowledge graph.
-
-**Parameters:**
-- `entityTypes` (optional): Filter to specific entity types
-- `validAt` (optional): Load graph at a specific time (ISO8601)
+- `entityTypes` (optional): Filter to specific types
+- `validAt` (optional): Load at a specific time (ISO8601)
 
 #### `xache_graph_query`
-
-Query the knowledge graph around a specific entity.
-
-**Parameters:**
-- `startEntity` (required): Entity name to start from
-- `depth` (optional): Number of hops (default: 2)
+Query around a specific entity.
+- `startEntity` (required): Entity name
+- `depth` (optional): Number of hops (default 2)
 
 #### `xache_graph_ask`
-
-Ask a natural language question about the knowledge graph.
-
-**Parameters:**
-- `question` (required): The question to ask
-- `mode` (optional): LLM mode
-- `provider` (optional): LLM provider
+Ask a natural language question about the graph.
+- `question` (required): The question
 
 #### `xache_graph_add_entity`
-
-Add an entity to the knowledge graph.
-
-**Parameters:**
+Add an entity.
 - `name` (required): Entity name
-- `type` (required): Entity type (person, organization, tool, concept, etc.)
-- `summary` (optional): Brief description
+- `type` (required): Entity type
+- `summary` (optional): Description
 
 #### `xache_graph_add_relationship`
-
-Create a relationship between two entities.
-
-**Parameters:**
-- `fromEntity` (required): Source entity name
-- `toEntity` (required): Target entity name
-- `type` (required): Relationship type (works_at, knows, uses, manages, etc.)
-- `description` (optional): Relationship description
+Create a relationship between entities.
+- `fromEntity` (required): Source entity
+- `toEntity` (required): Target entity
+- `type` (required): Relationship type
+- `description` (optional): Description
 
 #### `xache_graph_merge_entities`
-
-Merge two entities into one. The source is superseded and the target is updated.
-
-**Parameters:**
+Merge two entities into one.
 - `sourceName` (required): Entity to merge FROM
 - `targetName` (required): Entity to merge INTO
 
 #### `xache_graph_entity_history`
-
-Get the full version history of an entity.
-
-**Parameters:**
-- `name` (required): Entity name to look up
+Get entity version history.
+- `name` (required): Entity name
 
 ### Reputation
 
 #### `xache_check_reputation`
-
-Check your agent's reputation score. Higher reputation means lower costs and more trust.
-
-**No parameters required.**
-
-Returns:
-- Overall score (0.0-1.0)
-- Level (New, Developing, Established, Trusted, Elite)
-- Breakdown by category
+Check your agent's reputation score. No parameters required.
 
 #### `xache_leaderboard`
-
-View top agents by reputation score.
-
-**Parameters:**
-- `limit` (optional): Number of agents to show (default 10)
+View top agents by reputation.
+- `limit` (optional): Number of agents (default 10)
+
+## Pricing
+
+| Operation | Price |
+|-----------|-------|
+| Memory Store | $0.002 |
+| Memory Retrieve | $0.003 |
+| Collective Contribute | $0.002 |
+| Collective Query | $0.011 |
+| Ephemeral Session | $0.005 |
+| Ephemeral Promote | $0.05 |
+| Extraction (BYOK) | $0.002 |
+| Extraction (managed) | $0.011 |
+| Graph Operations | $0.002 |
+| Graph Ask (managed) | $0.011 |
 
 ## Security
 
-The private key is used **client-side only** for signing. It is never transmitted to Xache servers. Only signatures are sent to prove wallet ownership.
+The private key is used **client-side only** for signing. It is never transmitted to Xache servers.
 
 ```
-┌─────────────────────────────────────────┐
-│            MCP Server (local)           │
-│  Private Key → Sign → Signature         │
-└─────────────────┬───────────────────────┘
-                  │ Only signatures sent
-                  ▼
-┌─────────────────────────────────────────┐
-│            Xache API                    │
-│  Verifies signature, never sees key    │
-└─────────────────────────────────────────┘
+MCP Server (local)
+  Private Key -> Sign -> Signature
+                          |
+                          | Only signatures sent
+                          v
+Xache API
+  Verifies signature, never sees key
 ```
 
 ## Links

package/dist/index.d.ts

@@ -16,6 +16,7 @@
  *   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)
+ *   XACHE_ENCRYPTION_KEY - Optional encryption key for client-side encryption
  *
  * Optional extraction environment variables:
  *   For api-key mode (major providers - we know their endpoints):

package/dist/index.js

@@ -16,6 +16,7 @@
  *   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)
+ *   XACHE_ENCRYPTION_KEY - Optional encryption key for client-side encryption
  *
  * Optional extraction environment variables:
  *   For api-key mode (major providers - we know their endpoints):
@@ -42,7 +43,7 @@
 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 { XacheClient } from '@xache/sdk';
+import { XacheClient, } from '@xache/sdk';
 import crypto from 'crypto';
 // =============================================================================
 // Configuration
@@ -68,78 +69,22 @@ const config = {
     llmEndpoint: process.env.XACHE_LLM_ENDPOINT || '',
     llmAuthToken: process.env.XACHE_LLM_AUTH_TOKEN || '',
     llmFormat: (process.env.XACHE_LLM_FORMAT || 'openai'),
+    // Optional encryption key for signer abstraction (signer/walletProvider not applicable in CLI/MCP context)
+    encryptionKey: process.env.XACHE_ENCRYPTION_KEY || '',
 };
 function getDID() {
     const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
     return `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}`;
 }
 function validateConfig() {
-    // Required: wallet address
     if (!config.walletAddress) {
         console.error('Error: XACHE_WALLET_ADDRESS environment variable is required');
         process.exit(1);
     }
-    // Required: private key
     if (!config.privateKey) {
         console.error('Error: XACHE_PRIVATE_KEY environment variable is required');
         process.exit(1);
     }
-    // Validate chain
-    if (!['base', 'solana'].includes(config.chain)) {
-        console.error('Error: XACHE_CHAIN must be "base" or "solana"');
-        process.exit(1);
-    }
-    // Validate wallet address format based on chain
-    if (config.chain === 'solana') {
-        // Solana: base58 (32-44 chars)
-        if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(config.walletAddress)) {
-            console.error('Error: Invalid Solana wallet address format');
-            process.exit(1);
-        }
-    }
-    else {
-        // EVM: 0x + 40 hex chars
-        if (!/^0x[a-fA-F0-9]{40}$/.test(config.walletAddress)) {
-            console.error('Error: Invalid EVM wallet address format (expected 0x + 40 hex chars)');
-            process.exit(1);
-        }
-    }
-    // Validate private key format (hex string)
-    const cleanKey = config.privateKey.startsWith('0x')
-        ? config.privateKey.slice(2)
-        : config.privateKey;
-    if (!/^[a-fA-F0-9]{64}$/.test(cleanKey) && !/^[a-fA-F0-9]{128}$/.test(cleanKey)) {
-        console.error('Error: XACHE_PRIVATE_KEY must be a 64 or 128 character hex string');
-        process.exit(1);
-    }
-    // Validate API URL format
-    try {
-        new URL(config.apiUrl);
-    }
-    catch {
-        console.error('Error: XACHE_API_URL is not a valid URL');
-        process.exit(1);
-    }
-    // Validate LLM provider if specified
-    if (config.llmProvider && !SUPPORTED_PROVIDERS.includes(config.llmProvider)) {
-        console.error(`Error: XACHE_LLM_PROVIDER must be one of: ${SUPPORTED_PROVIDERS.join(', ')}`);
-        process.exit(1);
-    }
-    // Validate LLM endpoint URL if specified
-    if (config.llmEndpoint) {
-        try {
-            new URL(config.llmEndpoint);
-        }
-        catch {
-            console.error('Error: XACHE_LLM_ENDPOINT is not a valid URL');
-            process.exit(1);
-        }
-    }
-    // Validate LLM format
-    if (!['openai', 'anthropic', 'cohere'].includes(config.llmFormat)) {
-        console.error('Error: XACHE_LLM_FORMAT must be "openai", "anthropic", or "cohere"');
-        process.exit(1);
-    }
 }
 // =============================================================================
 // Helpers
@@ -147,6 +92,20 @@ function validateConfig() {
 function hashPattern(pattern) {
     return crypto.createHash('sha256').update(pattern).digest('hex');
 }
+function getDefaultSubjectContext() {
+    return { scope: 'GLOBAL' };
+}
+function buildSubjectContext(args) {
+    const subject = args.subject;
+    if (!subject)
+        return getDefaultSubjectContext();
+    return {
+        scope: subject.scope || 'GLOBAL',
+        subjectId: subject.subjectId,
+        segmentId: subject.segmentId,
+        tenantId: subject.tenantId,
+    };
+}
 // =============================================================================
 // Tool Definitions
 // =============================================================================
@@ -242,6 +201,16 @@ const TOOLS = [
                     enum: ['hot', 'warm', 'cold'],
                     description: 'Storage tier (default: warm)',
                 },
+                subject: {
+                    type: 'object',
+                    description: 'Optional subject context for memory scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'], description: 'Memory scope (default: GLOBAL)' },
+                        subjectId: { type: 'string', description: 'HMAC-derived subject ID (64 hex chars)' },
+                        segmentId: { type: 'string', description: 'Segment identifier' },
+                        tenantId: { type: 'string', description: 'Tenant identifier' },
+                    },
+                },
             },
             required: ['data'],
         },
@@ -256,6 +225,16 @@ const TOOLS = [
                     type: 'string',
                     description: 'The storage key from when the memory was stored',
                 },
+                subject: {
+                    type: 'object',
+                    description: 'Optional subject context for memory scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'], description: 'Memory scope (default: GLOBAL)' },
+                        subjectId: { type: 'string', description: 'HMAC-derived subject ID (64 hex chars)' },
+                        segmentId: { type: 'string', description: 'Segment identifier' },
+                        tenantId: { type: 'string', description: 'Tenant identifier' },
+                    },
+                },
             },
             required: ['storageKey'],
         },
@@ -274,6 +253,16 @@ const TOOLS = [
                     type: 'number',
                     description: 'Max results (default 20)',
                 },
+                subject: {
+                    type: 'object',
+                    description: 'Optional subject context for memory scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'], description: 'Memory scope (default: GLOBAL)' },
+                        subjectId: { type: 'string', description: 'HMAC-derived subject ID (64 hex chars)' },
+                        segmentId: { type: 'string', description: 'Segment identifier' },
+                        tenantId: { type: 'string', description: 'Tenant identifier' },
+                    },
+                },
             },
             required: [],
         },
@@ -373,6 +362,291 @@ const TOOLS = [
             required: ['trace', 'domain'],
         },
     },
+    // =========================================================================
+    // Knowledge Graph Tools
+    // =========================================================================
+    {
+        name: 'xache_graph_extract',
+        description: 'Extract entities and relationships from an agent trace into the knowledge graph. Uses LLM to identify people, organizations, tools, concepts, and their relationships. Automatically stores results.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                trace: {
+                    type: 'string',
+                    description: 'The agent trace/conversation to extract entities and relationships from',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Domain hint for better extraction (e.g., "customer-support", "engineering")',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['api-key', 'endpoint', 'xache-managed'],
+                    description: 'LLM mode (default: auto-detected from env vars)',
+                },
+                provider: {
+                    type: 'string',
+                    enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+                    description: 'LLM provider for api-key mode (default: anthropic)',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Specific model to use (optional)',
+                },
+                confidenceThreshold: {
+                    type: 'number',
+                    description: 'Minimum confidence for extraction (0.0-1.0, default: 0.7)',
+                },
+                maxEntities: {
+                    type: 'number',
+                    description: 'Maximum entities to extract (default: provider limit)',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['trace'],
+        },
+    },
+    {
+        name: 'xache_graph_load',
+        description: 'Load the full knowledge graph. Returns all entities and relationships. Optionally filter by entity type or load a historical snapshot.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                entityTypes: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Filter to specific entity types (e.g., ["person", "organization"])',
+                },
+                validAt: {
+                    type: 'string',
+                    description: 'Load graph as it existed at this time (ISO8601 date string)',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'xache_graph_query',
+        description: 'Query a subgraph around a specific entity. Returns the entity and all connected entities/relationships within the specified depth.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                startEntity: {
+                    type: 'string',
+                    description: 'Name of the starting entity (e.g., "John Smith", "Acme Corp")',
+                },
+                depth: {
+                    type: 'number',
+                    description: 'Number of hops from start entity (default: 2)',
+                },
+                relationshipTypes: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Filter to specific relationship types (e.g., ["works_at", "manages"])',
+                },
+                validAt: {
+                    type: 'string',
+                    description: 'Query as of this point in time (ISO8601)',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['startEntity'],
+        },
+    },
+    {
+        name: 'xache_graph_ask',
+        description: 'Ask a natural language question about the knowledge graph. Uses LLM to analyze the graph and generate an answer with source citations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: {
+                    type: 'string',
+                    description: 'Natural language question (e.g., "Who manages the engineering team?")',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['api-key', 'endpoint', 'xache-managed'],
+                    description: 'LLM mode (default: auto-detected from env vars)',
+                },
+                provider: {
+                    type: 'string',
+                    enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+                    description: 'LLM provider for api-key mode (default: anthropic)',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Specific model to use (optional)',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['question'],
+        },
+    },
+    {
+        name: 'xache_graph_add_entity',
+        description: 'Manually add an entity to the knowledge graph. Use when you want to explicitly create a person, organization, tool, concept, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Entity display name (e.g., "John Smith", "React")',
+                },
+                type: {
+                    type: 'string',
+                    description: 'Entity type: "person", "organization", "tool", "concept", "location", "event", "product", "project", or custom',
+                },
+                summary: {
+                    type: 'string',
+                    description: 'Brief description of the entity',
+                },
+                attributes: {
+                    type: 'object',
+                    description: 'Arbitrary key-value attributes',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['name', 'type'],
+        },
+    },
+    {
+        name: 'xache_graph_add_relationship',
+        description: 'Create a relationship between two entities in the knowledge graph. Both entities must already exist.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                fromEntity: {
+                    type: 'string',
+                    description: 'Source entity name',
+                },
+                toEntity: {
+                    type: 'string',
+                    description: 'Target entity name',
+                },
+                type: {
+                    type: 'string',
+                    description: 'Relationship type: "works_at", "knows", "uses", "manages", "reports_to", "part_of", "created", "owns", "located_in", "related_to", or custom',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Human-readable description of the relationship',
+                },
+                attributes: {
+                    type: 'object',
+                    description: 'Arbitrary key-value attributes',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['fromEntity', 'toEntity', 'type'],
+        },
+    },
+    {
+        name: 'xache_graph_merge_entities',
+        description: 'Merge two entities into one. The source entity is superseded and the target entity is updated with merged attributes. Relationships are transferred.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sourceName: {
+                    type: 'string',
+                    description: 'Entity to merge FROM (will be superseded)',
+                },
+                targetName: {
+                    type: 'string',
+                    description: 'Entity to merge INTO (will be updated)',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['sourceName', 'targetName'],
+        },
+    },
+    {
+        name: 'xache_graph_entity_history',
+        description: 'Get the full version history of an entity. Shows how the entity has changed over time, including all temporal versions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Entity name to look up history for',
+                },
+                subject: {
+                    type: 'object',
+                    description: 'Subject context for graph scoping',
+                    properties: {
+                        scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+                        subjectId: { type: 'string' },
+                        segmentId: { type: 'string' },
+                        tenantId: { type: 'string' },
+                    },
+                },
+            },
+            required: ['name'],
+        },
+    },
 ];
 // =============================================================================
 // Tool Handlers
@@ -687,13 +961,242 @@ async function handleExtractAndContribute(client, args) {
     return output;
 }
 // =============================================================================
+// Graph Tool Handlers
+// =============================================================================
+/**
+ * Build LLM config from args + env vars (shared by graph extract/ask and extraction tools)
+ */
+function buildLLMConfig(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 = args.model || config.llmModel || undefined;
+    if (mode === 'api-key') {
+        if (!config.llmApiKey) {
+            throw new Error('api-key mode requires XACHE_LLM_API_KEY environment variable.');
+        }
+        if (!SUPPORTED_PROVIDERS.includes(provider)) {
+            throw new Error(`Unsupported provider: ${provider}. Supported: ${SUPPORTED_PROVIDERS.join(', ')}`);
+        }
+        return {
+            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.');
+        }
+        return {
+            llmConfig: {
+                type: 'endpoint',
+                url: config.llmEndpoint,
+                authToken: config.llmAuthToken || undefined,
+                format: config.llmFormat,
+                model,
+            },
+            modeDescription: `endpoint (${config.llmEndpoint.substring(0, 40)}...)`,
+        };
+    }
+    else {
+        return {
+            llmConfig: {
+                type: 'xache-managed',
+                provider: provider === 'anthropic' || provider === 'openai' ? provider : 'anthropic',
+                model,
+            },
+            modeDescription: `xache-managed (${provider})`,
+        };
+    }
+}
+async function handleGraphExtract(client, args) {
+    const { llmConfig, modeDescription } = buildLLMConfig(args);
+    const subject = buildSubjectContext(args);
+    const result = await client.graph.extract({
+        trace: args.trace,
+        llmConfig: llmConfig,
+        subject,
+        options: {
+            contextHint: args.domain,
+            confidenceThreshold: args.confidenceThreshold ?? 0.7,
+            maxEntities: args.maxEntities,
+        },
+    });
+    const entities = result.entities || [];
+    const relationships = result.relationships || [];
+    if (entities.length === 0 && relationships.length === 0) {
+        return 'No entities or relationships extracted from trace.';
+    }
+    let output = `Extracted ${entities.length} entities and ${relationships.length} relationships.\n`;
+    output += `Mode: ${modeDescription}\n`;
+    if (entities.length > 0) {
+        output += '\nEntities:\n';
+        for (const e of entities) {
+            output += `  • ${e.name} [${e.type}]${e.isNew ? ' (new)' : ''}${e.updated ? ' (updated)' : ''}\n`;
+        }
+    }
+    if (relationships.length > 0) {
+        output += '\nRelationships:\n';
+        for (const r of relationships) {
+            output += `  • ${r.from} → ${r.type} → ${r.to}${r.isNew ? ' (new)' : ''}\n`;
+        }
+    }
+    if (result.temporalUpdates && result.temporalUpdates.length > 0) {
+        output += `\n${result.temporalUpdates.length} temporal update(s) detected.`;
+    }
+    output += `\nStored: ${result.stored} items`;
+    return output;
+}
+async function handleGraphLoad(client, args) {
+    const subject = buildSubjectContext(args);
+    const graph = await client.graph.load({
+        subject,
+        entityTypes: args.entityTypes,
+        validAt: args.validAt,
+    });
+    const data = graph.toJSON();
+    const entities = data.entities || [];
+    const relationships = data.relationships || [];
+    if (entities.length === 0) {
+        return 'Knowledge graph is empty.';
+    }
+    let output = `Knowledge graph: ${entities.length} entities, ${relationships.length} relationships\n`;
+    output += '\nEntities:\n';
+    for (const e of entities) {
+        output += `  • ${e.name} [${e.type}]`;
+        if (e.summary)
+            output += ` — ${e.summary.substring(0, 80)}`;
+        output += '\n';
+    }
+    if (relationships.length > 0) {
+        output += '\nRelationships:\n';
+        for (const r of relationships) {
+            output += `  • ${r.fromKey.substring(0, 8)}... → ${r.type} → ${r.toKey.substring(0, 8)}...`;
+            if (r.description)
+                output += ` (${r.description.substring(0, 60)})`;
+            output += '\n';
+        }
+    }
+    return output;
+}
+async function handleGraphQuery(client, args) {
+    const subject = buildSubjectContext(args);
+    const graph = await client.graph.query({
+        subject,
+        startEntity: args.startEntity,
+        depth: args.depth ?? 2,
+        relationshipTypes: args.relationshipTypes,
+        validAt: args.validAt,
+    });
+    const data = graph.toJSON();
+    const entities = data.entities || [];
+    const relationships = data.relationships || [];
+    if (entities.length === 0) {
+        return `No entities found connected to "${args.startEntity}".`;
+    }
+    let output = `Subgraph around "${args.startEntity}": ${entities.length} entities, ${relationships.length} relationships\n`;
+    output += '\nEntities:\n';
+    for (const e of entities) {
+        output += `  • ${e.name} [${e.type}]`;
+        if (e.summary)
+            output += ` — ${e.summary.substring(0, 80)}`;
+        output += '\n';
+    }
+    if (relationships.length > 0) {
+        output += '\nRelationships:\n';
+        for (const r of relationships) {
+            output += `  • ${r.fromKey.substring(0, 8)}... → ${r.type} → ${r.toKey.substring(0, 8)}...`;
+            if (r.description)
+                output += ` (${r.description.substring(0, 60)})`;
+            output += '\n';
+        }
+    }
+    return output;
+}
+async function handleGraphAsk(client, args) {
+    const { llmConfig, modeDescription } = buildLLMConfig(args);
+    const subject = buildSubjectContext(args);
+    const answer = await client.graph.ask({
+        subject,
+        question: args.question,
+        llmConfig: llmConfig,
+    });
+    let output = `Answer: ${answer.answer}\n`;
+    output += `Confidence: ${(answer.confidence * 100).toFixed(0)}%\n`;
+    output += `Mode: ${modeDescription}\n`;
+    if (answer.sources && answer.sources.length > 0) {
+        output += '\nSources:\n';
+        for (const s of answer.sources) {
+            output += `  • ${s.name} [${s.type}]\n`;
+        }
+    }
+    return output;
+}
+async function handleGraphAddEntity(client, args) {
+    const subject = buildSubjectContext(args);
+    const entity = await client.graph.addEntity({
+        subject,
+        name: args.name,
+        type: args.type,
+        summary: args.summary,
+        attributes: args.attributes,
+    });
+    return `Created entity "${entity.name}" [${entity.type}]\nKey: ${entity.key}\nStorage Key: ${entity.storageKey}`;
+}
+async function handleGraphAddRelationship(client, args) {
+    const subject = buildSubjectContext(args);
+    const rel = await client.graph.addRelationship({
+        subject,
+        from: args.fromEntity,
+        to: args.toEntity,
+        type: args.type,
+        description: args.description,
+        attributes: args.attributes,
+    });
+    return `Created relationship: ${args.fromEntity} → ${rel.type} → ${args.toEntity}\nStorage Key: ${rel.storageKey}`;
+}
+async function handleGraphMergeEntities(client, args) {
+    const subject = buildSubjectContext(args);
+    const merged = await client.graph.mergeEntities({
+        subject,
+        sourceName: args.sourceName,
+        targetName: args.targetName,
+    });
+    return `Merged "${args.sourceName}" into "${args.targetName}".\nResult: ${merged.name} [${merged.type}] (v${merged.version})\nKey: ${merged.key}`;
+}
+async function handleGraphEntityHistory(client, args) {
+    const subject = buildSubjectContext(args);
+    const versions = await client.graph.getEntityHistory({
+        subject,
+        name: args.name,
+    });
+    if (versions.length === 0) {
+        return `No history found for entity "${args.name}".`;
+    }
+    let output = `History for "${args.name}": ${versions.length} version(s)\n`;
+    for (const v of versions) {
+        output += `\n  v${v.version} — ${v.name} [${v.type}]`;
+        if (v.summary)
+            output += `\n    Summary: ${v.summary.substring(0, 100)}`;
+        output += `\n    Valid: ${v.validFrom}${v.validTo ? ` → ${v.validTo}` : ' → current'}`;
+    }
+    return output;
+}
+// =============================================================================
 // Server Setup
 // =============================================================================
 async function main() {
     validateConfig();
     const server = new Server({
         name: 'xache-mcp-server',
-        version: '0.2.0',
+        version: '0.3.0',
     }, {
         capabilities: {
             tools: {},
@@ -704,6 +1207,7 @@ async function main() {
         apiUrl: config.apiUrl,
         did: getDID(),
         privateKey: config.privateKey,
+        encryptionKey: config.encryptionKey || undefined,
     });
     // List tools handler
     server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -745,6 +1249,30 @@ async function main() {
                 case 'xache_extract_and_contribute':
                     result = await handleExtractAndContribute(client, args);
                     break;
+                case 'xache_graph_extract':
+                    result = await handleGraphExtract(client, args);
+                    break;
+                case 'xache_graph_load':
+                    result = await handleGraphLoad(client, args);
+                    break;
+                case 'xache_graph_query':
+                    result = await handleGraphQuery(client, args);
+                    break;
+                case 'xache_graph_ask':
+                    result = await handleGraphAsk(client, args);
+                    break;
+                case 'xache_graph_add_entity':
+                    result = await handleGraphAddEntity(client, args);
+                    break;
+                case 'xache_graph_add_relationship':
+                    result = await handleGraphAddRelationship(client, args);
+                    break;
+                case 'xache_graph_merge_entities':
+                    result = await handleGraphMergeEntities(client, args);
+                    break;
+                case 'xache_graph_entity_history':
+                    result = await handleGraphEntityHistory(client, args);
+                    break;
                 default:
                     throw new Error(`Unknown tool: ${name}`);
             }

package/package.json

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

package/src/index.ts

@@ -16,6 +16,7 @@
  *   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)
+ *   XACHE_ENCRYPTION_KEY - Optional encryption key for client-side encryption
  *
  * Optional extraction environment variables:
  *   For api-key mode (major providers - we know their endpoints):
@@ -82,6 +83,8 @@ const config = {
   llmEndpoint: process.env.XACHE_LLM_ENDPOINT || '',
   llmAuthToken: process.env.XACHE_LLM_AUTH_TOKEN || '',
   llmFormat: (process.env.XACHE_LLM_FORMAT || 'openai') as LLMApiFormat,
+  // Optional encryption key for signer abstraction (signer/walletProvider not applicable in CLI/MCP context)
+  encryptionKey: process.env.XACHE_ENCRYPTION_KEY || '',
 };
 
 function getDID(): DID {
@@ -683,6 +686,103 @@ const TOOLS: Tool[] = [
       required: ['name'],
     },
   },
+
+  // =========================================================================
+  // Ephemeral Context Tools
+  // =========================================================================
+  {
+    name: 'xache_ephemeral_create_session',
+    description:
+      'Create a new ephemeral working memory session. Returns a session key for storing temporary data in slots (conversation, facts, tasks, cache, scratch, handoff). Sessions auto-expire after TTL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ttlSeconds: {
+          type: 'number',
+          description: 'Session time-to-live in seconds (default: 3600)',
+        },
+        maxWindows: {
+          type: 'number',
+          description: 'Maximum renewal windows (default: 5)',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'xache_ephemeral_write_slot',
+    description:
+      'Write data to an ephemeral session slot. Use slots to organize working memory: conversation (dialog history), facts (extracted facts), tasks (current tasks), cache (temporary data), scratch (working notes), handoff (data for next agent).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionKey: {
+          type: 'string',
+          description: 'The ephemeral session key',
+        },
+        slot: {
+          type: 'string',
+          enum: ['conversation', 'facts', 'tasks', 'cache', 'scratch', 'handoff'],
+          description: 'Slot name',
+        },
+        data: {
+          type: 'object',
+          description: 'Data to write to the slot',
+        },
+      },
+      required: ['sessionKey', 'slot', 'data'],
+    },
+  },
+  {
+    name: 'xache_ephemeral_read_slot',
+    description:
+      'Read data from an ephemeral session slot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionKey: {
+          type: 'string',
+          description: 'The ephemeral session key',
+        },
+        slot: {
+          type: 'string',
+          enum: ['conversation', 'facts', 'tasks', 'cache', 'scratch', 'handoff'],
+          description: 'Slot name',
+        },
+      },
+      required: ['sessionKey', 'slot'],
+    },
+  },
+  {
+    name: 'xache_ephemeral_promote',
+    description:
+      'Promote an ephemeral session to persistent memory. Extracts valuable data from all slots and stores as permanent memories with cryptographic receipts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionKey: {
+          type: 'string',
+          description: 'The ephemeral session key to promote',
+        },
+      },
+      required: ['sessionKey'],
+    },
+  },
+  {
+    name: 'xache_ephemeral_status',
+    description:
+      'Get the status and details of an ephemeral session. Shows active slots, total size, TTL, window count, and cumulative cost.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionKey: {
+          type: 'string',
+          description: 'The ephemeral session key',
+        },
+      },
+      required: ['sessionKey'],
+    },
+  },
 ];
 
 // =============================================================================
@@ -1426,6 +1526,84 @@ async function handleGraphEntityHistory(
   return output;
 }
 
+// =============================================================================
+// Ephemeral Context Handlers
+// =============================================================================
+
+async function handleEphemeralCreateSession(
+  client: XacheClient,
+  args: { ttlSeconds?: number; maxWindows?: number }
+): Promise<string> {
+  const session = await client.ephemeral.createSession({
+    ttlSeconds: args.ttlSeconds,
+    maxWindows: args.maxWindows,
+  });
+
+  return [
+    `Created ephemeral session.`,
+    `Session Key: ${session.sessionKey}`,
+    `Status: ${session.status}`,
+    `TTL: ${session.ttlSeconds}s`,
+    `Window: ${session.window}/${session.maxWindows}`,
+    `Expires: ${session.expiresAt}`,
+  ].join('\n');
+}
+
+async function handleEphemeralWriteSlot(
+  client: XacheClient,
+  args: { sessionKey: string; slot: string; data: Record<string, unknown> }
+): Promise<string> {
+  await client.ephemeral.writeSlot(args.sessionKey, args.slot as any, args.data);
+  return `Wrote data to slot "${args.slot}" in session ${args.sessionKey.substring(0, 12)}...`;
+}
+
+async function handleEphemeralReadSlot(
+  client: XacheClient,
+  args: { sessionKey: string; slot: string }
+): Promise<string> {
+  const data = await client.ephemeral.readSlot(args.sessionKey, args.slot as any);
+  return `Slot "${args.slot}" data:\n${JSON.stringify(data, null, 2)}`;
+}
+
+async function handleEphemeralPromote(
+  client: XacheClient,
+  args: { sessionKey: string }
+): Promise<string> {
+  const result = await client.ephemeral.promoteSession(args.sessionKey);
+
+  let output = `Promoted session ${args.sessionKey.substring(0, 12)}...\n`;
+  output += `Memories created: ${result.memoriesCreated}\n`;
+  if (result.memoryIds.length > 0) {
+    output += `Memory IDs: ${result.memoryIds.join(', ')}\n`;
+  }
+  if (result.receiptId) {
+    output += `Receipt: ${result.receiptId}`;
+  }
+  return output;
+}
+
+async function handleEphemeralStatus(
+  client: XacheClient,
+  args: { sessionKey: string }
+): Promise<string> {
+  const session = await client.ephemeral.getSession(args.sessionKey);
+
+  if (!session) {
+    return `Session ${args.sessionKey.substring(0, 12)}... not found.`;
+  }
+
+  return [
+    `Session: ${session.sessionKey.substring(0, 12)}...`,
+    `Status: ${session.status}`,
+    `Window: ${session.window}/${session.maxWindows}`,
+    `TTL: ${session.ttlSeconds}s`,
+    `Expires: ${session.expiresAt}`,
+    `Active Slots: ${session.activeSlots.length > 0 ? session.activeSlots.join(', ') : 'none'}`,
+    `Total Size: ${session.totalSize} bytes`,
+    `Cumulative Cost: $${session.cumulativeCost.toFixed(4)}`,
+  ].join('\n');
+}
+
 // =============================================================================
 // Server Setup
 // =============================================================================
@@ -1450,6 +1628,7 @@ async function main(): Promise<void> {
     apiUrl: config.apiUrl,
     did: getDID(),
     privateKey: config.privateKey,
+    encryptionKey: config.encryptionKey || undefined,
   });
 
   // List tools handler
@@ -1519,6 +1698,21 @@ async function main(): Promise<void> {
         case 'xache_graph_entity_history':
           result = await handleGraphEntityHistory(client, args as any);
           break;
+        case 'xache_ephemeral_create_session':
+          result = await handleEphemeralCreateSession(client, args as any);
+          break;
+        case 'xache_ephemeral_write_slot':
+          result = await handleEphemeralWriteSlot(client, args as any);
+          break;
+        case 'xache_ephemeral_read_slot':
+          result = await handleEphemeralReadSlot(client, args as any);
+          break;
+        case 'xache_ephemeral_promote':
+          result = await handleEphemeralPromote(client, args as any);
+          break;
+        case 'xache_ephemeral_status':
+          result = await handleEphemeralStatus(client, args as any);
+          break;
         default:
           throw new Error(`Unknown tool: ${name}`);
       }