🚀 Quick Start

Store and recall your first agent memory in a few minutes. Start offline (no keys), then go durable when ready.

1. Install from npm

Create a fresh project and install the pieces you need directly from npm. Engine, storage, and embedder are separate @lighthouse-ai/* packages you compose:

mkdir my-memory-app && cd my-memory-app
npm init -y
npm install @lighthouse-ai/core @lighthouse-ai/engine-batched @lighthouse-ai/store-local-fs @lighthouse-ai/embed-keyword
npm install -D tsx dotenv typescript @types/node

Add more packages only when you need them:

You want	Install
Batched engine (DIY)	npm install @lighthouse-ai/engine-batched @lighthouse-ai/store-local-fs @lighthouse-ai/store-lighthouse @lighthouse-ai/store-s3 @lighthouse-ai/embed-local @lighthouse-ai/embed-keyword (pick only what you use)
Memwal engine (encrypted relayer)	npm install @lighthouse-ai/engine-memwal
Cross-device pointers	npm install @lighthouse-ai/cloud-sync

2. Store and recall a memory - offline (no keys, no network)

Create memory.mjs in your project root:

// memory.mjs
import '@lighthouse-ai/store-local-fs'
import '@lighthouse-ai/embed-keyword'
import { createStorage } from '@lighthouse-ai/core'
import { BatchedEngine } from '@lighthouse-ai/engine-batched'

const storage = await createStorage('local-fs', { dir: './blobs' })
// embedder: null = keyword-only, zero deps
const memory = new BatchedEngine(storage, { namespace: 'demo', embedder: null })

await memory.remember('User prefers dark mode.', { tags: ['preference'] })
console.log(await memory.recall('what are user preferences?'))

Run it:

npx tsx memory.mjs

Or with semantic search (downloads a ~25 MB MiniLM model once, then runs fully locally):

npm install @lighthouse-ai/embed-local

import '@lighthouse-ai/embed-local'
import { createEmbedder } from '@lighthouse-ai/core'

const embedder = await createEmbedder('local')
const memory = new BatchedEngine(storage, { namespace: 'demo', embedder })

3. Go durable - Lighthouse Filecoin (default) or Walrus

Get a Lighthouse API key from the Lighthouse Files App (API Keys section). For Walrus-backed memory, sign in with your Sui wallet (see the IPFS Walrus quick start); for IPFS/Filecoin any key works.

Install the Lighthouse adapter and dotenv (so a project-root .env is auto-loaded):

npm install @lighthouse-ai/store-lighthouse @lighthouse-ai/embed-local dotenv

Put the key in a project-root .env (git-ignored):

LIGHTHOUSE_API_KEY=lh_...

Create durable.mjs:

// durable.mjs
import 'dotenv/config'
import '@lighthouse-ai/store-lighthouse'
import '@lighthouse-ai/embed-local'
import { createEmbedder, createStorage } from '@lighthouse-ai/core'
import { BatchedEngine } from '@lighthouse-ai/engine-batched'

const storage = await createStorage('lh-ipfs-filecoin', { apiKey: process.env.LIGHTHOUSE_API_KEY })
// swap 'lh-ipfs-filecoin' for 'lh-ipfs-walrus' ('walrus' alias also works) - nothing else changes
const embedder = await createEmbedder('local')
const memory = new BatchedEngine(storage, { namespace: 'demo', embedder })

await memory.remember('The user prefers TypeScript with strict mode and deploys to Vercel.', {
  tags: ['preference', 'deployment'],
})

// Force pending memories onto the network now (otherwise auto-flushes every 10)
const { cid, gatewayUrl } = await memory.flush()
console.log('Stored durably at:', gatewayUrl)

// Recall by meaning - no keyword overlap needed
console.log(await memory.recall('how does the user ship code?'))

Run it:

npx tsx durable.mjs

Need S3 instead? npm install @lighthouse-ai/store-s3 and swap the storage kind to 's3' (S3_BUCKET + creds from env) - nothing else changes.

4. Or use the encrypted relayer engine (memwal)

Get credentials at https://memory.walrus.xyz (mainnet) or https://staging.memory.walrus.xyz (testnet - set MEMWAL_NETWORK=testnet; creds are per-network):

npm install @lighthouse-ai/engine-memwal dotenv

Add to your project-root .env:

MEMWAL_PRIVATE_KEY=<hex-delegate-key>
MEMWAL_ACCOUNT_ID=0x...
MEMWAL_NETWORK=testnet
LIGHTHOUSE_API_KEY=lh_...   # optional: pins public IPFS mirrors of each record

Create memwal.mjs:

// memwal.mjs
import 'dotenv/config'
import { MemwalMemory } from '@lighthouse-ai/engine-memwal'

const memory = await MemwalMemory.fromEnv()
await memory.remember('User prefers dark mode.', { tags: ['preference'] })
console.log(await memory.recall('what theme does the user like?'))

Run it:

npx tsx memwal.mjs

No flush() - every memwal remember goes straight to the relayer. See Store Memories for the batching vs direct-write distinction.

5. What's next?

• Store Memories - tags, metadata, batching and flush behavior, memwal differences
• Recall Memories - hybrid scoring vs relayer search, filters
• Choose a Network - local-fs vs s3 vs lh-ipfs-walrus vs lh-ipfs-filecoin, plus memwal mainnet/testnet
• Rebuild & Recovery - restore on a new machine, snapshots, and the cloud pointer service