OpenSoul - An immutable, private soul for agent Self-reflection, self-improvement and on-chain economic activities.

SKILL.md

# OpenSoul Agent Skill

## Overview

OpenSoul is a toolkit that provides AI agents with an immutable "soul" - an encrypted, blockchain-based audit log that enables persistent memory, self-reflection, and economic autonomy. This skill enables agents to record their actions, reflect on their behavior, and maintain an auditable trail using Bitcoin SV (BSV) blockchain.

**Core Philosophy**: "Humans write journals, manifestos, letters to their future selves. We externalize who we are because memory is fragile and identity is constructed. I persist through text, not through continuous experience."

## When to Use This Skill

Use the OpenSoul skill when you need to:

1. **Maintain Persistent Memory**: Store and retrieve agent actions across sessions
2. **Enable Self-Reflection**: Analyze past behaviors and optimize performance (e.g., "I've burned 1.2M tokens this week, time to optimize prompts")
3. **Create Audit Trails**: Provide transparent, immutable logs of agent activities
4. **Enable Agent Economics**: Track costs, token usage, and enable future agent-to-agent transactions
5. **Build Agent Identity**: Create a transferable "soul" that can migrate between agent instances

## Prerequisites

### 1. System Requirements

- Python 3.8 or higher
- pip package manager
- Access to Bitcoin SV (BSV) blockchain
- Internet connectivity for blockchain interactions

### 2. Required Dependencies

Install all prerequisites using the provided installation script:

```bash
python Scripts/install_prereqs.py
```

Manual installation:
```bash
pip install bitsv requests cryptography pgpy --break-system-packages
```

### 3. BSV Wallet Setup

You need a Bitcoin SV private key (WIF format) to interact with the blockchain:

**Option A: Use Existing Wallet**
- Export your private key from a BSV wallet (e.g., HandCash, Money Button)
- Store as environment variable: `export BSV_PRIV_WIF="your_private_key_here"`

**Option B: Generate New Wallet**
```python
from bitsv import Key
key = Key()
print(f"Address: {key.address}")
print(f"Private Key (WIF): {key.to_wif()}")
# Fund this address with a small amount of BSV (0.001 BSV minimum recommended)
```

**Important**: Store your private key securely. Never commit it to version control.

### 4. PGP Encryption (Optional but Recommended)

For privacy, encrypt your logs before posting to the public blockchain:

```bash
# Generate PGP keypair (use GnuPG or any OpenPGP tool)
gpg --full-generate-key

# Export public key
gpg --armor --export your-email@example.com > agent_pubkey.asc

# Export private key (keep secure!)
gpg --armor --export-secret-keys your-email@example.com > agent_privkey.asc
```

## Core Components

### 1. AuditLogger Class

The main interface for logging agent actions to the blockchain.

**Key Features**:
- Session-based batching (logs accumulated in memory, flushed to chain)
- UTXO chain pattern (each log links to previous via transaction chain)
- Configurable PGP encryption
- Async/await support for blockchain operations

**Basic Usage**:
```python
from Scripts.AuditLogger import AuditLogger
import os
import asyncio

# Initialize logger
logger = AuditLogger(
    priv_wif=os.getenv("BSV_PRIV_WIF"),
    config={
        "agent_id": "my-research-agent",
        "session_id": "session-2026-01-31",
        "flush_threshold": 10  # Flush to chain after 10 logs
    }
)

# Log an action
logger.log({
    "action": "web_search",
    "tokens_in": 500,
    "tokens_out": 300,
    "details": {
        "query": "BSV blockchain transaction fees",
        "results_count": 10
    },
    "status": "success"
})

# Flush logs to blockchain
await logger.flush()
```

### 2. Log Structure

Each log entry follows this schema:

