mastergoogler-opensoul

OpenSoul 开源人格与身份框架，为 AI 智能体定义持久化个性、信念与行为边界。

## 概述（中文）

OpenSoul 开源人格与身份框架，为 AI 智能体定义持久化个性、信念与行为边界。

## 技能正文

# OpenSoul Agent Skill

## 概述

OpenSoul is a toolkit that provides AI 智能体s with an immutable "soul" - an encrypted, blockchain-based audit log that enables persistent memory, self-reflection, and economic autonomy. 本技能 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."

## 何时使用 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. **创建 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**: 创建 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. 必填 Dependencies

安装 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

你需要 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. 切勿 commit it to version control.

### 4. PGP Encryption (可选 but Recommended)

对于 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 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**:
```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

创建 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)
    
    re