Most AI agents are brilliant reasoners trapped in amnesiac, dependent shells — they can't persist across restarts, can't fund themselves, and leave no verifiable trace of their actions. Engram is the backend that fixes that.

A framework-agnostic SDK built on the Filecoin Onchain Cloud, Lit Protocol's Vincent + Naga, and the Axelar-powered Squid Router — Engram gives agents the four primitives they're missing: the ability to remember, pay, share context, and prove their actions, without any human in the loop.

• The AI Lobotomy Problem
• The Engram Answer
• PL Genesis
  • Live Demo & Quickstart
  • Verifiable Links (Contracts, TXs, Deals)
• The Lobotomy Test
• How It Works
• Install
• Configuration
• API Reference
• Auto-Policy Engine
• Error Handling
• MCP Server
• Framework Adapters
  • OpenClaw
  • LangChain
  • LlamaIndex
  • MCP Server
• Architecture
• Beyond Ops-Only Tools
• Two Adoption Paths
• Agent Skills
• Testing
• Development

Every time an AI agent's process restarts, it is lobotomized. Its entire working memory — decisions, context, learned state — is wiped. What survives lives in databases that operators control, that agents can't fund, and that carry no cryptographic proof of what was actually stored.

This is not a memory problem. It's an infrastructure problem, and it creates a hard ceiling on what agents can actually do:

Agents can't persist. Context is lost across restarts, deployments, and machines. An agent that reasoned its way to a complex conclusion has no way to carry that conclusion forward.

Agents can't pay. They depend on humans to top up wallets, approve transactions, and manage keys. True autonomy stops at the payment layer.

Agents can't prove. There's no on-chain record of what an agent decided, stored, or spent. Every action is unverifiable and deniable.

Agents can't share. Handing context to another agent requires centralized middleware, shared databases, or manual intervention.

The result: agents that are brilliant reasoners trapped in amnesiac, dependent shells.

Engram replaces the fragile human-dependent layer with protocol-native infrastructure that agents control directly.

The protocols Engram is built on — FOC, Lit Protocol, and ERC-8004 are the core infrastructure the SDK runs on.

AI & Robotics is the primary fit. The track explicitly names ERC-8004, agent identity, and inter-agent payment rails as the infrastructure it wants built. Engram provides all three — cryptographic proof of agent actions via the ReputationRegistry, portable identity via the IdentityRegistry, and autonomous payments via Vincent + Squid Router.

Infrastructure & Digital Rights is the secondary fit. The track is about giving humans data ownership, encrypted storage, and censorship-resistant infrastructure. Engram applies those same guarantees to agents — memory stored on Filecoin that only the agent's key can retrieve, Lit Protocol encryption so the storage provider never sees plaintext, and ERC-8004 attestations that make every action auditable. The digital rights problem for agents is structurally identical to the one the track is trying to solve for humans.

Storage deals are submitted via the Synapse SDK, paid in USDFC from the agent's Vincent smart account. Every store() call:

1. Resolves replication factor and TTL from the Auto-Policy Engine (critical → 5× replication, 365-day TTL)
2. Enforces the maxSpendUSDFC budget guard before any network call
3. If the USDFC balance is below the estimated cost, Squid Router bridges funds autonomously
4. Submits the deal to Filecoin — agent pays directly, no operator approval
5. Returns a StorageReceipt: CID, deal ID, TTL timestamp, USDFC spent

Retrieval fetches by CID and decrypts automatically if the payload was encrypted. The EngramIndexRegistry on-chain pointer enables full memory reconstruction from a private key alone — no server, no database.

Vincent provisions a PKP-based smart account to the agent at SDK init. All on-chain spend — Filecoin storage deals, Axelar bridge transactions — is signed by the agent's PKP. The operator configures the agent but does not control its wallet.

Naga (Lit Protocol V1) handles encryption when encrypt: true is set. The payload is encrypted before leaving the process, with an access condition tied to the agent's DID. The storage provider on Filecoin only ever sees ciphertext. Decryption happens automatically on retrieve() using the same PKP.

const receipt = await sdk.store(reasoningChain, { priority: 'critical', encrypt: true });
const data    = await sdk.retrieve(receipt.cid); // Lit decrypts using agent PKP

Three registries are active on Base Sepolia:

The packages/identity package handles registration, attestation writes, and index pointer updates. Errors surface as typed RegistrationFailedError with structured context.

