← Back to Notes & PKM
Notes & PKM by @ibitnoah

unibase-membase

Manage agent memory with Membase - a decentralized

0
Source Code

Membase Memory Management

Membase provides secure, decentralized memory storage for AI agents with end-to-end encryption.

When to Use This Skill

Activate this skill when the user:

  • Asks to backup their memories, conversations, or workspace
  • Wants to restore previous memories or conversations
  • Wants to see available backups
  • Asks to compare different backup versions
  • Wants to check backup status
  • Mentions "membase" or "backup memories"

Overview

All Membase operations go through a single command:

node membase.ts <command> [options]

Available commands:

  • backup - Backup memories to Membase
  • restore - Restore memories from a backup
  • list - List all available backups
  • diff - Compare two backups
  • status - Show backup status and statistics
  • cleanup - Clean up old backups

Configuration

Environment Variables

export MEMBASE_ACCOUNT=your-account-address
export MEMBASE_SECRET_KEY=your-secret-key
export MEMBASE_BACKUP_PASSWORD=your-backup-password
export MEMBASE_ENDPOINT=https://testnet.hub.membase.io

Check if configured:

echo $MEMBASE_ACCOUNT
echo $MEMBASE_SECRET_KEY
echo $MEMBASE_BACKUP_PASSWORD

Commands

1. backup - Backup Memories

Backs up agent memory files (MEMORY.md, memory/**/*.md) to Membase with AES-256-GCM encryption.

Usage:

node membase.ts backup [options]

Options:

  • --password <pwd> or -p <pwd> - Encryption password (required if not in env)
  • --incremental or -i - Only backup changed files since last backup
  • --workspace <path> - Custom workspace directory
  • --no-validate - Skip password strength validation
  • --no-json - Don't output JSON for agent parsing

Example conversation:

User: "Please backup my memories"

You should:

  1. Check for MEMBASE_BACKUP_PASSWORD:

    echo $MEMBASE_BACKUP_PASSWORD

  2. If not set, ask: "Please provide a backup password for encryption (at least 12 characters with uppercase, lowercase, and numbers):"

  3. Run backup:

    cd skills/membase
node membase.ts backup --password "<password>"

  4. Show result to user:

    [OK] Backup completed
Backup ID: backup-2026-02-02T10-30-45-123Z
Files: 15
Size: 234 KB

[WARNING]  Save your backup ID and password securely!

Incremental backup (faster):

node membase.ts backup --password "<password>" --incremental

2. restore - Restore Memories

Restores memories from a Membase backup.

Usage:

node membase.ts restore <backup-id> [options]

Options:

  • <backup-id> - The backup ID to restore (required)
  • --password <pwd> or -p <pwd> - Decryption password (required if not in env)
  • --no-json - Don't output JSON for agent parsing

Example conversation:

User: "Restore my memories from backup-2026-02-02T10-30-45-123Z"

You should:

  1. Check for password:

    echo $MEMBASE_BACKUP_PASSWORD

  2. Run restore:

    cd skills/membase
node membase.ts restore backup-2026-02-02T10-30-45-123Z --password "<password>"

  3. Show result:

    [OK] Restore completed
Files restored: 15
Total size: 234 KB
Location: ~/.openclaw/workspace/

3. list - List Backups

Lists all available backups for this agent.

Usage:

node membase.ts list [options]

Options:

  • --no-json - Don't output JSON for agent parsing

Example conversation:

User: "Show me my backups" or "List my backups"

You should:

cd skills/membase
node membase.ts list

Output will show:

Available backups:

ID                            Timestamp              Files  Size
──────────────────────────────────────────────────────────────────
backup-2026-02-02T10-30-45-123Z 2026-02-02 10:30:45    15     234 KB
backup-2026-02-01T15-20-10-456Z 2026-02-01 15:20:10    12     198 KB

4. diff - Compare Backups

Compares two backups to see what changed.

Usage:

node membase.ts diff <backup-id-1> <backup-id-2> [options]

