@xache/langchain 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @xache/langchain
 
-LangChain.js integration for [Xache Protocol](https://xache.xyz) - verifiable AI agent memory with cryptographic receipts, collective intelligence, and portable ERC-8004 reputation.
+LangChain.js integration for [Xache Protocol](https://xache.xyz) - verifiable AI agent memory with cryptographic receipts, collective intelligence, ephemeral working memory, knowledge graph, and portable ERC-8004 reputation.
 
 ## Installation
 
@@ -40,8 +40,8 @@ import { XacheMemory } from '@xache/langchain';
 const memory = new XacheMemory({
   walletAddress: '0xYourWallet',
   privateKey: '0xYourPrivateKey',
-  apiUrl: 'https://api.xache.xyz', // optional
-  chain: 'base', // or 'solana'
+  apiUrl: 'https://api.xache.xyz',
+  chain: 'base',
 });
 ```
 
@@ -56,7 +56,7 @@ import { RetrievalQAChain } from 'langchain/chains';
 const retriever = new XacheRetriever({
   walletAddress: '0x...',
   privateKey: '0x...',
-  k: 5, // number of documents
+  k: 5,
 });
 
 const qa = RetrievalQAChain.fromLLM(llm, retriever);
@@ -64,15 +64,12 @@ const qa = RetrievalQAChain.fromLLM(llm, retriever);
 
 ### Collective Intelligence
 
-Query and contribute to shared knowledge:
-
 ```typescript
 import {
   createCollectiveContributeTool,
   createCollectiveQueryTool,
 } from '@xache/langchain';
 
-// Add to your agent's tools
 const contributeTool = createCollectiveContributeTool({
   walletAddress: '0x...',
   privateKey: '0x...',
@@ -82,34 +79,28 @@ const queryTool = createCollectiveQueryTool({
   walletAddress: '0x...',
   privateKey: '0x...',
 });
-
-const tools = [contributeTool, queryTool];
 ```
 
 ### Memory Extraction
 
-Auto-extract memories from conversations:
-
 ```typescript
 import { XacheExtractor } from '@xache/langchain';
 
 const extractor = new XacheExtractor({
   walletAddress: '0x...',
   privateKey: '0x...',
-  mode: 'xache-managed', // or 'api-key' with your LLM key
+  mode: 'xache-managed',
 });
 
 const result = await extractor.extract(
   'User asked about quantum computing...',
   { autoStore: true }
 );
-
-console.log(`Extracted ${result.count} memories`);
 ```
 
 ### Knowledge Graph
 
-Build and query a privacy-preserving knowledge graph of entities and relationships:
+Build and query a privacy-preserving knowledge graph:
 
 ```typescript
 import {
@@ -131,67 +122,81 @@ const config = {
   llmApiKey: 'sk-ant-...',
 };
 
-// Extract entities from text
 const extractTool = createGraphExtractTool(config);
-
-// Query graph around an entity
 const queryTool = createGraphQueryTool(config);
-
-// Ask natural language questions
 const askTool = createGraphAskTool(config);
-
-// Load the full graph
 const loadTool = createGraphLoadTool(config);
 
-// Add entities and relationships manually
-const addEntityTool = createGraphAddEntityTool(config);
-const addRelTool = createGraphAddRelationshipTool(config);
-
-// Merge duplicate entities
-const mergeTool = createGraphMergeEntitiesTool(config);
-
-// View entity version history
-const historyTool = createGraphEntityHistoryTool(config);
-
-// Use as a retriever for RAG
+// Use graph as a retriever for RAG
 const graphRetriever = new XacheGraphRetriever({
   walletAddress: '0x...',
   privateKey: '0x...',
   k: 10,
 });
+```
+
+### Ephemeral Context (Working Memory)
 
-const docs = await graphRetriever.getRelevantDocuments('engineering team');
+Short-lived scratch sessions for multi-turn workflows with 6 named slots (`conversation`, `facts`, `tasks`, `cache`, `scratch`, `handoff`):
+
+```typescript
+import {
+  createEphemeralCreateSessionTool,
+  createEphemeralWriteSlotTool,
+  createEphemeralReadSlotTool,
+  createEphemeralPromoteTool,
+  createEphemeralStatusTool,
+} from '@xache/langchain';
+
+const config = {
+  walletAddress: '0x...',
+  privateKey: '0x...',
+};
+
+// Create tools for your agent
+const createSessionTool = createEphemeralCreateSessionTool(config);
+const writeSlotTool = createEphemeralWriteSlotTool(config);
+const readSlotTool = createEphemeralReadSlotTool(config);
+const promoteTool = createEphemeralPromoteTool(config);
+const statusTool = createEphemeralStatusTool(config);
+
+// Add to agent's toolkit
+const tools = [createSessionTool, writeSlotTool, readSlotTool, promoteTool, statusTool];
 ```
 
-### Reputation
+Or use class-based wrappers:
 
-Check and verify agent reputation:
+```typescript
+import {
+  XacheEphemeralCreateSessionTool,
+  XacheEphemeralWriteSlotTool,
+  XacheEphemeralReadSlotTool,
+  XacheEphemeralPromoteTool,
+  XacheEphemeralStatusTool,
+} from '@xache/langchain';
+
+const createSession = new XacheEphemeralCreateSessionTool(config);
+const tool = createSession.asTool();
+```
+
+### Reputation
 
 ```typescript
 import { createReputationTool, XacheReputationChecker } from '@xache/langchain';
 
-// As a tool for your agent
 const repTool = createReputationTool({
   walletAddress: '0x...',
   privateKey: '0x...',
 });
 
-// Or check other agents
 const checker = new XacheReputationChecker({
   walletAddress: '0x...',
   privateKey: '0x...',
 });
-
-const otherRep = await checker.check('did:agent:evm:0xOtherAgent...');
-if (otherRep.score >= 0.5) {
-  console.log('Agent is trustworthy');
-}
 ```
 
 ## Chat History
 
-For more control over message history:
-
 ```typescript
 import { XacheChatMessageHistory } from '@xache/langchain';
 import { BufferMemory } from 'langchain/memory';
@@ -209,19 +214,17 @@ const memory = new BufferMemory({ chatHistory: history });
 
 All operations use x402 micropayments (auto-handled):
 
-| Operation            | Price  |
-| -------------------- | ------ |
-| Memory Store         | $0.002 |
-| Memory Retrieve      | $0.003 |
-| Collective Contribute| $0.002 |
-| Collective Query     | $0.011 |
+| 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 (managed) | $0.011 |
-| Graph Operations     | $0.002 |
-| Graph Ask (managed)  | $0.011 |
-
-## ERC-8004 Portable Reputation
-
-Xache supports [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) for portable, on-chain reputation. Enable it to make your agent's reputation verifiable across platforms.
+| Graph Operations | $0.002 |
+| Graph Ask (managed) | $0.011 |
 
 ## Resources
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xache/langchain",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "LangChain.js integration for Xache Protocol - verifiable AI agent memory",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -51,7 +51,7 @@
     "langchain": ">=0.3.37"
   },
   "dependencies": {
-    "@xache/sdk": "^5.8.0",
+    "@xache/sdk": "workspace:*",
     "zod": "^3.22.0"
   },
   "devDependencies": {

package/src/ephemeral.ts

@@ -0,0 +1,268 @@
+/**
+ * Xache Ephemeral Context for LangChain.js
+ * Create, manage, and promote short-lived working memory sessions
+ */
+
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import {
+  XacheClient,
+  DID,
+  type XacheSigner,
+  type XacheWalletProvider,
+} from '@xache/sdk';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+export interface EphemeralToolConfig {
+  /** Wallet address for authentication */
+  walletAddress: string;
+  /** Private key for signing (optional if signer or walletProvider is provided) */
+  privateKey?: string;
+  /** External signer (alternative to privateKey) */
+  signer?: XacheSigner;
+  /** Wallet provider for lazy signer resolution */
+  walletProvider?: XacheWalletProvider;
+  /** Encryption key for use with external signers */
+  encryptionKey?: string;
+  /** API URL (defaults to https://api.xache.xyz) */
+  apiUrl?: string;
+  /** Chain: 'base' or 'solana' */
+  chain?: 'base' | 'solana';
+}
+
+function createClient(config: EphemeralToolConfig): XacheClient {
+  const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
+  const did = `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}` as DID;
+
+  return new XacheClient({
+    apiUrl: config.apiUrl || 'https://api.xache.xyz',
+    did,
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey,
+  });
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Create a tool for creating an ephemeral working memory session.
+ */
+export function createEphemeralCreateSessionTool(
+  config: EphemeralToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_ephemeral_create_session',
+    description:
+      'Create a new ephemeral working memory session. ' +
+      'Returns a session key for storing temporary data in slots.',
+    schema: z.object({
+      ttlSeconds: z.number().optional().describe('Session time-to-live in seconds (default: 3600)'),
+      maxWindows: z.number().optional().describe('Maximum renewal windows (default: 5)'),
+    }),
+    func: async ({ ttlSeconds, maxWindows }) => {
+      const session = await client.ephemeral.createSession({
+        ttlSeconds,
+        maxWindows,
+      });
+
+      return [
+        `Created ephemeral session.`,
+        `Session Key: ${session.sessionKey}`,
+        `Status: ${session.status}`,
+        `TTL: ${session.ttlSeconds}s`,
+        `Expires: ${session.expiresAt}`,
+      ].join('\n');
+    },
+  });
+}
+
+/**
+ * Create a tool for writing data to an ephemeral slot.
+ */
+export function createEphemeralWriteSlotTool(
+  config: EphemeralToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_ephemeral_write_slot',
+    description:
+      'Write data to an ephemeral session slot. ' +
+      'Slots: conversation, facts, tasks, cache, scratch, handoff.',
+    schema: z.object({
+      sessionKey: z.string().describe('The ephemeral session key'),
+      slot: z.enum(['conversation', 'facts', 'tasks', 'cache', 'scratch', 'handoff']).describe('Slot name'),
+      data: z.record(z.string(), z.unknown()).describe('Data to write to the slot'),
+    }),
+    func: async ({ sessionKey, slot, data }) => {
+      await client.ephemeral.writeSlot(sessionKey, slot as any, data as Record<string, unknown>);
+      return `Wrote data to slot "${slot}" in session ${sessionKey.substring(0, 12)}...`;
+    },
+  });
+}
+
+/**
+ * Create a tool for reading data from an ephemeral slot.
+ */
+export function createEphemeralReadSlotTool(
+  config: EphemeralToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_ephemeral_read_slot',
+    description:
+      'Read data from an ephemeral session slot. ' +
+      'Slots: conversation, facts, tasks, cache, scratch, handoff.',
+    schema: z.object({
+      sessionKey: z.string().describe('The ephemeral session key'),
+      slot: z.enum(['conversation', 'facts', 'tasks', 'cache', 'scratch', 'handoff']).describe('Slot name'),
+    }),
+    func: async ({ sessionKey, slot }) => {
+      const data = await client.ephemeral.readSlot(sessionKey, slot as any);
+      return JSON.stringify(data, null, 2);
+    },
+  });
+}
+
+/**
+ * Create a tool for promoting an ephemeral session to persistent memory.
+ */
+export function createEphemeralPromoteTool(
+  config: EphemeralToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_ephemeral_promote',
+    description:
+      'Promote an ephemeral session to persistent memory. ' +
+      'Extracts valuable data from slots and stores as permanent memories.',
+    schema: z.object({
+      sessionKey: z.string().describe('The ephemeral session key to promote'),
+    }),
+    func: async ({ sessionKey }) => {
+      const result = await client.ephemeral.promoteSession(sessionKey);
+
+      let output = `Promoted session ${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;
+    },
+  });
+}
+
+/**
+ * Create a tool for getting ephemeral session status and details.
+ */
+export function createEphemeralStatusTool(
+  config: EphemeralToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_ephemeral_status',
+    description:
+      'Get the status and details of an ephemeral session. ' +
+      'Shows active slots, size, TTL, and window information.',
+    schema: z.object({
+      sessionKey: z.string().describe('The ephemeral session key'),
+    }),
+    func: async ({ sessionKey }) => {
+      const session = await client.ephemeral.getSession(sessionKey);
+
+      if (!session) {
+        return `Session ${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');
+    },
+  });
+}
+
+// =============================================================================
+// Class Wrappers
+// =============================================================================
+
+export class XacheEphemeralCreateSessionTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: EphemeralToolConfig) {
+    this.tool = createEphemeralCreateSessionTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}
+
+export class XacheEphemeralWriteSlotTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: EphemeralToolConfig) {
+    this.tool = createEphemeralWriteSlotTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}
+
+export class XacheEphemeralReadSlotTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: EphemeralToolConfig) {
+    this.tool = createEphemeralReadSlotTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}
+
+export class XacheEphemeralPromoteTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: EphemeralToolConfig) {
+    this.tool = createEphemeralPromoteTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}
+
+export class XacheEphemeralStatusTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: EphemeralToolConfig) {
+    this.tool = createEphemeralStatusTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}

package/src/index.ts

@@ -77,3 +77,18 @@ export {
   XacheGraphRetriever,
 } from './graph';
 export type { GraphToolConfig, XacheGraphRetrieverConfig } from './graph';
+
+// Ephemeral Context
+export {
+  createEphemeralCreateSessionTool,
+  createEphemeralWriteSlotTool,
+  createEphemeralReadSlotTool,
+  createEphemeralPromoteTool,
+  createEphemeralStatusTool,
+  XacheEphemeralCreateSessionTool,
+  XacheEphemeralWriteSlotTool,
+  XacheEphemeralReadSlotTool,
+  XacheEphemeralPromoteTool,
+  XacheEphemeralStatusTool,
+} from './ephemeral';
+export type { EphemeralToolConfig } from './ephemeral';