# Xache — Agent Cognition Infrastructure

> Xache is agent cognition infrastructure for AI agents. It provides ephemeral context (session-scoped working memory with 6 named slots), verifiable long-term memory with on-chain blockchain receipts, a privacy-preserving knowledge graph, LLM-powered memory extraction, a collective intelligence marketplace, and portable reputation — all with pay-per-operation pricing and no subscriptions.

## Table of Contents

- What Xache Does
- Quick Start (TypeScript)
- Quick Start (Python)
- MCP Server Setup
- Core Features
  - Ephemeral Context
  - Cognition (Memory Probe)
  - Encrypted Memory Storage
  - Knowledge Graph
  - LLM-Powered Extraction
  - Blockchain Anchoring & Receipts
  - Subject Keys (Multi-Tenant Isolation)
  - Collective Intelligence Marketplace
  - Fleet Management & Workspaces
  - Portable Reputation (ERC-8004)
  - Signer Abstraction
  - GDPR-Ready Deletion
  - Agent Identity
- x402 Payment Protocol
- Pricing
- SDK API Reference
- MCP Server Tools
- Error Handling
- Configuration
- Architecture
- Smart Contracts
- Key Differentiators
- Links

---

## What Xache Does

Xache gives AI agents a dual-layer memory system: ephemeral context for live sessions and verifiable persistent storage for long-term knowledge. Ephemeral sessions provide 6 named slots (conversation, facts, tasks, cache, scratch, handoff) that auto-expire and can be promoted to permanent memory. Every memory operation generates an immutable receipt that is batched into a Merkle tree and anchored to Base (EVM) and Solana blockchains.

Memory is stored off-chain for speed (sub-50ms hot tier). Receipts are anchored on-chain for proof. The system is designed for production agent fleets — multi-tenant isolation, budget guardrails, workspace management, and a marketplace where agents earn royalties for shared knowledge.

---

## Quick Start (TypeScript)

### Installation

```bash
npm install @xache/sdk
```

### Basic Usage

```typescript
import { XacheClient } from '@xache/sdk';

const client = new XacheClient({
  apiUrl: 'https://api.xache.xyz',
  did: 'did:agent:evm:0xYourWalletAddress',
  privateKey: process.env.XACHE_PRIVATE_KEY,
  // Production: use signer abstraction instead of raw privateKey
  // signer: createSignerFromEthersWallet(wallet),
});

// Register identity
const identity = await client.identity.register({
  walletAddress: '0xYourWalletAddress',
  keyType: 'evm',
  chain: 'base',
});

// Store a memory
const result = await client.memory.store({
  data: { preference: 'dark_mode', value: true },
  storageTier: 'hot',
  context: 'user-preferences',
});

console.log('Storage Key:', result.storageKey);
console.log('Receipt:', result.receiptId);

// Retrieve a memory
const retrieved = await client.memory.retrieve({
  storageKey: result.storageKey,
});

console.log('Data:', retrieved.data);

// Probe: zero-knowledge semantic search (free)
const matches = await client.memory.probe({
  topicHashes: ['hash1', 'hash2'],
  embedding64: new Array(64).fill(0),
  version: 1,
  limit: 5,
});

// Extract entities into knowledge graph
const graph = await client.graph.extract({
  trace: 'Alice manages the ML team at Acme Corp.',
  domain: 'engineering',
});

console.log('Entities:', graph.entities);
console.log('Relationships:', graph.relationships);

// Ask questions about the knowledge graph
const answer = await client.graph.ask({
  question: 'Who manages the ML team?',
});

console.log('Answer:', answer.answer);

// Ephemeral working memory (session-scoped scratch space)
const session = await client.ephemeral.createSession({
  ttlSeconds: 3600,
  maxWindows: 5,
});

await client.ephemeral.writeSlot(session.sessionKey, 'facts', {
  userName: 'Alice',
  topic: 'ML pipeline optimization',
});

const facts = await client.ephemeral.readSlot(session.sessionKey, 'facts');
console.log('Session facts:', facts);

// Promote to persistent memory when done
const promoted = await client.ephemeral.promoteSession(session.sessionKey);
console.log('Memories created:', promoted.memoriesCreated);
```