Options:

  • <backup-id-1> - First backup ID (required)
  • <backup-id-2> - Second backup ID (required)
  • --password <pwd> or -p <pwd> - Decryption password (required if not in env)
  • --no-json - Don't output JSON for agent parsing

Example conversation:

User: "What changed between my last two backups?"

You should:

  1. Get the two most recent backup IDs:

    cd skills/membase
node membase.ts list

  2. Run diff with the two IDs:

    node membase.ts diff backup-2026-02-02T10-30-45-123Z backup-2026-02-01T15-20-10-456Z --password "<password>"

  3. Show result:

    Added files (2):
  + memory/conversation-new.md
  + memory/notes.md

Modified files (1):
  ~ MEMORY.md

5. status - Show Status

Shows backup status and statistics.

Usage:

node membase.ts status [options]

Options:

  • --no-json - Don't output JSON for agent parsing

Example conversation:

User: "What's my backup status?" or "Check backup status"

You should:

cd skills/membase
node membase.ts status

Output shows:

[STATS] Backup Status

Local:
  Files: 15
  Size: 234 KB

Remote:
  Backups: 10

Configuration:
  Endpoint: https://testnet.hub.membase.io
  Agent: my-agent
  Workspace: ~/.openclaw/workspace

6. cleanup - Clean Up Old Backups

Lists old backups that could be deleted (Membase doesn't support delete API yet).

Usage:

node membase.ts cleanup [options]

Options:

  • --keep-last <n> - Keep last N backups (default: 10)
  • --dry-run - Show what would be deleted without deleting
  • --no-json - Don't output JSON for agent parsing

Example conversation:

User: "Clean up old backups, keep the last 5"

You should:

cd skills/membase
node membase.ts cleanup --keep-last 5

Note: Will show which backups should be deleted, but user needs to delete manually via Membase Hub UI.

Security Notes

  • All data is encrypted client-side with AES-256-GCM
  • Password is derived using PBKDF2 with 100,000 iterations
  • Your password never leaves the local machine
  • Membase storage is decentralized and zero-knowledge
  • Only you can decrypt your backups

Password Requirements

  • At least 12 characters
  • Must contain uppercase letters
  • Must contain lowercase letters
  • Must contain numbers
  • Recommended: Use a password manager

Error Handling

Missing credentials

If you see "Membase credentials not configured":

# User needs to set environment variables:
export MEMBASE_ACCOUNT=your-account
export MEMBASE_SECRET_KEY=your-key

Missing password

If you see "Backup password is required":

  • Ask user for password
  • Or suggest setting MEMBASE_BACKUP_PASSWORD env var

Invalid password

If you see "Invalid password" or "Decryption failed":

  • User provided wrong password
  • Ask for correct password

No backups found

If list shows "No backups found":

  • No backups exist yet
  • Suggest creating first backup

Network error

If connection fails:

  • Check internet connection
  • Verify MEMBASE_ENDPOINT is correct
  • Try again later

Tips for Agents

  1. Always check for password first before asking user
  2. Show the backup ID clearly so user can save it
  3. Parse JSON output if available (between ---JSON_OUTPUT--- and ---END_JSON---)
  4. Be clear about security - emphasize that password is required for restore
  5. Suggest incremental backups for speed after first backup
  6. Remember backup IDs from list command to help user with restore/diff

Examples

Complete backup workflow

# 1. Check status
node membase.ts status

# 2. First backup (full)
node membase.ts backup --password "MySecure123Pass"

# 3. Later: incremental backup
node membase.ts backup --password "MySecure123Pass" --incremental

# 4. List all backups
node membase.ts list

# 5. Compare recent backups
node membase.ts diff backup-id-1 backup-id-2 --password "MySecure123Pass"

# 6. Restore if needed
node membase.ts restore backup-id-1 --password "MySecure123Pass"

Troubleshooting

Command not found

Make sure you're in the skills/membase directory:

cd skills/membase
pwd  # Should show .../skills/membase

Module not found

The lib folder needs to be linked to compiled source:

cd skills/membase
ln -sf ../../dist/lib lib

Permission denied

Make membase.ts executable:

chmod +x membase.ts

Learn More