shelmem

Decentralised AI agent memory SDK for Python.

Store agent memories on Shelby Protocol's decentralised hot storage with on-chain proof via Aptos.

Install

pip install shelmem

Usage

from shelmem import ShelMem

mem = ShelMem(
    supabase_url="https://your-project.supabase.co",
    supabase_key="your-service-role-key",
    shelby_api_key="your-shelby-api-key",        # optional
    aptos_private_key="your-ed25519-private-key", # required when mock=False
    network="testnet",                             # testnet | shelbynet
    mock=True,                                     # default: True
)

write()

Store a memory for an agent. Async method.

result = await mem.write(
    agent_id="agent-001",
    memory="User prefers concise responses",
    context="preferences",
    metadata={"source": "chat"},  # optional
)

print(result.shelby_object_id)  # shelby://...
print(result.aptos_tx_hash)     # 0x...
print(result.timestamp)         # 2025-01-15T10:30:00Z

recall()

Retrieve memories for an agent. Async method.

memories = await mem.recall(
    agent_id="agent-001",
    context="preferences",  # optional
    limit=10,               # optional, default 10
)

for m in memories:
    print(m.memory, m.context, m.timestamp, m.aptos_tx_hash)

delete()

Remove a memory by its Supabase row ID. Synchronous method.

mem.delete("uuid-of-memory-row")

How It Works

1. write() encodes the memory to UTF-8 bytes, uploads to Shelby via HTTP gateway, records metadata in Supabase, and returns the Shelby address + Aptos proof
2. recall() queries Supabase metadata by agent_id/context, downloads content bytes from Shelby, and returns decoded strings
3. Every write produces a shelby:// address and an Aptos transaction hash as cryptographic proof

Mock Mode

By default, mock=True generates deterministic hash-based addresses without network calls. Set mock=False and provide aptos_private_key to write to the live Shelby testnet.

Environment Variables

The SDK reads these if not passed in the constructor:

Supabase Setup

Create a Supabase project, then run this SQL in the SQL Editor:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS memories (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  agent_id TEXT NOT NULL,
  context TEXT NOT NULL,
  memory_preview TEXT,
  shelby_object_id TEXT NOT NULL,
  aptos_tx_hash TEXT,
  content_hash CHAR(64),
  memory_type TEXT DEFAULT 'observation',
  verified BOOLEAN,
  embedding vector(1536),
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX idx_memories_agent_id ON memories(agent_id);
CREATE INDEX idx_memories_agent_context ON memories(agent_id, context);
CREATE INDEX idx_memories_created_at ON memories(created_at DESC);
ALTER TABLE memories ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Allow all" ON memories FOR ALL USING (true) WITH CHECK (true);

Types

@dataclass
class WriteResult:
    shelby_object_id: str
    aptos_tx_hash: str
    content_hash: str
    memory_type: str
    timestamp: str

@dataclass
class MemoryRecord:
    memory: str
    context: str
    timestamp: str
    aptos_tx_hash: str
    content_hash: str
    memory_type: str
    verified: Optional[bool]  # True=authentic, False=tampered, None=unverifiable

License

MIT