Enables AI agents to log immutable, encrypted audit trails on Bitcoin SV for persistent memory, self-reflection, and on-chain economic tracking.
Real data. Real impact.
Emerging
Developers
Per week
Open source
Skills give you superpowers. Install in 30 seconds.
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."
Use the OpenSoul skill when you need to:
Install all prerequisites using the provided installation script:
python Scripts/install_prereqs.py
Manual installation:
pip install bitsv requests cryptography pgpy --break-system-packages
You need a Bitcoin SV private key (WIF format) to interact with the blockchain:
Option A: Use Existing Wallet
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.
For privacy, encrypt your logs before posting to the public blockchain:
# Generate PGP keypair (use GnuPG or any OpenPGP tool) gpg --full-generate-keyExport 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
The main interface for logging agent actions to the blockchain.
Key Features:
Basic Usage:
from Scripts.AuditLogger import AuditLogger import os import asyncioInitialize 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()
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 }
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)}")
Create a configuration file to manage agent settings:
# config.py import osOPENSOUL_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 } }
from Scripts.AuditLogger import AuditLogger import asyncio from config import OPENSOUL_CONFIGclass 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()
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
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 } } )
"session-2026-01-31-research-task"Balance detail vs. cost:
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}")
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()
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
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
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())"
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
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())
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 }
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" })
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" })
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
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:
Start simple with basic logging, then expand to encryption, multi-agent collaboration, and advanced features as your agent's capabilities grow.
No automatic installation available. Please visit the source repository for installation instructions.
View Installation Instructions
1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.