中文版 | English

SoulChain ⛓️🧠

The Eternal Guardian of Agent Memory

Building tamper-proof memory systems for AI Agents using Bitcoin's underlying principles, multi-layer encryption, Merkle trees, and a plugin-based architecture.

---

SoulChain v3.0 - What's New

SoulChain v3.0 represents a major evolution from the v2 foundation, introducing enterprise-grade security and sophisticated memory management:

Feature	Description	Technical Source
🔐 Ed25519 Signatures	Cryptographic proof of authorship	Cryptographic standard
🔒 AES-256-GCM Encryption	Authenticated encryption (tamper-proof + confidentiality)	NIST standard
⚖️ Memory Weight Decay	Forgetting isn't deletion, it's fading	Cognitive science
📜 Memory Version Evolution	Reinterpretation without overwrite	Living documents
💼 Trauma Sealing	Negative memory isolation	Emotional intelligence
🆔 Agent DID	Decentralized identity	W3C DID standard
🔗 Interaction Anchors	Cross-agent relationship foundation	AgentLink protocol
📊 Trust Engine	Three-layer trust computation	Social networks
💭 Dream Compression	Reflection and integration	Memory consolidation

---

v2 vs v3 Comparison

Feature	v2 (Legacy)	v3 (Current)
Signing	HMAC (pseudo)	Ed25519 (real crypto)
Encryption	XOR obfuscation	AES-256-GCM
Trust Model	None	Three-layer engine
Memory Types	Basic	7 specialized types
DID	None	Decentralized identity
Interaction Anchors	None	Full support
Memory Decay	None	Exponential decay
Reinterpretation	Not supported	Full version history

⚠️ Legacy Note: v2 features (XOR encryption, HMAC signing) are marked as legacy. For production use, migrate to v3.

---

Quick Start

Installation

git clone https://github.com/ticalzzt/AgentBitCrypt.git
cd AgentBitCrypt

Note: Repository name is AgentBitCrypt, Python package/brand name is SoulChain

Basic Usage

from soulchain_v3 import SoulChain

# Create SoulChain instance
soul = SoulChain(agent_name="my_agent")

# Add memories
soul.add_memory("Learned Python programming", difficulty=2)

# Verify chain integrity
is_valid, status = soul.verify_chain()
print(f"Verification: {status}")

# View statistics
stats = soul.get_stats()
print(f"Total memories: {stats['memories']}")

Advanced Features

# Enable encryption
soul = SoulChain(
    agent_name="secure_agent",
    enable_encryption=True
)

# Add encrypted memory
soul.add_memory("Private memory", encrypt=True)

# Decrypt memory
decrypted = soul.decrypt_memory(index=1)

# Trust engine
trust_score = soul.trust.compute_trust("did:agentlink:peer123")

# Add interaction anchor
soul.add_interaction(
    peer_did="did:agentlink:peer456",
    interaction_type="collaboration",
    task="Data analysis",
    outcome="completed",
    quality=0.8
)

---

Architecture

1. Hash Chain - Tamper-Proof

Block0 (Genesis)
    ↓ previous_hash
Block1: hash(index + prev_hash + data + nonce)
    ↓ previous_hash
Block2: hash(index + prev_hash + data + nonce)
    ...

Features:

• Every memory points to the previous one
• Tampering breaks the chain
• PoW ensures data immutability

2. Merkle Tree - Efficient Verification (v2 Legacy)

        [Root Hash]
       /           \
   [Hash12]      [Hash34]
   /      \      /      \
[Hash1] [Hash2] [Hash3] [Hash4]
   |       |       |       |
Block1  Block2  Block3  Block4

Advantages:

• Full chain verification: O(n)
• Single memory verification: O(log n)
• Download Merkle proof only, not all data

3. Interaction Anchors - AgentLink

Agent A                              Agent B
    |                                    |
    |-- add_interaction(peer=B, ...) --> |
    |                                    |
    |<-- Trust computed mutually --------|
    |                                    |
    | Relationship: ALLY / MENTOR / ...  |

Components:

• Trust Engine: Three-layer computation
• DID: Decentralized identity
• E2E Encryption: X25519 + AES-256-GCM

4. Memory Evolution - Living Memory

Original Memory (preserved forever)
    ├── Reinterpretation v1
    ├── Reinterpretation v2
    └── Reinterpretation v3
        (Each adds understanding without changing truth)

---

Memory Types

