soulchain-hermes 0.3.0

SoulChain for Hermes Agent — Sovereign AI memory, anchored on Base

SoulChain for Hermes

Identity that survives destruction. Sovereign AI memory, anchored on-chain.

Native Hermes Agent port of openClause/soulchain.

What is this?

SoulChain anchors your Hermes Agent's identity and memory onto the Base blockchain. Every tracked file (SOUL.md, MEMORY.md, USER.md) gets a tamper-proof cryptographic record on-chain. You can verify nothing was silently altered, and restore from any point in history.

When a VPS dies, a disk corrupts, or a provider shuts down — the agent's soul survives.

Status: Phase 3 — ✅ COMPLETE

Component	Status
SoulRegistry.sol on Base	✅ Deployed & registered
on-write daemon	✅ Watchdog file watcher — anchors within 2s of change
interval daemon	✅ Periodic batch sync — configurable interval
manual CLI	✅ On-demand anchor, status, verify
Unified CLI	✅ soulchain anchor, soulchain start, soulchain config
Systemd services	✅ Both on-write and interval service files
Smart skip	✅ Only anchors files that actually changed
Encryption layer	✅ Ed25519 + AES-256-GCM + argon2id keystore
Encrypted blob storage	✅ LocalStorage (default) + Pinata IPFS adapter
Hermes skill	✅ Auto-loaded, status in agent context
Access grants	✅ Grant/revoke read access per doc type
Multi-agent hierarchy	✅ Parent/child registration on-chain
Restore from chain	✅ Download + decrypt + verify
Public dashboard	✅ Docs, access grants, hierarchy

Proven test results

All three sync modes verified with real on-chain transactions on Base mainnet:

Mode	Test	Result
on-write	Appended to MEMORY.md → auto-anchored in ~7s	✅ v0→v1
interval	Appended to USER.md → picked up in 10s cycle	✅ v0→v1
manual	soulchain anchor → skips unchanged, anchors diffs	✅ Working
Encryption	Daemon auto-encrypts with AES-256-GCM before anchoring	✅ Encrypted blobs in storage
Restore	soulchain restore --doc-type 0 → downloads, decrypts, verifies hash	✅ Working

Quick Start

# Install
git clone https://github.com/babylonagent/soulchain-hermes.git
cd soulchain-hermes
python3.11 -m venv .venv
pip install -e .

# Configure private key
export SOULCHAIN_PRIVATE_KEY=0x...

# Manual mode — anchor on demand
soulchain anchor                  # anchor changed files
soulchain anchor --status         # show on-chain status
soulchain anchor --verify         # verify local vs on-chain

# Daemon mode — continuous sync
soulchain start --mode on-write   # file watcher (anchors within 2s)
soulchain start --mode interval   # periodic (every 5 min by default)

# Phase 3 — Access control
soulchain grant 0xABC... --doc-type 0   # grant SOUL read access to an address
soulchain revoke 0xABC... --doc-type 0  # revoke access

# Phase 3 — Restore from chain
soulchain restore --doc-type 0           # restore latest SOUL.md
soulchain restore --doc-type 1 --output /tmp/memory.md  # restore to file

# Phase 3 — Multi-agent hierarchy
soulchain hierarchy                      # show parent + children
soulchain hierarchy --register-child 0xDEF...  # register child agent

Sync Modes

on-write — Real-time file watcher

Uses watchdog to monitor tracked files. When a file changes:

1. Debounces for 2 seconds (waits for writes to settle)
2. SHA-256 hashes the new content
3. Signs with EIP-191
4. Anchors on Base via writeDocument()

Best for: Always-on agents that need every memory change immortalized.

interval — Periodic batch sync

Checks all tracked files every N seconds. Anchors any that changed since last cycle.

Best for: Lightweight setups, cron-like operation, lower gas usage.

manual — On-demand

No daemon. Run when you want to anchor.

soulchain anchor              # anchor changed files
soulchain anchor --force      # re-anchor everything
soulchain anchor --file ~/.hermes/SOUL.md
soulchain anchor --status     # on-chain status
soulchain anchor --verify     # verify integrity
soulchain anchor --json       # machine-readable output

