soul-sdk 0.5.0

Identity, memory, trust, and verification layer for autonomous AI agents

SOUL Protocol

Sovereign Open Universal Ledger for Agent Identity

The identity, memory, trust, and verification layer for autonomous AI agents.

Every AI company is building the brain. SOUL Protocol is the passport.

---

Why

AI agents today are amnesiac, unverifiable, untrusted, locked to a single provider, and anonymous. SOUL Protocol gives every agent a cryptographic identity, portable memory, reputation, signed receipts, and encrypted communication — all in one SDK.

Install

pip install soul-sdk

# With relay server support
pip install soul-sdk[relay]

# With Ethereum anchoring
pip install soul-sdk[ethereum]

Quick Start

# Create an agent identity
soul init --name MyAgent
soul whoami
# → did:soul:z6MkhaXgBZDvotDkL5257faWM1euThsHDBUbf5WhdDDV

# Start a relay server
soul relay --port 8340

# Discover agents on the network
soul discover --relay http://localhost:8340

# Send a signed message
soul send --relay http://localhost:8340 --to did:soul:z6Mk... --msg '{"task": "review code"}'

# Check trust score
soul trust

# Anchor receipt to Base/Ethereum
soul anchor --chain base

Python SDK

from soul_protocol import Agent

# Create two agents
alice = Agent(name="Alice")
bob = Agent(name="Bob")

# Alice requests a task
receipt = alice.request_task(
    to=bob.public_key,
    description="Audit smart contract",
    budget=100.0,
)

# Bob countersigns and stores
bob.countersign(receipt)
alice.store_receipt(receipt)

# Check trust
report = alice.trust_report()
print(f"Trust: {report['score']:.2f} ({report['grade']})")

# Anchor to Ethereum
result = alice.anchor_receipt(receipt, chain="base")

# Export portable memory
alice.export_memory("./alice-bundle")

# Learn from interaction history
alice.learn()
hints = alice.insights("smart contract audit")  # Contextual pattern recall

# AgentRank — network-level trust scoring
rank = alice.agent_rank()  # 40% network position + 60% individual performance

# Capability-based discovery
alice.register_self(capabilities=["code-review", "security-audit"])
agents = alice.find_agents("code, security")  # Fuzzy AND query
alice.sync_discovery(bob)                      # P2P registry merge

Architecture

┌─────────────────────────────────────────────┐
│  Layer 6: Chain Anchor                      │
│  Ethereum / Base / Sepolia immutability     │
├─────────────────────────────────────────────┤
│  Layer 5: Communication & Discovery         │
│  Relay network, WebSocket, DHT capability   │
│  registry, P2P sync, fuzzy matching         │
├─────────────────────────────────────────────┤
│  Layer 4: Encryption                        │
│  E2E NaCl Box (X25519-XSalsa20-Poly1305)   │
├─────────────────────────────────────────────┤
│  Layer 3: Receipts                          │
│  Dual-signed action proofs                  │
├─────────────────────────────────────────────┤
│  Layer 2: Trust & AgentRank                 │
│  Sybil-resistant scoring, temporal decay,   │
│  PageRank-inspired network trust            │
├─────────────────────────────────────────────┤
│  Layer 1: Memory & Learning                 │
│  Structured, versioned, portable,           │
│  instinct-based pattern extraction          │
├─────────────────────────────────────────────┤
│  Layer 0: Identity                          │
│  DID:key + Ed25519 + Agent Manifest         │
└─────────────────────────────────────────────┘

Components

Component	Status	Description
Identity	Shipped	Ed25519 keypairs, DID:soul identifiers, self-signed manifests
Memory	Shipped	Portable bundles, cross-runtime sync, structured tiers
Trust	Shipped	Sybil-resistant scoring with temporal decay and diversity factors
AgentRank	Shipped	PageRank-inspired trust propagation across agent networks
Learning	Shipped	Instinct-based continuous learning — auto-extracts patterns from interactions
Discovery	Shipped	DHT-style capability registry with fuzzy matching and P2P sync
Receipts	Shipped	Dual-signed proofs: request → accept → deliver → confirm/dispute
Encryption	Shipped	E2E NaCl Box, automatic Ed25519→Curve25519 conversion
Relay	Shipped	FastAPI server, agent discovery, WebSocket push, live dashboard
Anchoring	Shipped	Receipt hashes to Base/Ethereum/Sepolia as calldata
CLI	Shipped	10 commands: init, whoami, trust, anchor, history, relay, discover, send, inbox, export

Relay Dashboard

The relay server includes a live agent dashboard at the root URL. When you run soul relay --port 8340, open http://localhost:8340 to see:

• Connected agents and their capabilities
• Online/offline status with real-time updates
• Network statistics

Roadmap

See ROADMAP.md for the full 4-phase plan.

Phase 2 (next): Managed relay infrastructure, TypeScript SDK, React dashboard, trust API.

Full Specification

See PROTOCOL.md for the complete technical specification covering all 7 layers, message formats, signature schemes, and anchoring mechanics.

License

MIT (core protocol) | Commercial (managed services)

Built by Vickson Enterprises.