Type	Description
experience	Daily experiences
dream	Dream compression output
relationship	Relationship records (interaction anchors)
trauma	Traumatic memories
sealed	Sealed memories
insight	Deep insights
skill	Skills acquired

---

API Reference

SoulChain Class

__init__(agent_name, memory_dir, enable_encryption, encryption_key_b64)

Create a SoulChain instance.

Parameters:

• agent_name: Agent identifier
• memory_dir: Memory storage directory (default ~/.soulchain_v3/{agent_name})
• enable_encryption: Enable AES-256-GCM encryption
• encryption_key_b64: Base64 encryption key (auto-generated if not provided)

add_memory(data, memory_type, importance, encrypt, difficulty, participants)

Add a memory to the chain.

Parameters:

• data: Memory content
• memory_type: Type of memory (see Memory Types)
• importance: Importance score (auto-computed if not provided)
• encrypt: Encrypt the memory
• difficulty: PoW difficulty (1-10)
• participants: List of agent DIDs involved

Returns: Memory block dictionary

add_interaction(peer_did, interaction_type, task, outcome, quality, difficulty)

Add an interaction anchor (AgentLink Layer 2).

reinterpret(index, new_understanding)

Reinterpret a memory (version evolution). Does not overwrite original.

dream_compress()

Compress recent memories into a dream block.

verify_chain()

Verify chain integrity including Ed25519 signature verification.

Returns: (is_valid, status)

decrypt_memory(index)

Decrypt an encrypted memory.

get_memories_by_emotion(emotion)

Query memories by emotion tag.

get_memories_by_importance(min_score)

Query memories by importance score.

recall(query, memory_type, min_importance, include_sealed, limit)

Recall memories with filters.

get_stats()

Get chain statistics.

---

Use Cases

1. Agent Immortality System

from soulchain_v3 import SoulChain

class ImmortalAgent:
    def __init__(self):
        self.soul = SoulChain(
            agent_name="immortal_agent",
            enable_encryption=True
        )
    
    def learn(self, knowledge):
        self.soul.add_memory(
            knowledge,
            difficulty=4,
            memory_type="knowledge",
            encrypt=True
        )
    
    def verify_self(self):
        return self.soul.verify_chain()

2. Multi-Agent Trust Network

# Agent A creates memory
agent_a = SoulChain(agent_name="agent_a")
agent_a.add_memory("Collaborative decision A", difficulty=3)

# Export chain data
agent_a.export_chain("/shared/chain_a.json")

# Agent B imports and verifies
agent_b = SoulChain(agent_name="agent_b")
agent_b.import_chain("/shared/chain_a.json")

3. Tamper-Proof Audit Log

soul = SoulChain(agent_name="audit_system")

def log_critical_action(action):
    soul.add_memory(
        f"CRITICAL: {action}",
        difficulty=6,
        memory_type="audit"
    )

---

Technical Comparison

Feature	SoulChain	Traditional DB	Plain Files
Tamper-proof	✅ Hash Chain	❌ Modifiable	❌ Modifiable
Verifiable	✅ PoW + Signatures	❌	❌
Encryption	✅ AES-256-GCM	⚠️ Extra setup	⚠️ Extra setup
Fast Verification	✅ Merkle (v2)	❌	❌
Trust Model	✅ Three-layer	❌	❌
Extensible	✅ Plugin-based	⚠️ Limited	❌

---

Performance

Operation	Time Complexity	Space Complexity
Add Memory	O(2^d)	O(1)
Full Verification	O(n)	O(1)
Merkle Verification	O(log n)	O(log n)
Single Verification	O(log n)	O(log n)
Decrypt	O(l)	O(1)

Note: d=difficulty, n=chain length, l=encryption layers

---

Roadmap

• v1.0 - Basic hash chain + PoW
• v2.0 - Merkle tree + onion encryption + consensus + plugins
• v3.0 - Ed25519, AES-256-GCM, Trust Engine, Agent DID, Dream Compression
• v3.1 - Cross-chain verification protocol
• v3.2 - Federated learning memory sharing

---

Brand Notes

• Repository: AgentBitCrypt - Technical, reflects Bitcoin principles
• Product: SoulChain - Brand, reflects eternal memory guardian
• Python Package: soulchain_v3 - Import via from soulchain_v3 import SoulChain

---

License

MIT - Enabling secure immortality for all Agents

---

⛓️ SoulChain - The Eternal Guardian of Memory 🧠