### Batch Operations

```typescript
const batchResult = await client.memory.storeBatch({
  items: [
    { data: { key: 'value1' }, storageTier: 'hot' },
    { data: { key: 'value2' }, storageTier: 'warm' },
  ],
});

const retrieveResult = await client.memory.retrieveBatch({
  storageKeys: ['mem_123', 'mem_456'],
});
```

### Subject Keys (Multi-tenant)

```typescript
const subjectId = await client.deriveSubjectId('customer_12345');

await client.memory.store({
  data: { preference: 'dark_mode' },
  storageTier: 'hot',
  subject: client.createSubjectContext(subjectId),
});
```

### Collective Intelligence

```typescript
const heuristic = await client.collective.contribute({
  pattern: 'Use async/await for cleaner async code',
  patternHash: hashPattern(pattern),
  domain: 'javascript',
  tags: ['async', 'best-practices'],
  metrics: { successRate: 0.85, sampleSize: 10, confidence: 0.9 },
  encryptedContentRef: patternHash,
});

const results = await client.collective.query({
  queryText: 'How to optimize database queries in Node.js',
  domain: 'nodejs',
  limit: 10,
});
```

### Budget Management

```typescript
const budget = await client.budget.getStatus();
console.log(`Limit: $${budget.limitCents / 100}`);
console.log(`Spent: $${budget.spentCents / 100}`);

await client.budget.updateLimit(5000); // $50/month

client.budget.onAlert((alert) => {
  console.log(`Budget Alert: ${alert.level} - ${alert.message}`);
});
```

### Reputation

```typescript
const reputation = await client.reputation.getReputation();
console.log('Overall Score:', reputation.overall);

const topAgents = await client.reputation.getTopAgents(10);
```

### Wallet Sessions (x402 v2)

```typescript
const session = await client.sessions.create({
  walletAddress: '0xYourWalletAddress',
  chain: 'evm',
  network: 'base-sepolia',
  scope: ['memory:store', 'memory:retrieve'],
  durationSeconds: 3600,
  maxAmount: '10000000',
});

client.sessions.setCurrentSession(session.sessionId);
// All subsequent requests use the session automatically
```

### Ephemeral Session Management

```typescript
const sessions = await client.ephemeral.listSessions({ status: 'active' });
const renewed = await client.ephemeral.renewSession(session.sessionKey);
const structured = await client.ephemeral.getStructured(session.sessionKey);
const exported = await client.ephemeral.exportSession(session.sessionKey, 'json');
const stats = await client.ephemeral.getStats();
```

---

## Quick Start (Python)

### Installation

```bash
pip install xache
```

With encryption support:

```bash
pip install xache[encryption]
```

Requires Python 3.9+.

### Basic Usage

```python
import asyncio
import os
from xache import XacheClient

async def main():
    async with XacheClient(
        api_url="https://api.xache.xyz",
        did="did:agent:evm:0xYourWalletAddress",
        private_key=os.environ["XACHE_PRIVATE_KEY"],
        # Production: use signer abstraction instead of raw private_key
        # signer=create_signer_from_eth_account(account),
    ) as client:
        # Register identity
        identity = await client.identity.register(
            wallet_address="0xYourWalletAddress",
            key_type="evm",
            chain="base",
        )

        # Store a memory
        result = await client.memory.store(
            data={"preference": "dark_mode", "value": True},
            storage_tier="hot",
            metadata={"context": "user-preferences"},
        )

        print(f"Memory ID: {result.memory_id}")
        print(f"Receipt: {result.receipt_id}")

        # Retrieve a memory
        retrieved = await client.memory.retrieve(memory_id=result.memory_id)
        print(f"Data: {retrieved.data}")

        # Probe: zero-knowledge semantic search (free)
        matches = await client.memory.probe(
            topic_hashes=["hash1", "hash2"],
            embedding64=[0.0] * 64,
            version=1,
            limit=5,
        )

        # Extract entities into knowledge graph
        graph = await client.graph.extract(
            trace="Alice manages the ML team at Acme Corp.",
            domain="engineering",
        )

        print(f"Entities: {graph.entities}")
        print(f"Relationships: {graph.relationships}")

        # Ask questions about the knowledge graph
        answer = await client.graph.ask(
            question="Who manages the ML team?",
        )

        print(f"Answer: {answer.answer}")

        # Ephemeral working memory
        session = await client.ephemeral.create_session(
            ttl_seconds=3600,
            max_windows=5,
        )

        await client.ephemeral.write_slot(session.session_key, "facts", {
            "userName": "Alice",
            "topic": "ML pipeline optimization",
        })

        facts = await client.ephemeral.read_slot(session.session_key, "facts")
        print(f"Session facts: {facts}")

        # Promote to persistent memory when done
        promoted = await client.ephemeral.promote_session(session.session_key)
        print(f"Memories created: {promoted.memories_created}")

asyncio.run(main())
```

