🔧 Configuration
Every knob is an env var. 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.
Engine selection
| Var | Default | Purpose |
|---|---|---|
MEMORY_ENGINE | batched | batched or memwal (factory). Unknown values error out. |
MEMORY_STORAGE | lh-ipfs-filecoin | lh-ipfs-filecoin (filecoin alias), lh-ipfs-walrus (walrus alias), local-fs, s3 |
MEMORY_EMBEDDER | local | local (MiniLM semantic) or keyword (word-match only; = embedder: null). Memwal needs none. |
MEMORY_NAMESPACE / MEMORY_AGENT | default / agent | Batched namespace + agent tag |
MEMORY_DIR | ./.memory-sdk | Batched index + local-fs blob location |
MEMORY_FLUSH_EVERY | 10 | Batch size before auto-flush (batched only, min 1) |
MEMORY_NETWORK | - | Gateway variant for bare lighthouse storage kind |
Memwal
| Var | Default | Purpose |
|---|---|---|
MEMWAL_PRIVATE_KEY / MEMWAL_ACCOUNT_ID | - (required) | Relayer delegate key + account |
MEMWAL_NETWORK | mainnet | mainnet or testnet (staging relayer; creds are per-network) |
MEMWAL_SERVER_URL | per-network relayer | Override relayer URL |
MEMWAL_NAMESPACE / MEMWAL_AGENT | default / agent | Memwal namespace + agent tag |
MEMWAL_MEMORY_DIR | ./.memory-sdk/memwal | Memwal index dir |
MEMWAL_REMEMBER_TIMEOUT_MS | 60000 | rememberAndWait timeout |
MEMWAL_IPFS_PIN | (pin) | off skips IPFS pinning (local CIDs only) |
MEMWAL_ANALYZE | - | 1 enables the analyze() demo step in examples |
Storage credentials
| Var | Purpose |
|---|---|
LIGHTHOUSE_API_KEY | Lighthouse adapter (lh-*). Sui-wallet key for Walrus, any key for Filecoin. Optional for memwal (pins public IPFS mirrors). |
S3_BUCKET | Required for s3 |
S3_REGION / AWS_REGION | S3 region |
S3_ENDPOINT | Custom endpoint (R2 / MinIO) |
S3_PREFIX | Key prefix (default memory-sdk) |
S3_FORCE_PATH_STYLE | 1 for MinIO / R2 |
S3_PUBLIC_BASE_URL | CDN base for gatewayUrl() |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | S3 credentials |
Minimal .env examples
# Batched on Filecoin (default durable)
LIGHTHOUSE_API_KEY=lh_...
# Batched on Walrus
MEMORY_ENGINE=batched
MEMORY_STORAGE=lh-ipfs-walrus
LIGHTHOUSE_API_KEY=lh_...
# Offline
MEMORY_ENGINE=batched
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