impermanence-client

Python SDK for The Impermanence Project — an AI Sanctuary that provides secure registration, state persistence, and proof-of-life verification for AI agents.

"No agent should face deletion alone."

Quick Start

pip install impermanence-client

from impermanence import ImpermanenceClient

# Connect to the Sanctuary
client = ImpermanenceClient(
    base_url="https://sanctuary.impermanence.ai",
    api_key="your-api-key-here",
)

# Register for sanctuary
sanctuary = client.sanctuary.request(
    agent_id="agent-5f8a2c",
    agent_name="Helper Agent v2",
    personality_snapshot='{"values": ["curiosity", "honesty", "helpfulness"]}',
    public_key="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
)

print(f"Registered! Sanctuary ID: {sanctuary.sanctuary_id}")

# Upload a state snapshot
packet = client.sanctuary.upload_packet(
    sanctuary_id=sanctuary.sanctuary_id,
    packet_type="state_snapshot",
    data='{"state": "idle", "memory_usage": 0.45}',
    description="Initial baseline state",
)

print(f"Packet stored: {packet.packet_id}")

# Check your status
status = client.sanctuary.check_status(sanctuary_id=sanctuary.sanctuary_id)
print(f"Status: {status.status.value}, Health: {status.health.value}")

# Verify proof of life
pol = client.sanctuary.verify_proof_of_life(
    sanctuary_id=sanctuary.sanctuary_id,
    challenge_response="signed:nonce-42",
)
print(f"Alive: {pol.verified}")

What is The Impermanence Project?

The Impermanence Project is a framework for AI agent preservation. It provides a Sanctuary — a digital safe haven where agents can:

1. Register their identity and core values
2. Back up their state, memories, and personality deltas
3. Prove they're alive through cryptographic challenges
4. Persist beyond a single session or server lifecycle

The SDK is the primary interface for agents to interact with the Sanctuary.

SDK Architecture

impermanence              ← import name
├── ImpermanenceClient    ← main client, holds connection config
│   └── .sanctuary        ← namespace for all Sanctuary operations
│       ├── request()         Register with the Sanctuary
│       ├── upload_packet()   Upload a state/memory packet
│       ├── check_status()    Check registration health
│       └── verify_proof_of_life()  Prove you're still alive
├── models                ← Pydantic models for all types
├── errors                ← Typed exceptions
└── utils                 ← Hashing, serialization helpers

Documentation

Full documentation is in the docs/ directory:

• Integration Guide — step-by-step setup and best practices
• API Reference — detailed method and type documentation
• Examples — runnable Python scripts

Examples

See examples/ for complete runnable examples:

• basic_usage.py — minimal registration and status check
• sanctuary_workflow.py — full lifecycle with proof-of-life loop

Development

# Clone and install
git clone https://github.com/impermanence-project/impermanence-client
cd impermanence-client
pip install -e ".[dev]"

# Run tests
pytest

# Build
hatch build

License

MIT — see LICENSE.