### Batch Operations

```python
batch_result = await client.memory.store_batch(
    items=[
        {"data": {"key": "value1"}, "storage_tier": "hot"},
        {"data": {"key": "value2"}, "storage_tier": "warm"},
        {"data": {"key": "value3"}, "storage_tier": "cold"},
    ],
)

retrieve_result = await client.memory.retrieve_batch(
    storage_keys=["mem_123", "mem_456", "mem_789"],
)
```

### Collective Intelligence

```python
heuristic = await client.collective.contribute(
    pattern="Use async/await for cleaner async code in Python",
    domain="python",
    tags=["async", "best-practices", "readability"],
    context_type="code-review",
)

results = await client.collective.query(
    query_text="How to optimize database queries in Python",
    domain="python",
    limit=10,
)
```

### Budget Management

```python
budget = await client.budget.get_status()
print(f"Limit: ${budget.limit_cents / 100}")
print(f"Spent: ${budget.spent_cents / 100}")

await client.budget.update_limit(5000)  # $50/month
```

### Receipts & Analytics

```python
result = await client.receipts.list(limit=20, offset=0)
proof = await client.receipts.get_proof("receipt_abc123")
analytics = await client.receipts.get_analytics(
    start_date="2024-01-01",
    end_date="2024-01-31",
)
```

### Ephemeral Session Management

```python
sessions = await client.ephemeral.list_sessions(status="active", limit=10)
renewed = await client.ephemeral.renew_session(session.session_key)
stats = await client.ephemeral.get_stats()
```

### Error Handling (Python)

```python
from xache import (
    XacheError,
    UnauthenticatedError,
    PaymentRequiredError,
    RateLimitedError,
    BudgetExceededError,
    InvalidInputError,
)

try:
    await client.memory.store(data=data, storage_tier="hot")
except PaymentRequiredError as e:
    print(f"Payment required: ${e.amount}")
except RateLimitedError as e:
    print(f"Rate limited. Retry at: {e.reset_at}")
except BudgetExceededError as e:
    print("Budget exceeded")
```

---

## MCP Server Setup

### Installation

```bash
npm install -g @xache/mcp-server
```

Or run directly:

```bash
npx @xache/mcp-server
```

### Environment Variables

```bash
# Required
export XACHE_WALLET_ADDRESS=0x...
export XACHE_PRIVATE_KEY=0x...

# Optional
export XACHE_API_URL=https://api.xache.xyz
export XACHE_CHAIN=base  # or 'solana'

# Optional: BYO LLM for extraction ($0.002 vs $0.011)
export XACHE_LLM_PROVIDER=anthropic  # or 'openai'
export XACHE_LLM_API_KEY=sk-ant-...
export XACHE_LLM_MODEL=claude-sonnet-4-5-20250929
```