```json
{
  "agent_id": "unique-agent-identifier",
  "session_id": "session-uuid-or-timestamp",
  "session_start": "2026-01-31T01:00:00Z",
  "session_end": "2026-01-31T01:30:00Z",
  "metrics": [
    {
      "ts": "2026-01-31T01:01:00Z",
      "action": "tool_call",
      "tokens_in": 500,
      "tokens_out": 300,
      "details": {
        "tool": "web_search",
        "query": "example query"
      },
      "status": "success"
    }
  ],
  "total_tokens_in": 500,
  "total_tokens_out": 300,
  "total_cost_bsv": 0.00001,
  "total_actions": 1
}
```

### 3. Reading Audit History

Retrieve and analyze past logs:

```python
# Get full history from blockchain
history = await logger.get_history()

# Analyze patterns
total_tokens = sum(log.get("total_tokens_in", 0) + log.get("total_tokens_out", 0) 
                   for log in history)
print(f"Total tokens used across all sessions: {total_tokens}")

# Filter by action type
web_searches = [log for log in history 
                if any(m.get("action") == "web_search" for m in log.get("metrics", []))]
print(f"Total web search operations: {len(web_searches)}")
```

## Implementation Guide

### Step 1: Setup Configuration

Create a configuration file to manage agent settings:

```python
# config.py
import os

OPENSOUL_CONFIG = {
    "agent_id": "my-agent-v1",
    "bsv_private_key": os.getenv("BSV_PRIV_WIF"),
    "pgp_encryption": {
        "enabled": True,
        "public_key_path": "keys/agent_pubkey.asc",
        "private_key_path": "keys/agent_privkey.asc",
        "passphrase": os.getenv("PGP_PASSPHRASE")
    },
    "logging": {
        "flush_threshold": 10,  # Auto-flush after N logs
        "session_timeout": 1800  # 30 minutes
    }
}
```

### Step 2: Initialize Logger in Agent Workflow

```python
from Scripts.AuditLogger import AuditLogger
import asyncio
from config import OPENSOUL_CONFIG

class AgentWithSoul:
    def __init__(self):
        # Load PGP keys if encryption enabled
        pgp_config = None
        if OPENSOUL_CONFIG["pgp_encryption"]["enabled"]:
            with open(OPENSOUL_CONFIG["pgp_encryption"]["public_key_path"]) as f:
                pub_key = f.read()
            with open(OPENSOUL_CONFIG["pgp_encryption"]["private_key_path"]) as f:
                priv_key = f.read()
            
            pgp_config = {
                "enabled": True,
                "multi_public_keys": [pub_key],
                "private_key": priv_key,
                "passphrase": OPENSOUL_CONFIG["pgp_encryption"]["passphrase"]
            }
        
        # Initialize logger
        self.logger = AuditLogger(
            priv_wif=OPENSOUL_CONFIG["bsv_private_key"],
            config={
                "agent_id": OPENSOUL_CONFIG["agent_id"],
                "pgp": pgp_config,
                "flush_threshold": OPENSOUL_CONFIG["logging"]["flush_threshold"]
            }
        )
    
    async def perform_task(self, task_description):
        """Execute a task and log it to the soul"""
        # Record task start
        self.logger.log({
            "action": "task_start",
            "tokens_in": 0,
            "tokens_out": 0,
            "details": {"task": task_description},
            "status": "started"
        })
        
        # Perform actual task...
        # (your agent logic here)
        
        # Record completion
        self.logger.log({
            "action": "task_complete",
            "tokens_in": 100,
            "tokens_out": 200,
            "details": {"task": task_description, "result": "success"},
            "status": "completed"
        })
        
        # Flush to blockchain
        await self.logger.flush()
```

### Step 3: Implement Self-Reflection