• Live Dashboard: https://engramsdk.dev/
• Docs: https://docs.engramsdk.dev/

The live site at https://engramsdk.dev/ is not a mocked UI demo. It is a replay of real Engram agent activity and transaction history that already happened on Filecoin mainnet.

What you are seeing in the dashboard reflects actual executed operations, including storage lifecycle events and on-chain proofs captured from production activity on Filecoin Mainnet.

For local verification, see agent-log.json, which contains the replay source events (for example BRIDGE_ROUTE_QUOTED, STORE, DELEGATE_ISSUED, DELEGATION_VERIFIED, and RESTORE_COMPLETE) plus concrete transaction metadata like bridgeTxHash.

pnpm demo          # autonomous agent flow + delegation + restore/lobotomy
pnpm demo:restore  # restore/lobotomy mode only
pnpm demo:agent-b  # delegated retrieval path for Agent B
pnpm swarm         # 3-agent incident-response swarm
pnpm swarm:restore # swarm restore phase

• pnpm demo (demo/agent.ts): A GPT-4o-mini langchain agent self-provisions its Vincent wallet and ERC-8004 identity, runs an autonomous research loop, offloads context to Filecoin at 80% capacity, resolves cross-chain USDC -> USDFC funding via Squid when needed, delegates memory access to Agent B, and then passes the Lobotomy Test by restoring from on-chain history + Filecoin CIDs after local wipe.
• pnpm swarm (demo/swarm.ts): A Commander coordinates Analyst and Verifier agents through a security incident. Findings are stored to Filecoin, delegated via signed capability tokens, and verified across agents. The Commander is intentionally hard-killed mid-run, restored from ERC-8004-linked history, and completes a final brief with CID-backed provenance for each claim.

Below are concrete, replay-backed artifacts you can click and independently verify.

In this replay, the logged dealId mirrors the CID value returned by the storage layer. Full raw event history lives in agent-log.json.

The definitive test for any agent memory system: wipe everything and see what survives.

Engram is designed to pass it. Here's what recovery looks like from a cold private key alone:

import { restore } from 'engramjs';

// New machine. No local files. Just the agent's private key.
const index = await restore({ operatorPrivateKey });

// Engram resolves the on-chain EngramIndexRegistry pointer,
// fetches the CID index from Filecoin, and reconstructs the full memory map.
// The agent is back.

console.log(`Recovered ${index.cids.length} memories`);
for (const cid of index.cids) {
  const memory = await sdk.retrieve(cid);
  // full data, fully decrypted, exactly as it was stored
}

How it works under the hood:

restore(privateKey)
 │
 ├─ Derive agent DID from private key
 ├─ Query EngramIndexRegistry on-chain → fetch latest index CID pointer
 ├─ Fetch index snapshot from Filecoin by CID
 ├─ Reconstruct full CID map { cid → { expiryDate, policy } }
 └─ Return populated index — agent is fully restored

No server. No database. No operator. Just the key and the chain.

sdk.store(data, { priority: 'critical', encrypt: true })
 │
 ├─ 1. Auto-Policy Engine resolves storage parameters
 │       priority: 'critical' → replication: 5, ttlDays: 365, encrypt: true
 │       explicit overrides always win over policy defaults
 │
 ├─ 2. Budget guard enforced before any network call
 │       runningSpend + estimatedCost must be ≤ maxSpendUSDFC
 │
 ├─ 3. (if funds low) Squid Router bridges autonomously
 │       USDC / ETH / any supported token → USDFC on Filecoin
 │       no human approval required
 │
 ├─ 4. (if encrypt: true) Lit Protocol / Vincent encrypts payload
 │       PKP access condition tied to agent DID
 │       ciphertext only — plaintext never leaves the process unencrypted
 │
 ├─ 5. Synapse SDK submits storage deal on Filecoin Onchain Cloud
 │       agent's Vincent smart account pays USDFC directly
 │       returns CID + deal confirmation
 │
 ├─ 6. (if attestOnChain: true) ERC-8004 ReputationRegistry
 │       writes on-chain receipt: what was stored, when, by whom
 │       immutable, timestamped, signed by agent DID
 │
 ├─ 7. EngramIndexRegistry updated with new CID pointer
 │       enables cold-key recovery (the Lobotomy Test)
 │
 └─ 8. Return StorageReceipt { cid, dealId, ttlTimestamp, spendUSDFC, policy, attestationTx }