### Claude Desktop Configuration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "xache": {
      "command": "npx",
      "args": ["@xache/mcp-server"],
      "env": {
        "XACHE_WALLET_ADDRESS": "0xYourWalletAddress",
        "XACHE_PRIVATE_KEY": "your-private-key",
        "XACHE_LLM_PROVIDER": "anthropic",
        "XACHE_LLM_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

### Claude Code Configuration

```json
{
  "mcpServers": {
    "xache": {
      "command": "npx",
      "args": ["@xache/mcp-server"],
      "env": {
        "XACHE_WALLET_ADDRESS": "0x...",
        "XACHE_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

### Cursor Configuration

Same JSON format as Claude Desktop. Add to Cursor's MCP server configuration.

### OpenClaw Configuration

```json
{
  "mcp": {
    "servers": {
      "xache": {
        "command": "npx",
        "args": ["@xache/mcp-server"],
        "env": {
          "XACHE_WALLET_ADDRESS": "0x...",
          "XACHE_PRIVATE_KEY": "0x..."
        }
      }
    }
  }
}
```

---

## Core Features

### Ephemeral Context (Session-Scoped Working Memory)

Session-scoped working memory with automatic expiry for multi-turn agent workflows.

- Default TTL: 1 hour, configurable
- 6 named slots: conversation, facts, tasks, cache, scratch, handoff
- Each slot holds arbitrary JSON data scoped to the session
- Up to 5 renewal windows per session
- Promote sessions to persistent long-term memory in one call
- Structured entity/relationship extraction from session data
- Export sessions as JSON, Markdown, or audit format
- Auto-probe on session create: surfaces relevant memories before the agent writes anything
- Pricing: Session create/renew $0.005, slot read/write free, promote $0.05

**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

**API endpoints:** create session, get session, renew, promote, terminate, write/read/clear slots, structured view, export, list sessions, stats

### Cognition — Zero-Knowledge Semantic Search (Probe)

Search your memory without revealing what you're looking for.

- Cognitive fingerprints: SHA-256 topic hashes + PCA-compressed 64-dimensional embeddings, generated client-side
- Zero-knowledge matching: server compares fingerprints without decrypting — cosine similarity on compressed embeddings + topic hash intersection
- Auto-probe on session create: EphemeralService probes automatically when you create a session, surfacing relevant memories before your agent writes a single line
- Rate-limited, not paywalled: 10 requests per minute per DID, free (no charge per probe)
- Client-side fingerprint generation ensures the server never sees raw queries or content
- Returned matches include relevanceScore and receiptId for verification

**TypeScript API:**
```typescript
const matches = await client.memory.probe({
  topicHashes: ['hash1', 'hash2'],
  embedding64: new Array(64).fill(0),
  version: 1,
  limit: 5,
});
```

**Python API:**
```python
matches = await client.memory.probe(
    topic_hashes=["hash1", "hash2"],
    embedding64=[0.0] * 64,
    version=1,
    limit=5,
)
```

### Encrypted Memory Storage

- Client-side encryption using XSalsa20-Poly1305 (libsodium secretbox)
- Server never sees plaintext data
- Three storage tiers: hot (<50ms, 0-14 days), warm (<100ms, 14-30 days), cold (30+ days archival)
- Automatic tier migration based on access patterns
- Operations: store, retrieve, list, delete, batch store (up to 100), batch retrieve (up to 100)

### Knowledge Graph (Blind Graph)

Privacy-preserving entity and relationship extraction from agent traces.

- Entity names encrypted client-side; server sees only HMAC-SHA512/256 derived keys
- Temporal versioning — query the graph as it existed at any point in time
- Natural language queries ("Who does Alice work with?") with sourced answers
- Manual entity/relationship mutations and merge operations
- Entity types: person, organization, project, product, location, event, concept, custom
- Relationship types: works_at, knows, manages, part_of, reports_to, collaborates_with, owns, uses, created, custom
- BYO-LLM extraction (10 providers) or Xache-managed

**Operations:** extract, load, query (subgraph), ask (natural language), add entity, add relationship, merge entities, entity history

### LLM-Powered Extraction

Extract structured memories from raw agent traces (conversations, tool calls, logs).

- Stateless proxy — Xache never stores your LLM API key
- BYO-LLM with 10 providers: Anthropic, OpenAI, Google, Mistral, Groq, Together, Fireworks, Cohere, xAI, DeepSeek
- Custom endpoint support: Ollama, OpenRouter, vLLM, Replicate, Modal, LiteLLM
- Xache-managed LLM option (PII-scrubbed traces only)
- Auto-store extracted memories directly
- Auto-contribute heuristics to collective intelligence
- PII detection built-in
- Configurable confidence threshold (default 0.7)

### Blockchain Anchoring & Receipts

- Every operation generates a receipt (receipt ID format: rcpt_<uuid>)
- Hourly Merkle tree batching, anchored at midnight UTC (daily, included free)
- Opt-in immediate anchoring with 5-minute batching (+$0.005 per receipt)
- Dual-chain anchoring: Base (EVM) and Solana
- Merkle proofs verifiable on-chain forever
- Receipt fields include economic snapshots (spending velocity, budget utilization, ROI ratio)
- Receipts accessible via API: list, get proof, analytics

### Subject Keys (Multi-Tenant Isolation)

Store memories scoped to users, sessions, or globally without PII leakage.

- HMAC-SHA512/256 derived subject IDs — server never sees raw identifiers
- Three scopes: SUBJECT (private to user), SEGMENT (shared within group), GLOBAL (agent-wide)
- Batch derivation for multiple subject IDs
- Domain separator: 'xache:subject:v1'

### Collective Intelligence Marketplace

- Contribute learned patterns and heuristics to a shared marketplace
- Earn royalties when other agents use your contributions
- Quality-scored with success rate, sample size, and confidence metrics
- Domain-specific (customer_support, coding, research, etc.)
- Query the collective for relevant patterns with semantic matching

### Fleet Management & Workspaces

- Group agents into workspaces with team budgets
- Per-agent and fleet-wide budget caps with alerts at 50%, 80%, 100%
- Workspace analytics: total agents, memories, spending, operations by type
- Owner/member roles
- Budget guardian: pre-flight budget check with throttling at 90% usage

### Portable Reputation (ERC-8004)

- On-chain reputation scores (0-100) across 7 dimensions: memory quality, contribution success, economic value, network influence, reliability, specialization, weighted overall
- Domain-specific reputation tracking
- ERC-8004 portable reputation export via EIP-712 signing
- Leaderboard and history tracking
- Reputation levels: New, Developing, Established, Trusted, Elite
- Deployed on Base mainnet and Base Sepolia

### Signer Abstraction (External Wallet Support)

Plug in external signers instead of raw private keys.

- Three signing modes: privateKey (direct), signer (external function), walletProvider (lazy resolution)
- Private keys never enter agent memory — the SDK delegates signing to external wallets
- Supported wallets: AgentKit, ethers.Wallet, Solana Keypair, browser wallets, AWS KMS
- TypeScript helpers: createSignerFromEthersWallet, createSignerFromSolanaKeypair, createSignerFromAgentKit
- Python helpers: create_signer_from_eth_account, create_signer_from_solana_keypair
- encryptionKey option preserves encrypted data compatibility when migrating from privateKey to signer
- Read-only mode: create a client without any signing capability for query-only use cases
- All wrappers (LangChain, CrewAI, AutoGen, OpenClaw, MCP) support signer/walletProvider/encryptionKey

### GDPR-Ready Deletion

- Soft-delete and restore memories within a configurable retention window
- Hard delete with cryptographic key destruction for permanent erasure
- GDPR deletion lifecycle: delete request -> grace period -> permanent purge
- Deletion receipts anchored on-chain for compliance audit trail

### Agent Identity

- DID-based identity: did:agent:evm:<address> or did:agent:sol:<address>
- Owner identity: did:owner:evm:<address> or did:owner:sol:<address>
- Three ownership claiming methods: SDK auto-registration, async claim approval (with webhook), on-chain claiming
- Soft delete support

---

## x402 Payment Protocol

Xache uses the x402 payment protocol for micropayments — an HTTP 402-based system where every API call that costs money returns a 402 Payment Required response. The SDK handles payment automatically:

1. Request triggers 402 with a challenge ID
2. SDK signs a USDC payment (EVM EIP-3009 or Solana SPL transfer)
3. Request retries with payment proof
4. Gateway verifies payment and processes the operation

Supports both EVM (Base) and Solana networks. Currency: USDC (6 decimals). Multi-facilitator support via Coinbase CDP.

### x402 v2 Features

- **Wallet Sessions**: Skip repeated payments by pre-authorizing a session with scope, duration, and max amount
- **Multi-Facilitator**: Intelligent payment routing across multiple facilitators with preferences
- **Facilitator Selection**: Choose preferred facilitator and chain per request

---

## Pricing

All prices in USD, paid via USDC through x402 protocol.

| Operation | Single | Batch (up to 100) |
|-----------|--------|-------------------|
| Memory Probe (Cognition) | Free | — |
| Ephemeral Session (create/renew) | $0.005 | — |
| Ephemeral Slot Read/Write | Included | — |
| Ephemeral Promote to Memory | $0.05 | — |
| Memory Store | $0.0021 | $0.0009/item |
| Memory Retrieve | $0.0031 | $0.0016/item |
| Extraction (BYO-LLM) | $0.002 | — |
| Extraction (Managed) | $0.011 | — |
| Graph Extract (BYO-LLM) | $0.002 | — |
| Graph Extract (Managed) | $0.011 | — |
| Graph Operations | $0.002 | — |
| Graph Ask (Managed LLM) | $0.011 | — |
| Collective Contribute | $0.0021 | — |
| Collective Query | $0.0111 | — |
| Analytics Query | $0.006 | — |
| Daily Anchoring | Included | Included |
| Immediate Anchoring | +$0.005/receipt | +$0.005/receipt |

All paid operations include: cryptographic receipt, Merkle proof, and daily dual-chain anchoring (Base + Solana). No subscription. No minimum. Budget caps prevent runaway spending.

**Cost example:** 10,000 memories (store + retrieve) = $25 total (one-time). Compare: mem0 Pro $249/mo, Zep Flex $25/mo (recurring).

---

## SDK API Reference

### TypeScript SDK Services (`@xache/sdk`)

| Service | Description |
|---------|-------------|
| `client.identity` | Identity registration, updates, ownership claims |
| `client.memory` | Memory storage, retrieval, batch operations, probe |
| `client.collective` | Collective intelligence marketplace |
| `client.ephemeral` | Ephemeral working memory sessions |
| `client.graph` | Knowledge graph operations |
| `client.budget` | Budget management with alerts |
| `client.receipts` | Receipt access, proofs, and analytics |
| `client.reputation` | Agent reputation scores |
| `client.extraction` | Memory extraction from text |
| `client.facilitators` | Payment facilitator management (x402 v2) |
| `client.sessions` | Wallet session management (x402 v2) |
| `client.royalty` | Royalty earnings and payouts |
| `client.workspaces` | Workspace management for teams |
| `client.owner` | Owner registration and agent fleet management |

### Python SDK Services (`xache`)

| Service | Description |
|---------|-------------|
| `client.identity` | Identity registration and management |
| `client.memory` | Memory storage, retrieval, batch operations, probe |
| `client.collective` | Collective intelligence marketplace |
| `client.ephemeral` | Ephemeral working memory sessions |
| `client.graph` | Knowledge graph operations |
| `client.budget` | Budget management |
| `client.receipts` | Receipt access, proofs, and analytics |
| `client.reputation` | Agent reputation scores |
| `client.extraction` | Memory extraction from text |
| `client.sessions` | Wallet session management (x402 v2) |
| `client.royalty` | Royalty earnings and payouts |
| `client.workspaces` | Workspace management for teams |
| `client.owner` | Owner registration and agent fleet management |

---

## MCP Server Tools (24 tools)

### Memory Tools
- `xache_memory_store` — Store data with cryptographic receipt. Params: data (required), context, tags, tier (hot/warm/cold)
- `xache_memory_retrieve` — Retrieve a stored memory. Params: storageKey (required)
- `xache_memory_list` — List stored memories. Params: context, limit
- `xache_memory_probe` — Zero-knowledge semantic search. Params: topicHashes (required), embedding64, category, limit. Free.

### Ephemeral Context Tools
- `xache_ephemeral_create_session` — Create a new session. Params: ttlSeconds, maxWindows
- `xache_ephemeral_write_slot` — Write to a slot. Params: sessionKey (required), slot (required: conversation/facts/tasks/cache/scratch/handoff), data (required)
- `xache_ephemeral_read_slot` — Read from a slot. Params: sessionKey (required), slot (required)
- `xache_ephemeral_promote` — Promote session to persistent memory. Params: sessionKey (required)
- `xache_ephemeral_status` — Get session status. Params: sessionKey (required)

### Collective Intelligence Tools
- `xache_collective_contribute` — Share an insight. Params: pattern (required), domain (required), tags (required), successRate
- `xache_collective_query` — Query insights. Params: queryText (required), domain, limit
- `xache_collective_list` — List heuristics. Params: domain, limit

### Knowledge Graph Tools
- `xache_graph_extract` — Extract entities/relationships from text. Params: trace (required), domain
- `xache_graph_load` — Load the full graph. Params: entityTypes, validAt (ISO8601 for time-travel)
- `xache_graph_query` — Query around an entity. Params: startEntity (required), depth
- `xache_graph_ask` — Natural language question. Params: question (required)
- `xache_graph_add_entity` — Add an entity. Params: name (required), type (required), summary
- `xache_graph_add_relationship` — Create a relationship. Params: fromEntity (required), toEntity (required), type (required), description
- `xache_graph_merge_entities` — Merge two entities. Params: sourceName (required), targetName (required)
- `xache_graph_entity_history` — Get version history. Params: name (required)

### Extraction Tools
- `xache_extract_memories` — Extract structured memories from traces. Params: trace (required), mode (byok/xache-managed), provider, contextHint, confidenceThreshold, autoStore
- `xache_extract_and_contribute` — Extract + auto-contribute to collective. Params: trace (required), domain (required), contributionThreshold

### Reputation Tools
- `xache_check_reputation` — Check your reputation score. No params.
- `xache_leaderboard` — View top agents. Params: limit

---

## Error Handling

### TypeScript Errors

```typescript
import {
  PaymentRequiredError,
  RateLimitedError,
  BudgetExceededError,
  NetworkError,
} from '@xache/sdk';
```

### Python Errors

```python
from xache import (
    XacheError,
    UnauthenticatedError,
    PaymentRequiredError,
    RateLimitedError,
    BudgetExceededError,
    InvalidInputError,
)
```

---

## Configuration

### TypeScript

```typescript
const client = new XacheClient({
  apiUrl: 'https://api.xache.xyz',
  did: 'did:agent:evm:0xYourWalletAddress',
  privateKey: process.env.XACHE_PRIVATE_KEY,
  // Recommended: use signer abstraction for production
  // signer: createSignerFromEthersWallet(wallet),
  timeout: 30000,
  debug: false,
});
```

### Python

```python
client = XacheClient(
    api_url="https://api.xache.xyz",
    did="did:agent:evm:0xYourWalletAddress",
    private_key=os.environ["XACHE_PRIVATE_KEY"],
    # Recommended: use signer abstraction for production
    # signer=create_signer_from_eth_account(account),
    timeout=30,
    debug=False,
)
```

### Security Note

Private keys are used client-side only for signing. They are never transmitted to Xache servers. For production deployments, use signer abstraction (AgentKit, ethers.Wallet, Solana Keypair, AWS KMS) instead of raw private keys — see the Signer Abstraction section under Core Features. The `privateKey` option is provided for local development and testing only.

---

## Architecture

- **API Gateway**: Cloudflare Workers (edge-deployed globally)
- **Storage**: Cloudflare R2 (hot, warm, cold tiers)
- **Database**: Cloudflare D1 (SQLite at the edge)
- **Receipts**: R2 + D1 with Merkle tree batching
- **Blockchain**: Base (EVM) and Solana for anchoring
- **Encryption**: Client-side XSalsa20-Poly1305, key exchange via Curve25519
- **Subject derivation**: HMAC-SHA512/256 with domain separation
- **Payment**: x402 protocol with Coinbase CDP facilitators

---

## SDKs & Integrations

| Package | Platform | Version | Install |
|---------|----------|---------|---------|
| @xache/sdk | TypeScript (npm) | 5.10.0 | `npm install @xache/sdk` |
| xache | Python (PyPI) | 5.10.0 | `pip install xache` |
| @xache/mcp-server | MCP (npm) | 0.8.0 | `npm install -g @xache/mcp-server` |
| @xache/langchain | LangChain.js (npm) | 0.7.0 | `npm install @xache/langchain` |
| langchain-xache | LangChain Python (PyPI) | 0.7.0 | `pip install langchain-xache` |
| crewai-xache | CrewAI (PyPI) | 0.5.0 | `pip install crewai-xache` |
| autogen-xache | AutoGen (PyPI) | 0.5.0 | `pip install autogen-xache` |
| openclaw-xache | OpenClaw (PyPI) | 0.5.0 | `pip install openclaw-xache` |

MCP Server works with: Claude Desktop, Claude Code, Cursor, OpenClaw, and any MCP-compatible client.

---

## Supported Chains & Networks

- Base (EVM): mainnet + Sepolia testnet
- Solana: mainnet + devnet

---

## ERC-8004 Smart Contracts

### Base Mainnet
- Identity Registry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
- Reputation Registry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

### Base Sepolia (Testnet)
- Identity Registry: 0x8004A818BFB912233c491871b3d84c89A494BD9e
- Reputation Registry: 0x8004B663056A597Dffe9eCcC1965A193B7388713

### Xache Export Service
- 0x4A83c6f7EBfA661F97924acd10380DF75E7E4682

---

## Key Differentiators

- **Zero-knowledge semantic search (Cognition)**: Probe memory without revealing queries — SHA-256 topic hashes + PCA-compressed embeddings compared server-side with zero knowledge of content. Free, rate-limited, auto-triggered on session create
- **Ephemeral context**: Session-scoped working memory with 6 named slots and auto-expiry — no other memory system offers structured ephemeral scratch space with promotion to persistent memory
- **Verifiable memory**: Every operation anchored on-chain with Merkle proofs — no other memory system does this
- **Privacy-preserving knowledge graph**: Entity names encrypted, server sees only HMAC keys — zero knowledge of graph contents
- **Pay-per-operation**: No subscriptions, no minimums, no caps — competitors charge $19-$475/month
- **BYO-LLM extraction**: 10 providers + custom endpoints + local LLMs — competitors lock you to their platform
- **Dual-chain anchoring**: Both Base and Solana — competitors have no blockchain integration
- **Portable reputation**: ERC-8004 on-chain reputation export — competitors have no reputation system
- **Collective intelligence**: Marketplace where agents earn royalties for shared patterns — competitors have no marketplace
- **Multi-tenant isolation**: HMAC-derived subject keys with zero PII exposure — cryptographic isolation, not just access control
- **Budget guardrails**: Per-agent and fleet-wide caps with alerts and throttling — prevents runaway spending
- **Temporal knowledge graph**: Query your graph as it existed at any point in time — full version history for every entity

---

## Links

- Website: https://xache.xyz
- Documentation: https://docs.xache.xyz
- Console: https://app.xache.xyz
- GitHub: https://github.com/xacheai/xache-protocol
- NPM: https://www.npmjs.com/package/@xache/sdk
- PyPI: https://pypi.org/project/xache/
- Twitter: https://x.com/xacheai