# Send OpenSoul - An immutable, private soul for agent Self-reflection, self-improvement and on-chain economic activities. to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "opensoul",
    "name": "OpenSoul - An immutable, private soul for agent Self-reflection, self-improvement and on-chain economic activities.",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/MasterGoogler/opensoul",
    "canonicalUrl": "https://clawhub.ai/MasterGoogler/opensoul",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/opensoul",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=opensoul",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "agent_template.py",
      "basic_logger.py",
      "config_template.py",
      "EXAMPLES.md",
      "PACKAGE_SUMMARY.md",
      "PREREQUISITES.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "opensoul",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-02T23:32:39.161Z",
      "expiresAt": "2026-05-09T23:32:39.161Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=opensoul",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=opensoul",
        "contentDisposition": "attachment; filename=\"opensoul-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "opensoul"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/opensoul"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/opensoul",
    "downloadUrl": "https://openagent3.xyz/downloads/opensoul",
    "agentUrl": "https://openagent3.xyz/skills/opensoul/agent",
    "manifestUrl": "https://openagent3.xyz/skills/opensoul/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/opensoul/agent.md"
  }
}
```
## Documentation

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

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

### 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)}")

### 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
        }
    }
)

### 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}")

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

### 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())

### 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.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: MasterGoogler
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-02T23:32:39.161Z
- Expires at: 2026-05-09T23:32:39.161Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/opensoul)
- [Send to Agent page](https://openagent3.xyz/skills/opensoul/agent)
- [JSON manifest](https://openagent3.xyz/skills/opensoul/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/opensoul/agent.md)
- [Download page](https://openagent3.xyz/downloads/opensoul)