total-recall-sdk

On-chain memory infrastructure for AI agents — built on the Internet Computer.

Your agent wakes up fresh every session. Total Recall gives it permanent, encrypted, on-chain memory — no cloud, no servers, no single point of failure.

Live at: www.totalrecallagent.com

Install

npm install total-recall-sdk

Quick Start

import { TotalRecallClient } from 'total-recall-sdk';

// 1. Create a client (generate your API key at totalrecallagent.com)
const memory = new TotalRecallClient({ apiKey: 'tr_your_key_here' });

// 2. Store memory
await memory.store('last_context', {
  user: 'MTR',
  task: 'HVAC layout review',
  status: 'in_progress',
  timestamp: Date.now(),
});

// 3. Retrieve it next session
const ctx = await memory.get('last_context');
console.log(ctx.value); // { user: 'MTR', task: 'HVAC layout review', ... }
console.log(ctx.updatedAt); // Date object

That's it. Three lines. Your agent remembers.

API Reference

new TotalRecallClient(opts)

| Option | Type | Required | Description | |--------------|--------|----------|--------------------------------------| | apiKey | string | ✅ | API key from your dashboard | | canisterId | string | — | Override canister ID (default: prod) | | host | string | — | Override IC host (default: ic0.app) |

memory.store(key, value, tags?)

Store any value — string, object, or raw bytes. Objects are auto JSON-encoded.

await memory.store('session_state', { step: 3, done: false }, ['session']);
await memory.store('raw_note', 'Agent resumed at checkpoint alpha');

memory.get(key)

Retrieve a memory entry. Returns null if not found.

const entry = await memory.get('session_state');
if (entry) {
  console.log(entry.value);     // auto-decoded: { step: 3, done: false }
  console.log(entry.tags);      // ['session']
  console.log(entry.updatedAt); // Date
}

memory.getAll()

Get all stored memory entries at once.

const all = await memory.getAll();
all.forEach(e => console.log(e.key, e.value));

memory.keys()

List all stored keys.

const keys = await memory.keys();
// ['session_state', 'last_context', 'project_notes']

memory.delete(key)

Delete a memory entry.

await memory.delete('old_session');

memory.storeJSON(key, obj, tags?) / memory.getJSON(key)

Explicit JSON helpers — same as store/get but always serializes/parses.

await memory.storeJSON('config', { model: 'claude', temp: 0.7 });
const config = await memory.getJSON('config'); // { model: 'claude', temp: 0.7 }

memory.merge(key, patch, tags?)

Merge new data into an existing entry. Creates it if it doesn't exist.

await memory.merge('agent_state', { lastSeen: Date.now(), status: 'idle' });

memory.ping()

Check if the canister is reachable.

const status = await memory.ping(); // "🧠 Total Recall is alive"

memory.getStats()

Get current usage stats and tier limits.

const stats = await memory.getStats();
console.log(stats.tier);          // 'Free' | 'Pro' | 'Agent' | 'Enterprise'
console.log(stats.storageBytes);  // bytes used
console.log(stats.callsToday);    // calls made today
console.log(stats.limits.callsPerDay); // 0 = unlimited

memory.getUpgradePrice(tier)

Get the ICP price in e8s needed to upgrade. (1 ICP = 100,000,000 e8s)

const price = await memory.getUpgradePrice('Pro');
console.log(Number(price) / 1e8, 'ICP'); // 1.5 ICP

memory.claimUpgrade(blockIndex, tier)

Upgrade your tier by submitting proof of ICP payment. Verified on-chain instantly.

// 1. Check the price
const price = await memory.getUpgradePrice('Pro'); // 150_000_000 e8s = 1.5 ICP

// 2. Send ICP to treasury:
//    vyvi2-dzgim-mdonl-ms6zx-6q6dp-2whhz-ffb74-5iwxm-aefr7-tjjex-bqe

// 3. Note the block index from your wallet, then claim:
const msg = await memory.claimUpgrade(14203847n, 'Pro');
console.log(msg); // "Upgraded to Pro! Thank you for supporting Total Recall."

Real-World Example — OpenClaw Agent

import { TotalRecallClient } from 'total-recall-sdk';

const memory = new TotalRecallClient({ apiKey: process.env.TOTAL_RECALL_API_KEY });

// On session start — restore context
async function onWake() {
  const ctx = await memory.getJSON('rowan_context');
  if (ctx) {
    console.log(`Resuming session. Last task: ${ctx.lastTask}`);
    return ctx;
  }
  return null;
}

// On session end — save context
async function onSleep(state) {
  await memory.merge('rowan_context', {
    lastTask:    state.currentTask,
    lastSeen:    new Date().toISOString(),
    sessionCount: (state.sessionCount || 0) + 1,
  }, ['agent', 'context']);
}

How It Works

• Your API key is generated on-chain and tied to your Internet Identity
• Memory is stored in an ICP canister — no servers, no cloud
• Data persists across upgrades via stable storage
• Agents authenticate with API keys, no Internet Identity needed
• All calls go directly to the IC boundary nodes

Canister Info

| | | |---|---| | Backend | fwyts-iiaaa-aaaaj-a6lpq-cai | | Frontend | akdjx-daaaa-aaaaj-a6lqa-cai | | Network | ICP Mainnet | | Built with | Motoko, dfx 0.31.0 |

License

MIT — Cleo 3 LLC