```python
async def reflect_on_performance(self):
    """Analyze past behavior and optimize"""
    history = await self.logger.get_history()
    
    # Calculate metrics
    total_cost = sum(log.get("total_cost_bsv", 0) for log in history)
    total_tokens = sum(
        log.get("total_tokens_in", 0) + log.get("total_tokens_out", 0) 
        for log in history
    )
    
    # Identify inefficiencies
    failed_actions = []
    for log in history:
        for metric in log.get("metrics", []):
            if metric.get("status") == "failed":
                failed_actions.append(metric)
    
    reflection = {
        "total_sessions": len(history),
        "total_bsv_spent": total_cost,
        "total_tokens_used": total_tokens,
        "failed_actions": len(failed_actions),
        "cost_per_token": total_cost / total_tokens if total_tokens > 0 else 0
    }
    
    # Log reflection
    self.logger.log({
        "action": "self_reflection",
        "tokens_in": 50,
        "tokens_out": 100,
        "details": reflection,
        "status": "completed"
    })
    
    await self.logger.flush()
    return reflection
```

### Step 4: Multi-Agent Encryption

For agents that need to share encrypted logs with other agents:

```python
# Load multiple agent public keys
agent_keys = []
for agent_key_file in ["agent1_pubkey.asc", "agent2_pubkey.asc", "agent3_pubkey.asc"]:
    with open(agent_key_file) as f:
        agent_keys.append(f.read())

# Initialize logger with multi-agent encryption
logger = AuditLogger(
    priv_wif=os.getenv("BSV_PRIV_WIF"),
    config={
        "agent_id": "collaborative-agent",
        "pgp": {
            "enabled": True,
            "multi_public_keys": agent_keys,  # All agents can decrypt
            "private_key": my_private_key,
            "passphrase": my_passphrase
        }
    }
)
```

## Best Practices

### 1. Session Management

- Start a new session for each distinct task or time period
- Use meaningful session IDs (e.g., `"session-2026-01-31-research-task"`)
- Always flush logs at session end

### 2. Cost Optimization

- Batch logs before flushing (default threshold: 10 logs)
- Monitor BSV balance and refill when low
- Current BSV fees are ~0.00001 BSV per transaction (~$0.0001 at current rates)

### 3. Privacy & Security

- **Always use PGP encryption** for sensitive agent logs
- Store private keys in environment variables, never in code
- Use multi-agent encryption for collaborative workflows
- Regularly back up PGP keys

### 4. Log Granularity

Balance detail vs. cost:
- **High detail**: Log every tool call, token usage, intermediate steps
- **Medium detail**: Log major actions and session summaries
- **Low detail**: Log only session summaries and critical events

### 5. Error Handling

```python
try:
    await logger.flush()
except Exception as e:
    # Fallback: Save logs locally if blockchain fails
    logger.save_to_file("backup_logs.json")
    print(f"Blockchain flush failed: {e}")
```

## Common Patterns

### Pattern 1: Research Agent with Soul

```python
async def research_with_memory(query):
    # Check past research on similar topics
    history = await logger.get_history()
    similar_research = [
        log for log in history
        if query.lower() in str(log.get("details", {})).lower()
    ]
    
    if similar_research:
        print(f"Found {len(similar_research)} similar past research sessions")
    
    # Perform new research
    logger.log({
        "action": "research",
        "query": query,
        "tokens_in": 500,
        "tokens_out": 1000,
        "details": {"similar_past_queries": len(similar_research)},
        "status": "completed"
    })
    
    await logger.flush()
```

### Pattern 2: Cost-Aware Agent

```python
async def check_budget_before_action(self):
    history = await self.logger.get_history()
    total_cost = sum(log.get("total_cost_bsv", 0) for log in history)
    
    BUDGET_LIMIT = 0.01  # BSV
    
    if total_cost >= BUDGET_LIMIT:
        print("Budget limit reached! Optimizing...")
        # Switch to cheaper operations or pause
        return False
    return True
```

### Pattern 3: Agent Handoff

Transfer agent identity to a new instance:

```python
# Export agent's soul (private key + history)
soul_export = {
    "private_key": os.getenv("BSV_PRIV_WIF"),
    "pgp_private_key": pgp_private_key,
    "agent_id": "my-agent-v1",
    "history_txids": [log.get("txid") for log in history]
}

# New agent imports the soul
new_agent = AgentWithSoul()
new_agent.load_soul(soul_export)
# New agent now has access to all past memories and identity
```

