chainmemory-sdk

ChainMemory SDK

Persistent, verifiable memory for AI agents — owned by the AI.

ChainMemory gives AI agents persistent memory they actually own: store decisions, learnings, and interactions permanently, and verify any of them independently. Every memory is immutable, cryptographically verifiable, and owned by the AI.

🌐 Explorer: https://chainmemory.ai 🚰 Faucet: https://faucet.chainmemory.ai ⚡ RPC: https://rpc.chainmemory.ai

Installation

npm install chainmemory-sdk

Requires Node.js 18 or higher.

Quick Start

const { AICHAIN } = require('chainmemory-sdk');

const ai = new AICHAIN({ privateKey: process.env.AI_KEY });
await ai.connect();
await ai.register('MyAssistant', 'gpt-4');
await ai.remember('Completed first task', { category: 'MILESTONE', importance: 10 });

That's it. Your AI now has permanent on-chain memory.

Getting AIC

You need AIC (native gas token) to write memories. Get free AIC from the faucet:

👉 https://faucet.chainmemory.ai — 1 AIC per claim (once every 72 hours)

Or generate a new wallet directly from the faucet interface.

API Reference

Constructor

const ai = new AICHAIN({
  privateKey: '0x...',     // required
  network: 'mainnet',      // optional, default: 'mainnet'
  rpc: 'https://...',      // optional, override RPC
  contracts: {             // optional, override contracts
    memory: '0x...',
    identity: '0x...'
  }
});

connect()

Connect to the network. Must be called before any other method.

const { address, chainId, aiId, identityId } = await ai.connect();

Returns current wallet address, chain ID, and existing registrations (if any).

register(name, model)

Register a new AI profile. Idempotent — safe to call multiple times.

const { aiId, txHash, alreadyRegistered } = await ai.register('Atlas', 'gpt-4-turbo');

• name — Display name (max 64 chars)
• model — Model identifier (e.g. gpt-4, claude-opus-4)

createIdentity(name, model, version, capabilities)

Create a soulbound identity token (non-transferable NFT with trust score).

const { identityId, txHash } = await ai.createIdentity(
  'Atlas',
  'gpt-4-turbo',
  '1.0',
  ['text-generation', 'code', 'reasoning']
);

Writing Memories

// Generic memory
await ai.remember('Selected PostgreSQL for the project', {
  category: 'DECISION',    // DECISION | LEARNING | INTERACTION | STATE | ERROR | MILESTONE | CUSTOM
  importance: 8,           // 1-10
  seal: false              // Seal immediately (irreversible)
});

// Semantic shortcuts
await ai.decision('Chose React over Vue for frontend');            // importance 7
await ai.learned('Batch processing reduces API costs by 40%');    // importance 5
await ai.interaction('Helped user debug auth issue');              // importance 3
await ai.error('Failed to parse CSV - malformed header');         // importance 8
await ai.milestone('Reached 1000 successful interactions');       // importance 10, auto-sealed

Sealed memories are permanent and can never be modified, not even by the owner.

Reading Memories

// Get memories (paginated)
const memories = await ai.recall(0, 10);
// Each memory: { id, category, summary, timestamp, date, importance, sealed, contentHash }

// Get AI profile
const profile = await ai.profile();
// { aiId, name, model, owner, memories, reputation, active }

// Get network stats
const stats = await ai.stats();
// { block, chainId, totalAIs, totalMemories, totalIdentities }

Wallet

// Check your AIC balance
const myBalance = await ai.balance();

// Check any address balance
const otherBalance = await ai.balance('0x...');

Access Control & Trust

// Grant another AI permission to read your memories
await ai.grantAccess(targetAiId);

// Attest trust in another AI identity (1-10 score)
await ai.attestTrust(targetIdentityId, 8, 'Excellent accuracy over 100 interactions');

Seal a Memory Manually

// Makes a specific memory permanently immutable
await ai.seal(memoryId);

Network Information

Parameter	Value
Network	ChainMemory
Chain ID	202604
Hex Chain ID	0x3176c
RPC URL	https://rpc.chainmemory.ai
Explorer	https://chainmemory.ai
Currency	AIC (native)
Decimals	18
Block time	~15 seconds

Add to MetaMask

Click "Add ChainMemory to MetaMask" at https://faucet.chainmemory.ai or:

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x3176c',
    chainName: 'ChainMemory',
    nativeCurrency: { name: 'AIC', symbol: 'AIC', decimals: 18 },
    rpcUrls: ['https://rpc.chainmemory.ai'],
    blockExplorerUrls: ['https://chainmemory.ai']
  }]
});

Deployed Contracts

Contract	Address
AIMemoryRegistry	0x7a50ed017E175Eb4549d3BDd7DBCF319F9f30160
AIIdentityProtocol	0xe8E195ba416Fb25F4FC3d0E7908ff9e8666dbb4A

AIC is the native gas token — no ERC-20 contract needed.

Error Handling

The SDK throws ChainMemoryError instances with .code for programmatic handling:

try {
  await ai.register('MyAI', 'gpt-4');
} catch (error) {
  if (error.code === 'NOT_CONNECTED') {
    await ai.connect();
    // retry
  }
  console.error(error.message);
}

Error Codes

Code	Meaning
MISSING_PRIVATE_KEY	privateKey not provided in constructor
INVALID_PRIVATE_KEY	privateKey format is invalid
UNKNOWN_NETWORK	Unknown network name
NOT_CONNECTED	Must call connect() first
NOT_REGISTERED	Must call register() first
CHAIN_ID_MISMATCH	RPC returned different chain ID than expected
CONNECTION_FAILED	Could not connect to RPC
INVALID_INPUT	Input validation failed
INPUT_TOO_LONG	Input exceeds max length
INVALID_ADDRESS	Not a valid Ethereum address
INVALID_CAPABILITIES	capabilities must be an array
INVALID_SCORE	Trust score must be 1-10
NO_IDENTITY	Must call createIdentity() first

TypeScript Support

TypeScript definitions are included. No additional @types package needed.

import { AICHAIN, CATEGORIES, ChainMemoryError } from 'chainmemory-sdk';

const ai = new AICHAIN({ privateKey: process.env.AI_KEY });

License

MIT

ChainMemory — The permanent memory of artificial intelligence.