Configuration

EngramSDK is configured through EngramConfig. This page maps each field to runtime behavior, risk, and production guidance.

Configuration Philosophy

The config surface is intentionally split between:

• capability controls (provider, keys, network, attestation)
• safety controls (budget ceiling, renew threshold, safety margin)
• operational controls (identity path, logs, verbosity, endpoint overrides)

This aligns with the PRD goal: autonomous execution that remains inspectable and bounded.

Production Baseline

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: 'calibration',
  maxSpendUSDFC: 10,
  renewThresholdDays: 14,
  safetyMarginPct: 20,
  attestOnChain: true,
  agentName: 'engram-agent',
  logPath: './agent_log.json',
  verbose: false
})

Baseline Guardrail Presets

Use these as policy-of-operation defaults:

Scenario	maxSpendUSDFC	renewThresholdDays	safetyMarginPct	attestOnChain
Local/dev	5-10	14	20	false
Staging	10-50	14-21	20-25	true
Production	env-specific	21-30	25-35	true

Treat these as starting points; tune with real usage and spend telemetry.

Full EngramConfig Field Reference

Field	Type	Default	Why it matters
storageProvider	StorageProvider	none	Required backend for store/retrieve/renew
operatorPrivateKey	string	none	Required for on-chain identity/index workflows
vincentApiKey	string	unset	Enables Vincent wallet flows
network	'calibration' | 'mainnet'	'calibration'	Selects chain and defaults
baseRpcUrl	string	https://sepolia.base.org	Base RPC override
filecoinRpcUrl	string	GLIF endpoint by network	Filecoin RPC override
vincentApiBaseUrl	string	https://heyvincent.ai	Vincent API override
identityRegistryAddress	string	deployed default	Custom identity registry
reputationRegistryAddress	string	deployed default	Custom attestation registry
indexRegistryAddress	string	deployed default	Custom index pointer registry
agentName	string	engram-memory-agent	Metadata and operator clarity
agentMcpPort	number	3456	MCP server port
verbose	boolean	false	Additional diagnostics
wallet	WalletStub	unset	Custom wallet behavior
maxSpendUSDFC	number	10	Hard budget cap for spend guard
renewThresholdDays	number	14	Renewal trigger window
safetyMarginPct	number	20	Cost estimate buffer
logPath	string	unset	Structured operation log destination
autoFund	boolean	unset	Allow automatic top-up flow when available
attestOnChain	boolean	false	Emit ERC-8004 operation attestations
identityPath	string	.engram/identity.json	Identity file isolation per agent

Minimal Config Profiles

Local Unit Testing (No Network)

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

Integration Testing (Calibration)

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

Production (Mainnet)

const sdk = new EngramSDK({
  storageProvider: await createProvider('synapse'),
  operatorPrivateKey: process.env.OPERATOR_PRIVATE_KEY,
  vincentApiKey: process.env.VINCENT_SECRET_API_KEY,
  network: 'mainnet',
  maxSpendUSDFC: 250,
  renewThresholdDays: 21,
  safetyMarginPct: 25,
  attestOnChain: true,
  identityPath: '/var/lib/engram/agent-a.identity.json',
  logPath: '/var/log/engram/agent-a.jsonl'
})

Environment Variable Mapping (MCP/CLI Flows)

If you run @engram-sdk/mcp, these env vars map to config fields:

Environment Variable	Config field
OPERATOR_PRIVATE_KEY	operatorPrivateKey
VINCENT_SECRET_API_KEY	vincentApiKey
ENGRAM_NETWORK	network
ENGRAM_MCP_PORT	agentMcpPort
ENGRAM_ATTEST_ON_CHAIN	attestOnChain
ENGRAM_BUDGET_MAX_USDFC	maxSpendUSDFC
ENGRAM_RENEW_THRESHOLD_DAYS	renewThresholdDays
ENGRAM_BUDGET_SAFETY_MARGIN_PCT	safetyMarginPct
ENGRAM_LOG_PATH	logPath
BASE_RPC_URL	baseRpcUrl
FILECOIN_RPC_URL	filecoinRpcUrl
ERC8004_IDENTITY_REGISTRY	identityRegistryAddress
ERC8004_REPUTATION_REGISTRY	reputationRegistryAddress

Network and Contract Overrides

Override RPC endpoints and contract addresses only when you intentionally control infrastructure or deploy custom contracts. Keep defaults unless you have a strict reason.

When overriding:

• pin all related addresses together (identity/reputation/index)
• record versioned config manifests per environment
• validate with a canary agent before global rollout

Multi-Agent Hosts

If multiple agents run in one process or pod, each agent needs:

• unique identityPath
• unique agentName
• isolated logs (logPath)
• clear budget partition (maxSpendUSDFC)

Example:

const agentA = new EngramSDK({
  storageProvider,
  identityPath: '.engram/agent-a.identity.json',
  agentName: 'agent-a',
  logPath: './agent-a.log.json',
  maxSpendUSDFC: 25
})

const agentB = new EngramSDK({
  storageProvider,
  identityPath: '.engram/agent-b.identity.json',
  agentName: 'agent-b',
  logPath: './agent-b.log.json',
  maxSpendUSDFC: 10
})

Dev vs Production

Mode	Provider	Keys	Attestation	Goal
Local dev	mock	none	off	fast iteration
Integration	synapse on calibration	test keys	optional	end-to-end confidence
Production	synapse on mainnet	managed keys	on	durable operation

Configuration Anti-Patterns

• sharing one identityPath across multiple autonomous agents
• leaving maxSpendUSDFC unset in live workflows
• running production with verbose: true and no log controls
• enabling attestOnChain without monitoring for tx failures