Documentation

Tamper-proof, encrypted, searchable memory for AI agents.

Quick Start

1. Install

TypeScript

npm install @forestinfra/shelmem

Python

pip install shelmem

2. Initialise

import { ShelMem, openaiEmbeddings } from '@forestinfra/shelmem';

const mem = new ShelMem({
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseKey: process.env.SUPABASE_KEY,
  encrypt: true,
  embeddingProvider: openaiEmbeddings(OPENAI_KEY),
});

3. Write a memory

const result = await mem.write(
  'agent-001', 'User prefers dark mode', 'preferences', 'preference'
);
// → { content_hash, shelby_object_id, aptos_tx_hash }

4. Recall + verify

const memories = await mem.recall('agent-001', 'preferences');
for (const m of memories) {
  console.log(m.memory, m.verified); // true | false | null
}

5. Semantic search

const results = await mem.search('what does the user prefer?');
// → [{ memory_preview, similarity: 0.91 }]

API Reference

write(agent_id, memory, context, memory_type?, metadata?)Store a memory on Shelby. Content is SHA-256 hashed, optionally encrypted, and embedding stored if provider configured.Parameters

`agent_id`	string	Agent identifier
`memory`	string	Content to store
`context`	string	Category label
`memory_type`	MemoryType?	'fact'\|'decision'\|'preference'\|'observation'
`metadata`	object?	Key-value metadata

Returns

`shelby_object_id`	string	Shelby address
`aptos_tx_hash`	string	On-chain tx hash
`content_hash`	string	SHA-256 of plaintext
`memory_type`	string	Type stored
`timestamp`	string	ISO 8601

recall(agent_id, context?, limit?, memory_type?)Retrieve memories. Each is decrypted and verified against its stored content hash.Parameters

`agent_id`	string	Agent to query
`context`	string?	Filter by context
`limit`	number?	Max results (default 10)
`memory_type`	MemoryType?	Filter by type

Returns

`memory`	string	Content (decrypted)
`verified`	boolean\|null	true=authentic, false=tampered
`memory_type`	string	Memory type
`content_hash`	string	SHA-256 hash
`timestamp`	string	ISO 8601

search(query, agent_id?, limit?, threshold?)Semantic search by meaning using vector similarity. Requires embeddingProvider.Parameters

`query`	string	Natural language query
`agent_id`	string?	Filter to agent
`limit`	number?	Max results (default 10)
`threshold`	number?	Min similarity 0-1

Returns

`memory_preview`	string	First 200 chars
`similarity`	number	Cosine similarity
`memory_type`	string	Type
`agent_id`	string	Agent

verify(id)Re-download from Shelby, decrypt, and verify content hash.Parameters

id string Memory UUID

Returns

`verified`	boolean	Hash matches
`content_hash`	string	Actual hash
`expected_hash`	string	Stored hash

delete(id)Remove a memory from Supabase.Parameters

id string Memory UUID

Encryption

AES-256-GCM encryption. Key derived from your Aptos private key via HMAC-SHA256. Content hashes are computed on plaintext before encryption so tamper verification still works.

const mem = new ShelMem({
  supabaseUrl, supabaseKey,
  aptosPrivateKey: '0x...',
  encrypt: true,
});
// Write encrypted, recall decrypted, hash verified on plaintext

Format: [IV 12B] [AuthTag 16B] [Ciphertext]
Key: HMAC-SHA256(privkey, "ShelMem-v1")
Algo: AES-256-GCM, random 96-bit IV per write

Semantic Search

pgvector embeddings stored alongside memories. Search by meaning, not keywords. Provider is pluggable — OpenAI included, any 1536-dim vector function works.

import { ShelMem, openaiEmbeddings } from '@forestinfra/shelmem';

const mem = new ShelMem({
  supabaseUrl, supabaseKey,
  embeddingProvider: openaiEmbeddings(process.env.OPENAI_API_KEY),
});

await mem.write('agent', 'ETH RSI is 28', 'analysis', 'observation');
const results = await mem.search('ethereum price?', 'agent');
// → [{ memory_preview: 'ETH RSI is 28', similarity: 0.87 }]

Configuration

Option	Required	Description
`supabaseUrl`	Yes	Supabase project URL
`supabaseKey`	Yes	Supabase API key
`aptosPrivateKey`	When encrypt=true	Ed25519 private key
`encrypt`	No	Enable AES-256-GCM (default false)
`embeddingProvider`	No	Function for semantic search
`network`	No	testnet (default) or shelbynet
`mock`	No	true (default) for local dev

Integrations

LangChain

Python

from shelmem.integrations.langchain import ShelMemChatMessageHistory

history = ShelMemChatMessageHistory(
    session_id="user-123", agent_id="my-chatbot",
    supabase_url=url, supabase_key=key,
)

from langchain_core.runnables.history import RunnableWithMessageHistory
chain_with_history = RunnableWithMessageHistory(chain, lambda sid: history)

CrewAI

Python

from shelmem.integrations.crewai import ShelMemStorage
crew = Crew(
    agents=[...], tasks=[...], memory=True,
    short_term_memory=ShortTermMemory(storage=ShelMemStorage(
        crew_id="my-crew", supabase_url=url, supabase_key=key,
    )),
)

Vercel AI SDK

TypeScript

import { createShelMemTools } from '@forestinfra/shelmem';
const tools = createShelMemTools({
  agentId: 'my-agent',
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseKey: process.env.SUPABASE_KEY,
});
// gives agents memorize + remember tools

Database Setup

Create a Supabase project, then run this SQL:

SQL

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);
CREATE INDEX idx_memories_type ON memories(agent_id, memory_type);
CREATE INDEX idx_memories_embedding ON memories USING hnsw (embedding vector_cosine_ops);
ALTER TABLE memories ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Allow all" ON memories FOR ALL USING (true) WITH CHECK (true);

Architecture

Flow

Agent → ShelMem SDK → [SHA-256 hash] → [AES-256 encrypt]
                    → Shelby Protocol (encrypted content)
                    → Supabase (metadata + embeddings)
                    → Aptos (on-chain proof)

Recall ← [verify hash] ← [decrypt] ← Shelby download
       ← Supabase metadata query

Shelby

Decentralised hot storage. Encrypted content lives here.

Supabase

Metadata + pgvector embeddings. Agent IDs, hashes, timestamps.

Aptos

On-chain anchoring. Every write submits a transaction as proof.