@xache/mcp-server 0.6.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xache/mcp-server",
-  "version": "0.6.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.8.0",
+    "@xache/sdk": "workspace:*",
     "zod": "^3.22.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -686,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'],
+    },
+  },
 ];
 
 // =============================================================================
@@ -1429,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
 // =============================================================================
@@ -1523,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}`);
       }