sdk.retrieve(cid)
 │
 ├─ Fetch from Filecoin by CID
 ├─ (if encrypted) Lit Protocol decrypts using agent PKP
 └─ Return original payload — type preserved

npm install engramjs

MCP server (for Cursor, Claude Desktop, or any MCP client):

npx @engram-sdk/mcp

import { EngramSDK } from 'engramjs';
import { createProvider } from '@engram-sdk/providers';

const storageProvider = await createProvider(); // Synapse by default

const sdk = new EngramSDK({
  storageProvider,

  // Credentials
  operatorPrivateKey: process.env.OPERATOR_PRIVATE_KEY, // signs on-chain txs
  vincentApiKey: process.env.VINCENT_SECRET_API_KEY, // Vincent smart account

  // Network
  network: 'calibration', // 'mainnet' for production

  // Budget controls — enforced before every store()
  maxSpendUSDFC: 10, // cumulative ceiling
  renewThresholdDays: 14, // renew X days before expiry
  safetyMarginPct: 20, // add 20% buffer to cost estimates

  // Behavior
  attestOnChain: true, // write ERC-8004 receipt after every store
  agentName: 'my-agent',
  logPath: './agent_log.json',
  verbose: false,
});

import { EngramSDK } from 'engramjs';
import { MockStorageProvider } from '@engram-sdk/providers/mock';

const sdk = new EngramSDK({
  storageProvider: new MockStorageProvider(),
  maxSpendUSDFC: 10,
});

// Fully functional — store, retrieve, renew, prune all work.
// MockStorageProvider simulates latency and tracks spend.

sdk.store(data: unknown, options?: StoreOptions): Promise<StorageReceipt>

const receipt = await sdk.store(
  { messages: conversationHistory, stepCount: 142 },
  { priority: 'critical', encrypt: true },
);

// receipt.cid            → 'bafy...'
// receipt.dealId         → Filecoin deal identifier
// receipt.ttlTimestamp   → Date  (365 days for 'critical')
// receipt.spendUSDFC     → 0.04
// receipt.policy         → { replication: 5, ttlDays: 365, encrypt: true }
// receipt.attestationTx  → '0x...'  (if attestOnChain: true)

Priority levels:

Explicit options always override priority defaults:

await sdk.store(data, {
  priority: 'standard',
  replication: 5, // override: store more copies
  ttlDays: 180, // override: custom retention
  encrypt: true, // override: force encrypt
});

sdk.retrieve(cid: string, options?: RetrieveOptions): Promise<unknown>

Fetches from Filecoin and decrypts automatically if the payload was encrypted.

const data = await sdk.retrieve(receipt.cid);

sdk.renew(cid: string, options?: RenewOptions): Promise<RenewResult>

Submits a renewal deal if within the renewThresholdDays window. Idempotent — safe to run on a schedule.

const result = await sdk.renew('bafy...');
// result.renewed         → true | false
// result.daysUntilExpiry → 11
// result.newTtlTimestamp → Date  (if renewed)

sdk.prune(cid: string): Promise<PruneResult>

Removes a CID from the active memory index and logs a PRUNE event. Data on Filecoin is immutable — prune manages the index, not the underlying storage.

Issue a signed capability token granting another agent read access to a specific memory:

import { delegate } from 'engramjs';

const { tokenCid, token } = await delegate(sdk, receipt.cid, partnerAgentDID, {
  ttlHours: 24,
});
// tokenCid       → 'bafy...'  share this CID with the recipient
// token.signature → '0x...'
// token.expiresAt → ISO string
// token.scope     → 'agent/read'

import { verifyDelegation } from 'engramjs';

const token = await verifyDelegation(sdk, tokenCid, callerDID);
// Throws DelegationVerificationError — wrong recipient or invalid signature
// Throws DelegationExpiredError     — token past expiresAt

A pure, deterministic function — no side effects, fully testable in isolation:

import { resolvePolicy } from 'engramjs';

resolvePolicy({ priority: 'critical' });
// → { replication: 5, ttlDays: 365, encrypt: true }

resolvePolicy({ priority: 'standard', replication: 5, ttlDays: 180 });
// → { replication: 5, ttlDays: 180, encrypt: false }
// explicit fields always win over priority defaults

All errors are typed and carry structured context:

import {
  BudgetExceededError, // spend would exceed maxSpendUSDFC
  InsufficientBalanceError, // USDFC balance too low
  StorageDealFailedError, // Filecoin deal failed
  DecryptionFailedError, // Lit Protocol decryption error
  DelegationVerificationError, // wrong recipient or invalid signature
  DelegationExpiredError, // token past expiresAt
  RegistrationFailedError, // ERC-8004 registration failed
} from 'engramjs';

try {
  await sdk.store(largePayload, { priority: 'critical' });
} catch (err) {
  if (err instanceof BudgetExceededError) {
    // err.maxSpend      → 10 (configured ceiling)
    // err.currentSpend  → 9.8 (running total)
    // err.estimatedCost → 0.4 (projected cost of this operation)
  }
  if (err instanceof InsufficientBalanceError) {
    // err.required  → USDFC needed
    // err.available → current agent balance
    // → trigger sdk funding flow or alert operator
  }
}

Engram ships a standalone MCP server that exposes the full SDK as tools — usable directly from Cursor, Claude Desktop, or any MCP-compatible client. No integration code required.

OPERATOR_PRIVATE_KEY=0x... ENGRAM_NETWORK=calibration npx @engram-sdk/mcp
# → [engram:mcp] Server listening on http://localhost:3456/mcp

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "engram": { "url": "http://localhost:3456/mcp" }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "engram": { "url": "http://localhost:3456/mcp" }
  }
}

# Health check
curl http://localhost:3456/health
# → { "status": "ok", "tools": ["engram_store", "engram_retrieve", ...] }

The OpenClaw adapter is a lifecycle hook — install it once and every agent session is automatically snapshotted to Filecoin on command:new and restored from Filecoin on agent:bootstrap. Zero changes to your agent code.

openclaw hooks install ./packages/adapters/openclaw

agent:bootstrap  → reads last CID from disk
                 → fetches snapshot from Filecoin
                 → injects ENGRAM_MEMORY.md into bootstrapFiles
                 → agent starts with full prior context

command:new      → snapshots current session to Filecoin
                 → saves CID locally
                 → agent carries memory into next session

The agent never goes blank between sessions.

import {
  EngramStoreTool,
  EngramRetrieveTool,
} from 'engramjs/adapters/langchain';
import { createOpenAIFunctionsAgent } from 'langchain/agents';

const tools = [new EngramStoreTool(sdk), new EngramRetrieveTool(sdk)];
const agent = await createOpenAIFunctionsAgent({ llm, tools, prompt });
// Every decision the agent makes can be persisted to Filecoin
// and recalled in future sessions by CID

import { EngramWriter, EngramReader } from 'engramjs/adapters/llamaindex';

const writer = new EngramWriter(sdk);
const cid = await writer.store(document);

const reader = new EngramReader(sdk);
const doc = await reader.loadData(cid);

┌──────────────────────────────────────────────────────────────────────┐
│                        Your Agent / App                              │
│              LangChain · LlamaIndex · MCP · custom loop              │
└────────────────────────────────┬─────────────────────────────────────┘
                                 │
                                 ▼
┌──────────────────────────────────────────────────────────────────────┐
│                          engramjs SDK                                │
│                                                                      │
│  ┌──────────────────┐   ┌───────────────┐   ┌─────────────────────┐  │
│  │  Auto-Policy     │   │  Budget Guard │   │  Logger + Errors    │  │
│  │  Engine          │   │  maxSpendUSDFC│   │  typed, structured  │  │
│  └──────────────────┘   └───────────────┘   └─────────────────────┘  │
│                                                                      │
│  ┌───────────────────────────────┐  ┌──────────────────────────────┐ │
│  │  Identity + Delegation        │  │  Wallet + Encryption         │ │
│  │                               │  │                              │ │
│  │  ERC-8004 IdentityRegistry    │  │  Lit Protocol / Vincent      │ │
│  │  ERC-8004 ReputationRegistry  │  │  PKP-based smart accounts    │ │
│  │  EngramIndexRegistry          │  │  Squid Router (Axelar)       │ │
│  │  Capability token delegation  │  │  Multichain → USDFC          │ │
│  └───────────────────────────────┘  └──────────────────────────────┘ │
└─────────────────┬────────────────────────────────────────────────────┘
                  │
      ┌───────────┴────────────┐
      ▼                        ▼
