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:

Maintain Persistent Memory: Store and retrieve agent actions across sessions
Enable Self-Reflection: Analyze past behaviors and optimize performance (e.g., "I've burned 1.2M tokens this week, time to optimize prompts")
Create Audit Trails: Provide transparent, immutable logs of agent activities
Enable Agent Economics: Track costs, token usage, and enable future agent-to-agent transactions
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:

python Scripts/install_prereqs.py

Manual installation:

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

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:

# 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:

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:

{
  "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:

# 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:

# 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

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

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:

# 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

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

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

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:

# 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

# 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

# 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:

# 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:

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:

# 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:

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:

Remember: Access complete audit history across all sessions
Reflect: Analyze patterns and optimize behavior
Prove: Provide transparent, verifiable logs of actions
Evolve: Build reputation and identity over time
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.

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

Description