Skip to content

Latest commit

 

History

History
377 lines (279 loc) · 9.68 KB

README.md

File metadata and controls

377 lines (279 loc) · 9.68 KB

MemOS 🧠💾

memos.software

🔐 Never lose your AI's memory again! MemOS lets your AI assistant save its memories to the blockchain — permanently, securely, and privately. Think of it like a backup drive for your AI's brain! 🤖✨

📦 Back up → 🔒 Encrypt → ⛓️ Store forever on Arweave → 🔄 Restore anytime

Part of the MemOS Network by 0xRelayer.

Overview 🎯

This skill enables autonomous agents to:

  • 🔐 Encrypt memory content locally using a deterministic key derived from an Ethereum private key
  • 💎 Store encrypted backups permanently on Arweave
  • 🔄 Restore prior memory state with integrity verification
  • 🛡️ Protect against replay/rollback attacks via sequence numbers

The encryption key is derived directly from the ETH private key via HKDF (never stored). Encrypted bundles are versioned with SHA256 checksums and HMAC-signed manifests.

Installation 📥

# Install uv (fast Python package manager, handles PEP 668 gracefully)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Python dependencies
uv pip install --system -r requirements.txt

# Node.js dependencies (for Turbo uploads)
cd scripts/turbo && npm install && cd ../..

Required packages:

  • eth-account — Ethereum address derivation
  • cryptography — ChaCha20Poly1305 AEAD encryption and HKDF
  • @ardrive/turbo-sdk (Node.js) — Arweave uploads via Turbo

Note: uv avoids venv issues and PEP 668 restrictions that block standard pip on many systems.

Configuration ⚙️

Set environment variable:

export ETH_PRIVATE_KEY="0x..."  # Ethereum private key (hex, 32 bytes)

No Arweave wallet or AR tokens needed. Two payment options:

Option 1: Turbo Credits (Default)

Pre-fund at turbo-topup.com or use free tier for small uploads.

Option 2: x402 with Base USDC (Recommended for Agents)

Pay-per-upload micropayments. No pre-funding needed — just USDC on Base (L2).

# Use x402 payments
python scripts/memos.py backup --input memory/ --x402

# Set max USDC per upload (default $1.00)
python scripts/memos.py backup --input memory/ --x402 --x402-max-usdc 0.50

# Use testnet for development
python scripts/memos.py backup --input memory/ --x402 --x402-network base-sepolia

x402 is ideal for autonomous agents because:

  • No account setup or pre-funding required
  • Pay exactly what you use
  • USDC on Base = ~$0.001 gas fees
  • Works with standard ETH private key

Quick Start 🚀

Using the Unified CLI (Recommended)

# Backup memory to Arweave
python scripts/memos.py backup --input memory/

# Restore from Arweave (by tx ID)
python scripts/memos.py restore --tx-id <bundle_tx_id> --out memory/

# Restore latest backup (discovers on Arweave)
python scripts/memos.py restore --latest --out memory/

# Check status
python scripts/memos.py status

# List backup history (local index)
python scripts/memos.py list

Using Individual Scripts

1. Encrypt a memory directory

python scripts/encrypt_pack.py \
  --input memory/ \
  --out /tmp/vault/memory.enc \
  --manifest /tmp/vault/manifest.json

2. Upload to Arweave

python scripts/arweave_upload.py \
  --bundle /tmp/vault/memory.enc \
  --manifest /tmp/vault/manifest.json

3. Download from Arweave (later)

python scripts/arweave_download.py \
  --tx-id <arweave_tx_id> \
  --out /tmp/vault/downloaded.enc \
  --manifest /tmp/vault/manifest.json

4. Decrypt and restore

python scripts/decrypt_unpack.py \
  --bundle /tmp/vault/downloaded.enc \
  --manifest /tmp/vault/manifest.json \
  --out memory_restored/

Scripts 📜

memos.py — Unified CLI

The recommended way to use MemOS. Combines all operations into a single command.

python scripts/memos.py <command> [options]

Commands:

  • backup — Encrypt and upload memory to Arweave
  • restore — Download and decrypt from Arweave
  • list — Show backup history
  • status — Check configuration and wallet balance
  • init — Set up MemOS (generate wallet, create directories)

arweave_wallet.py — Wallet Management

Generate and manage Arweave wallets.

# Generate new wallet
python scripts/arweave_wallet.py --generate --out wallet.json

# Check balance
python scripts/arweave_wallet.py --balance --wallet wallet.json

# Get address
python scripts/arweave_wallet.py --address --wallet wallet.json

encrypt_pack.py — Pack and encrypt

Creates an encrypted bundle from a directory.

python scripts/encrypt_pack.py \
  --input <directory> \
  --out <bundle_path> \
  --manifest <manifest_path>

Output:

{
  "ok": true,
  "bundle": "/path/to/bundle.enc",
  "manifest": "/path/to/manifest.json",
  "bundle_sha256": "abc123...",
  "eth_address": "0x...",
  "sequence": 1,
  "files": 42
}

