Introduction
# 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) 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.