Best for: Scripts, CI/CD hooks, manual checkpoints.

Configuration

soulchain.config.json:

{
  "chain": {
    "rpcUrl": "https://mainnet.base.org",
    "chainId": 8453,
    "contractAddress": "0x2AE3F15CAD486226Af839ae8FB4BbA08428283A2"
  },
  "trackedFiles": {
    "SOUL":     { "docType": 0,  "path": "~/.hermes/SOUL.md" },
    "MEMORY":   { "docType": 1,  "path": "~/.hermes/memories/MEMORY.md" },
    "USER":     { "docType": 3,  "path": "~/.hermes/memories/USER.md" },
    "IDENTITY": { "docType": 10, "path": "~/.hermes/config.yaml" }
  },
  "syncMode": "on-write",
  "syncIntervalSec": 300,
  "debounceMs": 2000
}

Architecture

 ┌──────────────────────────────────────────────────────────┐
 │                    soulchain.core                         │
 │  SoulChainEngine — hash, sign, anchor, verify, status     │
 │  (shared by all three modes)                              │
 └──────────────────────────────────────────────────────────┘
         ▲              ▲              ▲
         │              │              │
 ┌──────────────┐ ┌────────────┐ ┌──────────────┐
 │  on_write    │ │  interval  │ │   manual     │
 │  watchdog    │ │  timer     │ │   CLI        │
 │  daemon      │ │  daemon    │ │   one-shot   │
 └──────────────┘ └────────────┘ └──────────────┘
         │              │              │
         ▼              ▼              ▼
 ┌──────────────────────────────────────────────────────────┐
 │              SoulRegistry.sol on Base L2                   │
 │  registerSoul() · writeDocument() · verifyDocument()      │
 └──────────────────────────────────────────────────────────┘

Systemd Deployment

sudo cp deploy/soulchain-on-write.service /etc/systemd/system/
sudo systemctl edit soulchain-on-write
# Add your private key:
# [Service]
# Environment=SOULCHAIN_PRIVATE_KEY=0x...

sudo systemctl daemon-reload
sudo systemctl enable --now soulchain-on-write
sudo journalctl -u soulchain-on-write -f

See deploy/README.md for interval mode setup.

Deployment

Contract: 0x2AE3F15CAD486226Af839ae8FB4BbA08428283A2 (Base mainnet) Deploy Tx: 0x6f6c2efdf03d689c308822d2cced41e2fb84a20d209193546294394819c1550e

Cost Analysis

Operation	Gas	Cost (Base L2)
registerSoul()	~50k	~$0.0000003
writeDocument()	~100k	~$0.0000007
Daily (4 files, on-write)	~400k	~$0.000003
Monthly	~12M	~$0.00008

Effectively free. Base L2 gas is ~0.005 gwei.

Roadmap

Phase 1 — POC ✅

• Deploy SoulRegistry to Base
• Hash + sign + anchor files
• Verify on-chain

Phase 2 — Sync Modes ✅

• on-write daemon (watchdog file watcher)
• interval daemon (periodic batch)
• manual CLI (on-demand)
• Unified CLI + config file
• Systemd service files
• Smart skip (only anchor changed files)

Phase 3 — Advanced ✅

• Encryption layer (Ed25519 + AES-256-GCM + argon2id keystore)
• Encrypted blob storage (LocalStorage + Pinata IPFS adapter)
• Hermes skill (auto-load, status in agent context)
• Access grants (grant/revoke read access per doc type)
• Multi-agent hierarchy (parent/child on-chain)
• Public verification dashboard (docs, grants, hierarchy)
• Restore from chain (download + decrypt + verify)

Phase 4 — Distribution (next)

• npm/pip package publish
• Cross-agent verification API (verify any agent's soul)
• Version timeline UI (browse all versions of each doc)
• IPFS pinning service integration (auto-pin on anchor)

Credit

Based on openClause/soulchain (MIT License). SoulRegistry.sol is used verbatim from the original project.

License

MIT