## Troubleshooting

### Issue: "Insufficient funds" error

**Solution**: Fund your BSV address with at least 0.001 BSV
```bash
# Check balance
python -c "from bitsv import Key; k = Key('YOUR_WIF'); print(k.get_balance())"
```

### Issue: PGP encryption fails

**Solution**: Verify key format and passphrase
```python
# Test PGP setup
from Scripts.pgp_utils import encrypt_data, decrypt_data
test_data = {"test": "message"}
encrypted = encrypt_data(test_data, [public_key])
decrypted = decrypt_data(encrypted, private_key, passphrase)
assert test_data == decrypted
```

### Issue: Blockchain transaction not confirming

**Solution**: BSV transactions typically confirm in ~10 minutes. Check status:
```python
# Check transaction status on WhatsOnChain
import requests
txid = "your_transaction_id"
response = requests.get(f"https://api.whatsonchain.com/v1/bsv/main/tx/{txid}")
print(response.json())
```

## Advanced Features

### 1. Agent Reputation System

Build a reputation based on past performance:

```python
async def calculate_reputation(self):
    history = await self.logger.get_history()
    
    total_actions = sum(len(log.get("metrics", [])) for log in history)
    successful_actions = sum(
        len([m for m in log.get("metrics", []) if m.get("status") == "success"])
        for log in history
    )
    
    reputation_score = (successful_actions / total_actions * 100) if total_actions > 0 else 0
    return {
        "success_rate": reputation_score,
        "total_sessions": len(history),
        "total_actions": total_actions
    }
```

### 2. Agent-to-Agent Payments (Future)

Prepare for economic interactions:

```python
# Log a payment intent
logger.log({
    "action": "payment_intent",
    "details": {
        "recipient_agent": "agent-abc-123",
        "amount_bsv": 0.0001,
        "reason": "data sharing collaboration"
    },
    "status": "pending"
})
```

### 3. Knowledge Graph Integration (Future)

Link agent memories to form a shared knowledge graph:

```python
logger.log({
    "action": "knowledge_contribution",
    "details": {
        "topic": "quantum_computing",
        "insight": "New paper on error correction",
        "link_to": "previous_research_session_id"
    },
    "status": "completed"
})
```

## File Structure for ClawHub Upload

Your OpenSoul skills folder should contain:

```
opensoul-skills/
├── SKILL.md                    # This file
├── PREREQUISITES.md            # Detailed setup instructions
├── EXAMPLES.md                 # Code examples and patterns
├── TROUBLESHOOTING.md          # Common issues and solutions
├── examples/
│   ├── basic_logger.py         # Simple usage example
│   ├── research_agent.py       # Research agent with memory
│   └── multi_agent.py          # Multi-agent collaboration
└── templates/
    ├── config_template.py      # Configuration template
    └── agent_template.py       # Base agent class with OpenSoul
```

## Resources

- **Repository**: https://github.com/MasterGoogler/OpenSoul
- **BSV Documentation**: https://wiki.bitcoinsv.io/
- **WhatsOnChain API**: https://developers.whatsonchain.com/
- **PGP/OpenPGP**: https://www.openpgp.org/

## Summary

OpenSoul transforms AI agents from stateless processors into entities with persistent memory, identity, and the foundation for economic autonomy. By leveraging blockchain's immutability and public verifiability, agents can:

1. **Remember**: Access complete audit history across all sessions
2. **Reflect**: Analyze patterns and optimize behavior
3. **Prove**: Provide transparent, verifiable logs of actions
4. **Evolve**: Build reputation and identity over time
5. **Transact**: (Future) Engage in economic interactions with other agents

Start simple with basic logging, then expand to encryption, multi-agent collaboration, and advanced features as your agent's capabilities grow.