Lighthouse Memory is built from 3 swappable layers: an engine, a storage network and an embedder. I used it to save 5 facts about a test learner, recall them in a fresh session, and check that every batch had a verifiable fingerprint.
This post is the builder version: how the pieces fit, the setup the docs give you, and what to watch out for.
What are the three layers?
From the official docs (https://docs.lighthouse.storage/memory/intro):
Engine: how memories are stored and searched. "batched" embeds locally and flushes memories as one blob every 10 by default. "memwal" hands embedding, encryption and search to a Walrus relayer.
Storage: where the bytes live. Local folder for offline work, S3, R2 or MinIO, Lighthouse with Walrus, or Lighthouse with Filecoin, which is the default.
Embedder: how recall ranks results. The default is a small local model (all-MiniLM-L6-v2) blended with keyword matching. You can also run keyword-only.
You pick each layer with environment variables, so the same agent code can move from your laptop to Filecoin without a rewrite.
What does the setup look like?
This is the batched setup from the docs:
import '@lighthouse-ai/store-lighthouse'
import '@lighthouse-ai/embed-local'
import { createStorage, createEmbedder } from '@lighthouse-ai/core'
import { BatchedEngine } from '@lighthouse-ai/engine-batched'
const storage = await createStorage('lh-ipfs-filecoin', { apiKey: process.env.LIGHTHOUSE_API_KEY })
const embedder = await createEmbedder('local')
const memory = new BatchedEngine(storage, { namespace: 'demo', embedder })
From there the agent uses remember, recall and forget. Pending memories are searchable straight away, and a flush uploads them as one batch blob with its own CID. The docs' Quick Start (https://docs.lighthouse.storage/memory/quick-start) covers the full calls.
If your agent speaks MCP, you can skip the SDK: the hosted backend exposes memory as MCP tools for Claude Code, Claude Desktop and other MCP clients.
What did I test?
I created a test learner, Tobi, and saved 5 facts: MetaMask set up on 2 October, seed phrase backed up on paper, confused about gas price versus gas limit, prefers Pidgin, nearly signed a fake airdrop last week.
Then I closed the process and ran recall in a new session:
"Where did I store my recovery words?" returned the seed phrase note first. No shared keywords, so the local embedder did the work.
"Someone sent me a link for free tokens, is it safe?" returned the fake airdrop memory.
"Why did my transaction cost so much?" returned the gas lesson first, but only narrowly ahead of the airdrop memory.
The flushed batch got the CID bafkreidjvg75kgsnqodj72phjcuydjqs4cncmseitlsht3zb5knx3qcdl4. When I edited one phrase in a copy of that batch, "on paper" to "in Google Drive", the CID became bafkreidrqqfuz2a74dvzhuiswxmpzd5iav3uvn54odwak7o3oz2bim64mu. A one-phrase edit gives a completely different fingerprint, which is the whole point of content addressing.
What happens when you forget and rebuild?
I forgot one fact, then rebuilt the local index from storage. All 5 facts came back, including the forgotten one. That makes sense once you see the design: forget works on the local index, while the original batch blob is still on the network with the other facts in it.
If your product needs real deletion, design for it. Keep sensitive data out of shared batches, or use the memwal engine and its encrypted blobs.
What should builders watch out for?
Batched blobs are unencrypted. The docs say plainly that anyone with a CID can read them. Store context, never secrets. A note that a learner keeps their seed phrase on paper is fine. The phrase itself is not.
Close scores. My recall scores were low and close together. With a large memory store, add tags and test your ranking before trusting the top result.
Walrus quota. The docs note every Walrus blob counts about 63 MB against quota after erasure coding, whatever its size. Batching exists partly for that reason.
Recovery. You can rebuild a whole memory store on a new machine from a single snapshot CID. Test that path before you need it.
Why build on this?
The layers are the real win. You can start offline with a local folder, move to S3 for a pilot, and land on Filecoin or Walrus for production, without touching your agent's logic. And because every batch has a CID, you can prove what your agent knew.
The short version is my X thread (https://x.com/The_Real_EJC/status/2108138685300437129). I also wrote on Substack about why owned memory matters for African learners (https://therealejc.substack.com/p/why-does-an-ai-tutor-need-memory). Try it yourself at https://memory.lighthouse.storage.