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

# 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 [email protected] > agent_pubkey.asc

# Export private key (keep secure!)
gpg --armor --export-secret-keys [email protected] > 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)