Getting Started

This guide covers a practical local setup, then a production-ready baseline.

Why Start This Way

The recommended sequence (mock -> calibration -> mainnet) is intentional:

• validate lifecycle logic before introducing chain complexity
• verify budget and policy behavior under realistic conditions
• only then promote to production funding and attestation paths

This follows the SDK's product goal: autonomous operation with explicit guardrails, not silent best-effort behavior.

Requirements

• Node.js >=20
• A package manager (npm recommended for app projects)
• Optional for live network operations:
  • OPERATOR_PRIVATE_KEY
  • VINCENT_SECRET_API_KEY

Install SDK

npm install engramjs @engram-sdk/providers

Start With Mock Provider

Use the mock provider first so you can validate behavior without chain keys or network calls.

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

const storageProvider = await createProvider('mock')

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

const receipt = await sdk.store({ task: 'bootstrap state' }, { priority: 'standard' })
const payload = await sdk.retrieve(receipt.cid)

Enable Live Storage (Synapse/Filecoin)

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

const storageProvider = await createProvider('synapse')

const sdk = new EngramSDK({
  storageProvider,
  operatorPrivateKey: process.env.OPERATOR_PRIVATE_KEY,
  vincentApiKey: process.env.VINCENT_SECRET_API_KEY,
  network: 'calibration',
  attestOnChain: true
})

Environment Variables

OPERATOR_PRIVATE_KEY=0x...
VINCENT_SECRET_API_KEY=ssk_...
ENGRAM_NETWORK=calibration
ENGRAM_STORAGE_PROVIDER=synapse

Integration Tiers

Use this staged rollout model to avoid jumping straight into full production complexity.

Tier	Goal	Typical setup
0	Local dev/CI, zero network cost	ENGRAM_STORAGE_PROVIDER=mock
1	Real storage flow on testnet/mainnet	ENGRAM_STORAGE_PROVIDER=synapse, OPERATOR_PRIVATE_KEY, ENGRAM_NETWORK
2	Wallet + confidential memory	add VINCENT_SECRET_API_KEY, store with encrypt: true for sensitive payloads
3	Verifiable receipts	enable attestOnChain: true (or ENGRAM_ATTEST_ON_CHAIN=true in MCP/CLI flows)
4	Unattended funding path	enable autoFund: true and configure funding timeout/poll env vars

Tiered setup keeps failures easy to isolate when first integrating.

What “Done” Looks Like

A strong initial integration should prove all of these:

• your app can persist and recover state by CID
• budget checks stop unsafe write growth
• logs capture operation outcomes and spend context
• delegation tokens can be issued and verified (if multi-agent flows matter)

First Lifecycle Test

Run a minimal memory lifecycle in your app startup:

1. store a small object with priority: 'critical'
2. retrieve the same CID
3. renew once to confirm renewal permissions and pathing
4. prune only if this is disposable test data

Optional Funding Env (Auto-Fund)

If using unattended funding in wallet flows, these env vars are commonly configured:

SQUID_INTEGRATOR_ID=your-integrator
ENGRAM_FUNDING_TIMEOUT_MS=300000
ENGRAM_FUNDING_POLL_MS=10000
SQUID_FROM_CHAIN=42161
SQUID_TO_CHAIN=314

You can also override token addresses via:

• SQUID_USDC_ARBITRUM
• SQUID_USDFC_FILECOIN

Recommended Next Steps

• Read Problem and Design Goals for product context
• Read Concepts for lifecycle and trust model
• Use Configuration to harden deployment settings

Continue with Configuration before production rollout.