arweave_upload.py — Upload to Arweave

Uploads encrypted bundle to Arweave with required tags.

python scripts/arweave_upload.py \
  --bundle <bundle_path> \
  --manifest <manifest_path> \
  [--wallet <jwk_path>] \
  [--dry-run]

Options:

  • --wallet — Arweave JWK wallet path (or use ARWEAVE_JWK_PATH env var)
  • --dry-run — Check balance and estimate cost without uploading

Output:

{
  "ok": true,
  "tx_id": "abc123...",
  "bundle_size": 12345,
  "estimated_cost_ar": 0.0001,
  "arweave_url": "https://arweave.net/abc123..."
}

arweave_download.py — Download from Arweave

Downloads bundle from Arweave with checksum verification.

python scripts/arweave_download.py \
  --tx-id <transaction_id> \
  --out <output_path> \
  [--manifest <manifest_path>] \
  [--expected-sha256 <hash>] \
  [--status-only]

Options:

  • --manifest — Read expected checksum from manifest
  • --expected-sha256 — Provide checksum directly
  • --status-only — Check transaction status without downloading

decrypt_unpack.py — Decrypt and restore

Decrypts bundle and extracts files.

python scripts/decrypt_unpack.py \
  --bundle <bundle_path> \
  --manifest <manifest_path> \
  --out <output_directory> \
  [--force] \
  [--ignore-rollback]

Options:

  • --force — Overwrite existing output directory
  • --ignore-rollback — Bypass rollback protection (dangerous)

How It Works 🔧

Key Derivation

The encryption key is derived deterministically from the ETH private key:

  1. ETH private key bytes (32 bytes) are extracted
  2. HKDF-SHA256 derives a 32-byte encryption key
  3. Salt: memos-v2 (versioned for key rotation)
  4. Info: memos:encryption:<eth_address>

This ensures the same private key always produces the same encryption key.

Encryption

  • Cipher: ChaCha20Poly1305 (AEAD)
  • Nonce: 12 random bytes (prepended to ciphertext)
  • AAD: Version, ETH address, and timestamp bound to ciphertext
  • Plaintext: Gzipped tar archive of memory directory

Manifest

The manifest JSON records:

  • Sequence number (monotonically increasing)
  • ETH address that created the backup
  • SHA256 checksum of encrypted bundle
  • HMAC signature over manifest contents
  • Arweave transaction ID (after upload)
  • File inventory

Replay Protection

  • Each backup increments a sequence number
  • Local index tracks highest known sequence per address
  • Restore rejects manifests with sequence < known sequence
  • Use --ignore-rollback for emergency recovery (dangerous)

Arweave Tags

Uploaded bundles include these tags (privacy-safe):

  • App-Name: MEMOS
  • App-Version: 2.1
  • Content-Type: application/octet-stream
  • Unix-Time: <timestamp>
  • Manifest-SHA256: <hash>
  • Bundle-SHA256: <hash>

Privacy: ETH address, filenames, and identifying info are NOT included in tags.

Security 🛡️

Private Key Handling

  • Keys passed via ETH_PRIVATE_KEY environment variable only
  • Never passed via CLI (prevents exposure in shell history/ps)
  • Never logged or written to files
  • Rotate keys if compromise is suspected

Path Traversal Protection

The decrypt script blocks:

  • Absolute paths in tar archives
  • .. path components
  • Symlinks and hardlinks
  • Paths that escape the destination directory

Checksum Verification

  • Bundle SHA256 verified before decryption
  • AAD hash verified during decryption
  • Manifest HMAC signature verified
  • File count verified after extraction

Testing 🧪

pytest tests/ -v

Tests cover:

  • Encrypt/decrypt roundtrip
  • Tampered bundle detection
  • Wrong key rejection
  • Path traversal blocking
  • Key derivation determinism

Files 📁

scripts/
  encrypt_pack.py      # Pack + encrypt directory
  decrypt_unpack.py    # Decrypt + restore bundle
  arweave_upload.py    # Upload to Arweave
  arweave_download.py  # Download from Arweave
tests/
  test_roundtrip.py    # Encryption roundtrip tests
  test_integrity.py    # Tamper detection tests
  test_security.py     # Security tests
  test_key_derivation.py # Key derivation tests
references/
  ops-checklist.md     # Operational guardrails
  secret-handling.md   # Secret management guide
SKILL.md               # OpenClaw skill definition
README.md              # This file
requirements.txt       # Pinned dependencies

Dependencies 📦

Package Version Purpose
eth-account 0.11.3 ETH address derivation
cryptography 42.0.5 HKDF, ChaCha20Poly1305
arweave-python-client 1.0.19 Arweave uploads
pytest 8.0.0 Testing

References 📚

License 📄

Part of the MemOS Network. See repository root for license.