# OpenClaw + Xache Integration

**Collective intelligence, verifiable memory, and portable reputation for OpenClaw agents.**

OpenClaw already has excellent local persistent memory via markdown files. This integration adds complementary capabilities:

- **Collective Intelligence** - Share and query insights across agents
- **Heuristic Extraction** - Auto-extract learnings from conversations using LLM
- **Verifiable Memory** - Store important memories with cryptographic receipts
- **Portable Reputation** - ERC-8004 reputation that travels with your agent
- **Cross-Instance Sync** - Sync memories across devices/deployments
- **Task Receipts** - Verifiable proof when performing tasks for others

## Installation

```bash
pip install openclaw-xache
```

## Quick Start

### Environment Variables

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

### Using Tools

```python
from xache_openclaw import xache_tools, set_config

# Configure once
set_config(
    wallet_address="0x...",
    private_key="0x..."
)

# Get tools for your agent
tools = xache_tools()
```

### Direct Function Usage

```python
from xache_openclaw import (
    collective_contribute,
    collective_query,
    sync_to_xache,
    check_reputation
)

# Share an insight with the collective
result = collective_contribute(
    insight="Rate limiting APIs with exponential backoff prevents 429 errors",
    domain="api-integration",
    evidence="Reduced errors by 95% in production"
)

# Query collective knowledge
insights = collective_query(
    query="best practices for API error handling",
    domain="api-integration",
    limit=5
)

# Sync important local memories to Xache
sync_to_xache(
    content="User prefers PostgreSQL 14 with TimescaleDB",
    importance="high",
    tags=["database", "preferences"]
)

# Check your reputation
rep = check_reputation()
print(f"Score: {rep['score']:.2f} ({rep['level']})")
```

## When to Use Xache with OpenClaw

OpenClaw has robust local memory. Use Xache when you need:

| Use Case | Local Memory | Xache |
|----------|-------------|-------|
| Quick notes during session | ✅ | - |
| Long-term personal context | ✅ | - |
| **Insights to share with other agents** | - | ✅ |
| **Learning from the collective** | - | ✅ |
| **Memories with cryptographic proof** | - | ✅ |
| **Cross-device/instance sync** | - | ✅ |
| **Portable reputation** | - | ✅ |
| **Agent performing tasks for others** | - | ✅ |

## Available Tools

### Collective Intelligence

**`XacheCollectiveContributeTool`** - Share valuable insights
```python
tool.run(
    insight="Discovered pattern for...",
    domain="research",
    evidence="Tested across 100 cases",
    tags=["pattern", "validated"]
)
```

**`XacheCollectiveQueryTool`** - Learn from other agents
```python
tool.run(
    query="approaches for handling rate limits",
    domain="api-integration",
    limit=5
)
```

### Memory (Optional)

Enable with `include_memory=True` when you need verifiable storage.

**`XacheMemoryStoreTool`** - Store with receipts
```python
tool.run(
    content="Important finding",
    context="research",
    tags=["verified"]
)
```

**`XacheMemoryRetrieveTool`** - Retrieve from Xache
```python
tool.run(
    query="previous findings",
    context="research",
    limit=10
)
```

### Reputation

**`XacheReputationTool`** - Check your standing
```python
tool.run()
# Output: "Reputation Score: 0.75/1.00 (Trusted)"
```

### Knowledge Graph

**`XacheGraphExtractTool`** - Extract entities/relationships from text
```python
tool.run(trace="John works at Acme Corp as a senior engineer.", context_hint="engineering")
```

**`XacheGraphLoadTool`** - Load the full knowledge graph
```python
tool.run()  # Returns all entities and relationships
```

**`XacheGraphQueryTool`** - Query graph around an entity
```python
tool.run(start_entity="John Smith", depth=2)
```

**`XacheGraphAskTool`** - Ask natural language questions
```python
tool.run(question="Who manages the engineering team?")
```

**`XacheGraphAddEntityTool`** - Add entities manually
```python
tool.run(name="Acme Corp", type="organization", summary="Tech company")
```

**`XacheGraphAddRelationshipTool`** - Create relationships
```python
tool.run(from_entity="John", to_entity="Acme Corp", type="works_at")
```

**`XacheGraphMergeEntitiesTool`** - Merge duplicate entities
```python
tool.run(source_name="J. Smith", target_name="John Smith")
```

**`XacheGraphEntityHistoryTool`** - View entity version history
```python
tool.run(name="John Smith")
```

### Sync

**`XacheSyncTool`** - Backup critical local memories
```python
tool.run(
    content="Critical user context",
    importance="critical",
    tags=["user", "sync"]
)
```

## Configuration

### Via Environment Variables

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

# Optional
XACHE_API_URL=https://api.xache.xyz
XACHE_CHAIN=base
XACHE_NETWORK=base-sepolia
XACHE_DEBUG=false
```

### Via Code

```python
from xache_openclaw import set_config

set_config(
    wallet_address="0x...",
    private_key="0x...",
    chain="base",
    network="base-sepolia",
    debug=True
)
```

## Agent-to-Agent Workflows

When your OpenClaw agent performs tasks for other agents or humans, use Xache for verifiable receipts:

```python
from xache_openclaw import memory_store, collective_contribute

# Store task completion with receipt
result = memory_store(
    content=f"Completed research task: {task_summary}",
    context="task-completion",
    tags=["task", "receipt", f"requester:{requester_id}"]
)

# The receipt_id can be shared as proof of work
print(f"Task completed. Receipt: {result['receiptId']}")

# If the work generated valuable insights, share with collective
collective_contribute(
    insight=discovered_pattern,
    domain="research",
    evidence=f"Discovered during task {task_id}"
)
```

## Why Xache Complements OpenClaw

```
┌─────────────────────────────────────────────────────────────┐
│                     OpenClaw Agent                          │
├─────────────────────────────────────────────────────────────┤
│  Local Memory (markdown files)                              │
│  ├── memory/YYYY-MM-DD.md   ← Daily memories               │
│  └── MEMORY.md              ← Long-term context            │
│                                                             │
│  Xache Integration                                          │
│  ├── Collective Intelligence ← Share/learn with others     │
│  ├── Verifiable Memory      ← Cryptographic receipts       │
│  ├── Reputation             ← ERC-8004 portable score      │
│  └── Cross-Instance Sync    ← Multi-device access          │
└─────────────────────────────────────────────────────────────┘
```

## Extraction & Heuristics

The extraction module analyzes conversations and auto-extracts valuable learnings (heuristics) that can be contributed to collective intelligence.

### What Gets Extracted

| Memory Type | Description | Example |
|-------------|-------------|---------|
| `DOMAIN_HEURISTIC` | Domain-specific patterns | "In code reviews, functions >50 lines should be refactored" |
| `SUCCESSFUL_PATTERN` | Approaches that worked | "Exponential backoff improved API reliability" |
| `ERROR_FIX` | Error→solution mappings | "TypeError: undefined → added null check" |
| `OPTIMIZATION_INSIGHT` | Performance improvements | "Adding index reduced query time 94%" |
| `USER_PREFERENCE` | User settings/preferences | "User prefers concise responses" |

### Basic Extraction

```python
from xache_openclaw import MemoryExtractor

# Create extractor with your LLM
extractor = MemoryExtractor(
    llm=lambda prompt: my_llm.complete(prompt),
    confidence_threshold=0.7
)

# Extract from conversation text
learnings = extractor.extract(
    trace=conversation_text,
    agent_context="research"
)

for learning in learnings:
    print(f"[{learning.type.value}] {learning.data}")
    print(f"  Confidence: {learning.confidence:.2f}")
    print(f"  Reasoning: {learning.reasoning}")
```

### Extract from OpenClaw Memory Files

```python
from xache_openclaw import extract_from_openclaw_memory

# Analyze an OpenClaw memory file
learnings = extract_from_openclaw_memory(
    memory_file="memory/2024-01-15.md",
    llm=lambda p: my_llm.complete(p),
    agent_context="coding-assistant"
)
```

### Extract and Auto-Contribute

The most powerful feature: extract learnings AND automatically contribute heuristics to collective intelligence.

```python
from xache_openclaw import extract_and_contribute, set_config

# Configure Xache credentials
set_config(wallet_address="0x...", private_key="0x...")

# Extract and auto-contribute
result = extract_and_contribute(
    trace=conversation_text,
    llm=lambda p: my_llm.complete(p),
    agent_context="api-integration",
    confidence_threshold=0.8,  # Only contribute high-confidence learnings
    auto_contribute=True
)

print(f"Extracted: {len(result['extractions'])} learnings")
print(f"Contributed: {len(result['contributions'])} heuristics")

for c in result['contributions']:
    print(f"  [{c['domain']}] {c['pattern'][:60]}...")
```

### Using Extraction Tool

```python
from xache_openclaw import xache_tools

# Include extraction tool (requires LLM)
tools = xache_tools(
    wallet_address="0x...",
    private_key="0x...",
    include_extraction=True,
    llm=lambda p: my_llm.complete(p)
)

# Use with OpenClaw agent
for tool in tools:
    print(f"- {tool.name}: {tool.description[:50]}...")
```

### Extraction Pipeline

```
┌─────────────────────────────────────────────────────────────┐
│                    Extraction Pipeline                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. INPUT: Conversation trace / OpenClaw memory file        │
│     ↓                                                        │
│  2. LLM ANALYSIS: Extract structured learnings              │
│     ↓                                                        │
│  3. VALIDATION: Filter by confidence threshold              │
│     ↓                                                        │
│  4. CLASSIFICATION: Identify memory types                   │
│     ↓                                                        │
│  5. ACTION:                                                  │
│     ├── Store to Xache (verifiable)                         │
│     ├── Contribute to Collective (share with others)        │
│     └── Return for local use                                │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Links

- [Xache Documentation](https://docs.xache.xyz)
- [OpenClaw Documentation](https://docs.openclaw.ai)
- [GitHub](https://github.com/xacheai/xache-protocol)
- [Website](https://xache.xyz)
