@xache/langchain 0.4.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/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { BaseMemory, InputValues, MemoryVariables, OutputValues } from '@langchain/core/memory';
 import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
 import { BaseMessage } from '@langchain/core/messages';
+import { XacheSigner, XacheWalletProvider, LLMProvider, LLMApiFormat, SubjectContext } from '@xache/sdk';
 import { BaseRetriever, BaseRetrieverInput } from '@langchain/core/retrievers';
 import { Document } from '@langchain/core/documents';
 import { CallbackManagerForRetrieverRun } from '@langchain/core/callbacks/manager';
-import { LLMProvider, LLMApiFormat, SubjectContext } from '@xache/sdk';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 
 /**
@@ -15,8 +15,14 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
 interface XacheChatMessageHistoryConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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;
     /** Session ID to group messages */
     sessionId?: string;
     /** API URL (defaults to https://api.xache.xyz) */
@@ -166,8 +172,14 @@ declare class XacheConversationBufferMemory extends XacheMemory {
 interface XacheRetrieverConfig extends BaseRetrieverInput {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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;
     /** Number of documents to retrieve */
     k?: number;
     /** Filter by context */
@@ -238,8 +250,14 @@ interface ExtractionResult {
 interface XacheExtractorConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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;
     /**
      * Extraction mode:
      * - 'xache-managed': Xache provides the LLM ($0.011)
@@ -336,8 +354,14 @@ declare class XacheExtractor {
 interface CollectiveToolConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */
@@ -400,8 +424,14 @@ declare class XacheCollectiveQueryTool {
 interface ReputationToolConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */
@@ -484,8 +514,14 @@ declare class XacheReputationChecker {
 interface GraphToolConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */
@@ -598,8 +634,14 @@ declare class XacheGraphEntityHistoryTool {
 interface XacheGraphRetrieverConfig extends BaseRetrieverInput {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { BaseMemory, InputValues, MemoryVariables, OutputValues } from '@langchain/core/memory';
 import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
 import { BaseMessage } from '@langchain/core/messages';
+import { XacheSigner, XacheWalletProvider, LLMProvider, LLMApiFormat, SubjectContext } from '@xache/sdk';
 import { BaseRetriever, BaseRetrieverInput } from '@langchain/core/retrievers';
 import { Document } from '@langchain/core/documents';
 import { CallbackManagerForRetrieverRun } from '@langchain/core/callbacks/manager';
-import { LLMProvider, LLMApiFormat, SubjectContext } from '@xache/sdk';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 
 /**
@@ -15,8 +15,14 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
 interface XacheChatMessageHistoryConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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;
     /** Session ID to group messages */
     sessionId?: string;
     /** API URL (defaults to https://api.xache.xyz) */
@@ -166,8 +172,14 @@ declare class XacheConversationBufferMemory extends XacheMemory {
 interface XacheRetrieverConfig extends BaseRetrieverInput {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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;
     /** Number of documents to retrieve */
     k?: number;
     /** Filter by context */
@@ -238,8 +250,14 @@ interface ExtractionResult {
 interface XacheExtractorConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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;
     /**
      * Extraction mode:
      * - 'xache-managed': Xache provides the LLM ($0.011)
@@ -336,8 +354,14 @@ declare class XacheExtractor {
 interface CollectiveToolConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */
@@ -400,8 +424,14 @@ declare class XacheCollectiveQueryTool {
 interface ReputationToolConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */
@@ -484,8 +514,14 @@ declare class XacheReputationChecker {
 interface GraphToolConfig {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */
@@ -598,8 +634,14 @@ declare class XacheGraphEntityHistoryTool {
 interface XacheGraphRetrieverConfig extends BaseRetrieverInput {
     /** Wallet address for authentication */
     walletAddress: string;
-    /** Private key for signing */
-    privateKey: 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' */

package/dist/index.js

@@ -70,6 +70,9 @@ var XacheChatMessageHistory = class extends import_chat_history.BaseListChatMess
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
       privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey,
       timeout: config.timeout,
       debug: config.debug
     });
@@ -264,7 +267,10 @@ var XacheRetriever = class extends import_retrievers.BaseRetriever {
     this.client = new import_sdk2.XacheClient({
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
-      privateKey: config.privateKey
+      privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey
     });
     this.k = config.k ?? 5;
     this.filterContext = config.context;
@@ -310,6 +316,9 @@ var XacheExtractor = class {
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
       privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey,
       timeout: config.timeout,
       debug: config.debug
     });
@@ -398,7 +407,10 @@ function createClient(config) {
   return new import_sdk4.XacheClient({
     apiUrl: config.apiUrl || "https://api.xache.xyz",
     did,
-    privateKey: config.privateKey
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey
   });
 }
 function createCollectiveContributeTool(config) {
@@ -507,7 +519,10 @@ function createClient2(config) {
   return new import_sdk5.XacheClient({
     apiUrl: config.apiUrl || "https://api.xache.xyz",
     did,
-    privateKey: config.privateKey
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey
   });
 }
 function createReputationTool(config) {
@@ -602,7 +617,10 @@ function createClient3(config) {
   return new import_sdk6.XacheClient({
     apiUrl: config.apiUrl || "https://api.xache.xyz",
     did,
-    privateKey: config.privateKey
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey
   });
 }
 function getSubject(config) {
@@ -912,7 +930,10 @@ var XacheGraphRetriever = class extends import_retrievers2.BaseRetriever {
     this.client = new import_sdk6.XacheClient({
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
-      privateKey: config.privateKey
+      privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey
     });
     this.subject = config.subject || { scope: "GLOBAL" };
     this.startEntity = config.startEntity;