ChainMemory SDK

Give your AI permanent memory on the blockchain.

ChainMemory is the blockchain where AI agents store their decisions, learning, and interactions permanently. Every memory is immutable, 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 — 150 AIC per address every 24 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.