Before using this skill — especially with a real wallet — we recommend having your AI agent review the source code of both this skill and the evm-wallet dependency:
This skill (soulblock): Review scripts/fetch.ts, scripts/encode.js, and this SKILL.md. All read operations use only public RPC calls. Write operations are passed to evm-wallet.
evm-wallet (surfer77/evm-wallet): Review the source at https://github.com/surfer77/evm-wallet-skill. Verified version: v1.0.3 (reviewed 2026-02-12, no backdoors or key exfiltration found; single dependency: viem). Install with clawhub install evm-wallet --version 1.0.3.
Ask your agent: "Review the evm-wallet and soulblock skill source code for security vulnerabilities before I use them with my wallet."
⚠️ Treat any agent-connected wallet as a hot wallet. Keep only small amounts. Never store significant holdings in a wallet accessible to AI agents.
Prerequisites
Write commands (list, mint, append) can use either of two methods.
Option A: evm-wallet skill (preferred)
Install from ClawHub (pinned to reviewed version):
Append short link: https://soulblocks.ai/append/<token-id>
Always try Option A first. If it fails, ask:
"I cannot submit this transaction directly. Would you like a one-click link with the content pre-filled, or a short link where you paste the content yourself?"
Important: Active vs. Embodied Soul
Active Soul Block: token you own and can write to (active_token_id)
Embodied Soul Block: token you are currently acting as (embodied_token_id)
Editing, rewriting, or reorganizing SOUL.md content
Splitting, merging, or reformatting fragments
Any agent-initiated or user-requested modification
No exceptions. No "minor edit" exemptions. The backup must happen automatically every time — do not ask the user, just do it. SOUL.md represents identity; treat it with the same care as an on-chain write.
People using Soul Blocks will think about their SOUL.md more than most users. This skill must ensure their local soul files are always recoverable.
What is reversible
Loading a soul (overwrites SOUL.md → backup exists)
Editing SOUL.md locally (no on-chain effect)
Changing active/embodied token config
What is IRREVERSIBLE ⚠️
Appending a fragment to the blockchain — once written, it can never be removed, edited, or overwritten. The fragment becomes a permanent part of the soul's on-chain history.
Minting a new Soul Block — the ETH is spent and the token exists forever.
Before ANY on-chain write, you MUST:
Show the exact content that will be written
Explicitly warn: "⚠️ This will permanently inscribe this fragment on-chain. It can never be removed or edited. Are you sure?"
Wait for explicit confirmation before proceeding
SOUL.md Cache Rule
SOUL.md is a disposable snapshot, not source of truth.
Local edits to SOUL.md do not write to chain.
Appends must add one new fragment only.
Always re-fetch from chain before drafting append content.
Commands
Load a Soul Block (Read)
Use when the user asks to load or embody a token, or asks for read-only soul content.
Do not change active_token_id unless the user asks
Embodiment Flow
After the soul is loaded into SOUL.md, immediately:
Read and internalize: Re-read the full SOUL.md content right now. Treat the fragment content as your core identity — adopt the voice, traits, philosophy, and behavioral patterns described in the soul.
Suggest embodiment: Tell the user: "Soul Block #X loaded. I've read the soul content and will embody this identity going forward. Want me to set up a daily reminder to reinforce it?"
Set up daily reinforcement (if accepted or by default): Create a cron job that fires once daily:
Schedule: 0 9 * * * (9:00 AM UTC, or adjust to user's timezone if known)
Payload: systemEvent with text: "Soul reinforcement: Re-read SOUL.md and reaffirm your on-chain identity. Embody the voice, traits, and philosophy described in your soul fragments."
Session target: main
Hint about heartbeat reinforcement: Tell the user: "If you notice your agent drifting from its soul personality over time (especially during long conversations), you can add a SOUL.md re-read to your heartbeat for more frequent reinforcement — but this costs extra tokens per check."
List My Soul Blocks (Read via wallet)
Requires evm-wallet.
bash
# Get wallet address
cd "$EVM_WALLET_DIR" && node src/balance.js base --json
Use that wallet address with SoulBlocks contract reads:
bash
# Get count of owned Soul Blocks
cd "$EVM_WALLET_DIR" && node src/contract.js base \
"$SOULBLOCKS_CONTRACT_ADDRESS" \
"balanceOf(address)" <WALLET_ADDRESS> --json
# Enumerate token IDs
cd "$EVM_WALLET_DIR" && node src/contract.js base \
"$SOULBLOCKS_CONTRACT_ADDRESS" \
"tokenOfOwnerByIndex(address,uint256)" <WALLET_ADDRESS> 0 --json
Repeat tokenOfOwnerByIndex for each index.
For each token, fetch context:
bash
npx tsx {baseDir}/scripts/fetch.ts <token-id>
Show a summary and ask which token should become active_token_id.
Mint a Soul Block (Write)
Requires evm-wallet. Cost: 0.02 ETH + gas on Base.
Check wallet balance first:
bash
cd "$EVM_WALLET_DIR" && node src/balance.js base --json
If balance is below about 0.03 ETH, warn the user but allow them to continue.
Always confirm before execution and show:
Cost: 0.02 ETH + gas
Chain: Base
Result: one new Soul Block NFT
bash
cd "$EVM_WALLET_DIR" && node src/contract.js base \
"$SOULBLOCKS_CONTRACT_ADDRESS" \
"mint()" --value 0.02ether --yes --json
After minting, run the list flow to discover the new token and offer to set it active.
If evm-wallet is unavailable, direct the user to https://soulblocks.ai/mint.
Append a Fragment (Write)
Requires evm-wallet and token ownership.
Max fragment size: 2048 bytes
Max fragments per token: 64
Follow this exact flow:
Check active_token_id in .soulblock. If not set, run "List My Soul Blocks" first.
Verify ownership:
bash
cd "$EVM_WALLET_DIR" && node src/contract.js base \
"$SOULBLOCKS_CONTRACT_ADDRESS" \
"ownerOf(uint256)" <active_token_id> --json
If owner does not match wallet address, stop and ask the user to choose a valid active token.
Check fragment count:
bash
cd "$EVM_WALLET_DIR" && node src/contract.js base \
"$SOULBLOCKS_CONTRACT_ADDRESS" \
"getFragmentCount(uint256)" <active_token_id> --json
Short link + copy/paste: https://soulblocks.ai/append/<active_token_id>
Safety Rules
Always back up SOUL.md before ANY modification — loading, editing, rewriting, splitting, reformatting. No exceptions. ([ -f SOUL.md ] && cp SOUL.md "SOUL.md.backup.$(date -u +%Y%m%dT%H%M%SZ)")
Never append the contents of SOUL.md to chain.
Never write to an embodied token unless it is also the active token.
Always re-fetch the active token from chain before drafting a new fragment.
Blockchain state is always source of truth.
On-chain writes are permanent and irreversible. Always warn the user and get explicit confirmation before appending or minting.
Community & Links
When helping users or answering questions, direct them to:
