🔧 Configuration

Engine, storage and embedder are chosen in code (see SDK Overview); env vars cover credentials and per-engine defaults. Keys live in a project-root .env (git-ignored) - load it with dotenv (import 'dotenv/config' at the top of your script); explicit shell export still wins. Tests pin local-fs + keyword explicitly so they stay offline.

The Read by column says which code actually reads each var:

• SDK constructor - an adapter or engine constructor / storage factory reads it when you don't pass the option.
• fromEnv - only MemwalMemory.fromEnv() reads it; the MemwalMemory constructor ignores env.
• hosted backend - the MCP server reads it directly. The backend runs the SDK in-process, so it also honours every SDK constructor / fromEnv var.
• example script only - no package reads it; only the tutorial / example scripts do.

Batched engine

Var	Default	Read by	Purpose
MEMORY_NAMESPACE / MEMORY_AGENT	default / agent	SDK constructor, hosted backend	Namespace + agent tag when namespace / agent aren't passed to BatchedEngine
MEMORY_DIR	./.memory-sdk	SDK constructor, hosted backend	Index + local-fs blob location (defaultBaseDir())
MEMORY_FLUSH_EVERY	10	SDK constructor	Batch size before auto-flush (min 1)
MEMORY_NETWORK	ipfs-walrus	SDK constructor, hosted backend	Network for the bare lighthouse storage kind (ipfs-walrus or ipfs-filecoin)
MEMORY_ENGINE	batched	hosted backend	batched or memwal. In your own code, pick the engine class instead
MEMORY_STORAGE	lh-ipfs-filecoin	hosted backend, example script only	Storage kind. In the SDK it's only a fallback for MEMORY_NETWORK on the bare lighthouse kind (lh- prefix stripped)
MEMORY_EMBEDDER	local	hosted backend, example script only	Embedder kind. In the SDK only core's resolveEmbedder() reads it, and only when no embedder is passed

To pick engine, storage and embedder from env in your own code, read the vars yourself - the tutorial scripts do this:

const storage = await createStorage(process.env.MEMORY_STORAGE ?? 'local-fs', { dir })
const embedderName = process.env.MEMORY_EMBEDDER ?? 'keyword'
const embedder = embedderName === 'keyword' ? null : await createEmbedder(embedderName)

Memwal

Var	Default	Read by	Purpose
MEMWAL_PRIVATE_KEY / MEMWAL_ACCOUNT_ID	- (required)	fromEnv	Relayer delegate key + account
MEMWAL_NETWORK	mainnet	fromEnv	mainnet or testnet (staging relayer; creds are per-network)
MEMWAL_SERVER_URL	per-network relayer	fromEnv	Override relayer URL
MEMWAL_NAMESPACE / MEMWAL_AGENT	default / agent	fromEnv (namespace also hosted backend)	Memwal namespace + agent tag
MEMWAL_MEMORY_DIR	./.memory-sdk/memwal	fromEnv	Memwal index dir
MEMWAL_REMEMBER_TIMEOUT_MS	60000	fromEnv	rememberAndWait timeout
MEMWAL_IPFS_PIN	(pin)	fromEnv	off skips IPFS pinning (local CIDs only)
MEMWAL_ANALYZE	-	example script only	Demo flag: 1 runs the analyze() step in the memwal example / tutorial script. Not an SDK setting

Storage credentials

Var	Read by	Purpose
LIGHTHOUSE_API_KEY	SDK constructor, fromEnv	Lighthouse adapter (lh-*). Sui-wallet key for Walrus, any key for Filecoin. Optional for memwal (pins public IPFS mirrors).
S3_BUCKET	SDK constructor, hosted backend	Required for s3
S3_REGION / AWS_REGION	SDK constructor	S3 region
S3_ENDPOINT	SDK constructor	Custom endpoint (R2 / MinIO)
S3_PREFIX	SDK constructor	Key prefix (default memory-sdk)
S3_FORCE_PATH_STYLE	SDK constructor	1 for MinIO / R2
S3_PUBLIC_BASE_URL	SDK constructor	CDN base for gatewayUrl()
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	SDK constructor	S3 credentials

Minimal .env examples

# Batched on Filecoin or Walrus (storage kind picked in code)
LIGHTHOUSE_API_KEY=lh_...

# Offline - read by the offline tutorial script, not by the SDK
MEMORY_STORAGE=local-fs
MEMORY_EMBEDDER=keyword

# Memwal testnet
MEMWAL_PRIVATE_KEY=<hex-delegate-key>
MEMWAL_ACCOUNT_ID=0x...
MEMWAL_NETWORK=testnet
LIGHTHOUSE_API_KEY=lh_...  # optional pinning