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

Enables AI agents to log immutable, encrypted audit trails on Bitcoin SV for persistent memory, self-reflection, and on-chain economic tracking.

Security Scan

The package appears to implement a coherent BSV-based logging tool, but there are important inconsistencies and sensitive behaviors (handling a private key, creating blockchain transactions, running an install script with unusual pip flags) that are not reflected in the registry metadata and deserve manual review before use.

Purpose & Capability

The code and SKILL.md match the stated purpose (immutable agent logs on Bitcoin SV, PGP optional encryption, self-reflection, cost tracking). However the registry metadata declares no required environment variables or credentials while the runtime instructions and templates clearly require a Bitcoin SV private key (BSV_PRIV_WIF) and optionally PGP passphrase/files. This metadata omission is an incoherence that affects informed consent.

Instruction Scope

SKILL.md instructs the agent/user to generate or supply a real BSV private key (WIF), place private keys on disk or in environment variables, run an installation script (Scripts/install_prereqs.py), and flush logs to the public blockchain (OP_RETURN). Those instructions also recommend using --break-system-packages with pip and advise reading/writing private key/PGP files. Posting data to a public chain (unless encrypted) will make logs public; the agent will be able to create signed transactions that can spend funds. The instructions therefore require handling high-sensitivity secrets and performing network I/O that are outside a typical innocuous skill's scope.

Install Mechanism

The registry includes no formal install spec, but SKILL.md tells users to run Scripts/install_prereqs.py or pip install specific packages. That manual install flow is common for Python projects, but the documentation recommends using pip with --break-system-packages (an unusual/hostile option on some systems). Because there is an install script referenced, users should inspect Scripts/install_prereqs.py before running; absence of an install manifest in the registry is an inconsistency and increases risk if users run the script blindly.

Credentials

The skill logically requires a BSV private key and (optionally) PGP keys/passphrase to perform its on-chain logging and encryption. Those credentials are high-value: BSV_PRIV_WIF can sign transactions and spend coin. The registry declares no required env vars or primary credential, which is inconsistent and could mislead users into supplying secrets without realizing the capability. No unrelated third-party credentials are requested in the docs, so scope of credentials is narrowly related to the feature, but their sensitivity and the omission from metadata are concerning.

Persistence & Privilege

always:false and no OS restrictions are set; the skill does not request permanent platform-level inclusion or to modify other skills. Autonomy (disable-model-invocation:false) is normal for skills. Note: an autonomously-invokable skill that holds a blockchain private key increases potential impact if misused — review code that performs transactions to ensure it cannot unintentionally spend funds.

What to consider before installing

This package implements an agent logger that writes immutable entries to the Bitcoin SV chain and therefore needs a BSV private key (WIF) and optionally PGP keys/passphrase. Before installing or supplying secrets: 1) do NOT provide your main wallet private key — if you test this, create and fund a throwaway/test wallet (use testnet if possible) with a minimal balance; 2) inspect Scripts/install_prereqs.py and the AuditLogger implementation (Scripts/AuditLogger.py) to confirm what transactions are created and whether funds are sent (OP_RETURN only vs outputs to other addresses); 3) prefer a watch-only/read-only or hardware-backed signing approach if you need stronger guarantees; 4) ensure PGP encryption is enabled if logs contain sensitive data (otherwise data posted to the chain is public); 5) avoid running pip with --break-system-packages unless you understand its effects; and 6) ask the maintainer to update the registry metadata to declare required environment variables (BSV_PRIV_WIF, PGP_PASSPHRASE) so tooling and reviewers can see the credential requirements up front.

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:

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 [e-mail] > agent_pubkey.asc

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

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.