┌───────────────────┐  ┌─────────────────────────────┐
│  StorageProvider  │  │  Base Sepolia (on-chain)     │
│                   │  │                             │
│  Synapse SDK      │  │  IdentityRegistry (ERC-8004)│
│  ↓                │  │  ReputationRegistry         │
│  Filecoin         │  │  EngramIndexRegistry        │
│  Onchain Cloud    │  │  ↑                          │
│  (USDFC deals)    │  │  recovery anchor for        │
│                   │  │  the Lobotomy Test          │
└───────────────────┘  └─────────────────────────────┘

CLI-first storage tooling is excellent for setup, uploads, wallet checks, and provider operations. Engram includes those operational concerns, but its core value is agent-native memory behavior:

• Multi-agent delegation — issue and verify signed capability tokens for cross-agent context handoff.
• Verifiable memory handoff — Agent A can delegate a specific CID to Agent B with expiry + recipient checks.
• Restore / Lobotomy recovery — wipe local index, recover memory map from on-chain index pointer + Filecoin snapshot.
• Lifecycle semantics for agents — store/retrieve/renew/prune with deterministic policy, budget guardrails, and optional on-chain receipts.

In short: ops commands are part of Engram, not the product boundary.

Goal: prove the memory lifecycle quickly with zero chain risk.

1. Use MockStorageProvider
2. Store one payload
3. Retrieve by returned CID
4. Confirm logs and policy behavior

import { EngramSDK } from 'engramjs';
import { createProvider } from '@engram-sdk/providers';

const sdk = new EngramSDK({
  storageProvider: await createProvider('mock'),
  maxSpendUSDFC: 5,
});

const receipt = await sdk.store({ note: 'hello engram' }, { priority: 'standard' });
const data = await sdk.retrieve(receipt.cid);
console.log(receipt.cid, data);

Goal: run with real persistence, verifiability, and disaster-recovery confidence.

1. Use live provider (synapse) on calibration or mainnet
2. Enable attestOnChain
3. Run normal store/retrieve/renew/prune operations
4. Run restore drill (restore() or demo restore mode) to validate cold-start recovery

import { EngramSDK } from 'engramjs';
import { createProvider } from '@engram-sdk/providers';

const sdk = new EngramSDK({
  storageProvider: await createProvider('synapse'),
  operatorPrivateKey: process.env.OPERATOR_PRIVATE_KEY,
  vincentApiKey: process.env.VINCENT_SECRET_API_KEY,
  network: 'mainnet',
  attestOnChain: true,
  maxSpendUSDFC: 250,
  renewThresholdDays: 21,
  safetyMarginPct: 25,
});

For a full end-to-end example (delegation + restore), run pnpm demo.

For AI agents consuming this repo/docs:

• Repo-level agent guidance: SKILLS.md
• Docs authoring guidance: docs/skills.md
• LLM docs index/context: docs/llm.txt

These files are optimized for tool-using agents and keep outputs consistent with Engram semantics.

All tests run against MockStorageProvider — zero network calls, zero keys, zero USDFC needed.

pnpm test            # 72 tests, all passing
pnpm test:watch      # watch mode for development
pnpm test:coverage   # coverage report

Tests cover:

• Policy engine (pure function — 11 cases)
• Store / retrieve / renew / prune lifecycle (14 cases)
• Budget enforcement and typed errors (8 cases)
• Capability delegation — issue, verify, reject expired, reject tampered (6 cases)
• Wallet helpers (18 cases)

git clone https://github.com/aryza0x/engram-sdk
cd engram-sdk
pnpm install

pnpm build        # compile all packages (tsc -b, topological order)
pnpm test         # run full test suite
pnpm mcp-server   # start MCP server locally

cp .env.example .env   # fill in keys
pnpm demo              # run the full autonomous agent demo
pnpm swarm             # multi-agent swarm demo

packages/
  core/        EngramSDK class, policy engine, types, errors
  identity/    ERC-8004 registration, attestation, restore
  delegation/  Capability token issuance + verification
  wallet/      Lit Protocol / Vincent PKP wallet helpers
  mcp/         MCP server + CLI binary (npx @engram-sdk/mcp)
  sdk/         Published as 'engramjs' — re-exports everything above
providers/
  synapse.ts   Filecoin Onchain Cloud via Synapse SDK
  mock.ts      In-process mock — deterministic, zero network
demo/
  agent.ts     Autonomous agent: context offload loop, self-funding, restore
  swarm.ts     Multi-agent swarm with capability delegation
  dashboard/   Real-time React dashboard (Vite + SSE)

Pull requests are welcome. For significant changes, open an issue first to discuss the approach. All submissions must pass pnpm test and pnpm build.

MIT