👋 Introduction

What is Lighthouse Memory?

Lighthouse Memory gives AI agents durable, portable long-term memory backed by decentralized storage. Agents get simple remember / recall / forget primitives every memory is persisted as a verifiable, content-addressed blob (CIDv1).

Because memory lives on the network rather than inside one app or session, an agent can pick up where it left off across sessions, machines, and runtimes and the entire memory store can be restored on a brand-new machine from just a snapshot CID.

One API, swappable layers. You pick the engine (how memories are stored/searched), the storage (where bytes live), and the embedder (how recall ranks) per deploy with env vars.

The three layers

Layer	Choices	Pick with
Engine	`batched` - you embed locally, memories buffer and flush as one blob per `flushEvery` (default 10) on any storage · `memwal` - the Walrus relayer embeds, SEAL-encrypts, and searches; you keep tags/CIDs locally	`MEMORY_ENGINE=batched \| memwal`
Storage (batched only; memwal owns its blobs)	`local-fs` (local folder, offline) · `s3` (AWS S3 / R2 / MinIO) · `lh-ipfs-walrus` (`walrus` alias, Lighthouse x Walrus) · `lh-ipfs-filecoin` (`filecoin` alias, default)	`MEMORY_STORAGE` + `LIGHTHOUSE_API_KEY` / `S3_BUCKET` / `dir`
Embedder (batched only; memwal searches server-side)	`local` (default, in-process MiniLM `all-MiniLM-L6-v2`, hybrid `0.7 × cosine + 0.3 × keyword`) · `keyword` (word-match only, zero deps - pass `embedder: null`)	`MEMORY_EMBEDDER=local \| keyword`

Side-effect imports self-register each package, so createStorage / createEmbedder can find it:

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 })

import { MemwalMemory } from '@lighthouse-ai/engine-memwal'

const memory = await MemwalMemory.fromEnv() // MEMWAL_PRIVATE_KEY + MEMWAL_ACCOUNT_ID

What You Can Do

Store memories durably - facts, decisions, preferences, and context are written to Lighthouse storage (or S3 / local disk) and retrievable by CID.
Recall by meaning - batched search runs locally with an in-process embedding model (nothing leaves the machine) combined with keyword/tag matching; memwal search runs in the relayer over SEAL-encrypted blobs.
Connect any agent via MCP - the hosted memory-backend exposes memory as Model Context Protocol tools (POST /mcp) for Claude Code, Claude Desktop, and any MCP-capable agent. Tools adapt to the active engine.
Batch writes to save quota - (batched engine) memories buffer locally and flush as one blob. On Walrus this matters: every blob counts ~63 MB against quota after erasure coding, regardless of size.
Recover from nothing - rebuild the local search index from the network, or restore it on a brand-new machine from a single snapshot CID tracked by the pointer service. See Rebuild & Recovery.

How It Works

Batched engine (local embed + any storage):

agent ──(MCP tools / TypeScript API)──► BatchedEngine
                                            │
                         ┌──────────────────┼─────────────────────┐
                         ▼                  ▼                     ▼
                   batch blob         local search index    index snapshot
                   (memories JSON     (content, tags,       (snapshotIndex() CID,
                    on Walrus /        vectors - fast        tracked by pointer
                    Filecoin /         local recall,         service for fast
                    S3 / disk)         incl. pending)        restore)

Remember - content (+ tags, metadata) is embedded locally and buffered as pending.
Flush - pending memories upload as one batch blob (auto-flush every flushEvery memories, or flush() manually).
Recall - hybrid cosine + keyword/tag ranking over flushed and pending memories.
Rebuild - on a new machine, re-read every batch blob (rebuild()), or merge a single index snapshot (rebuildLocal(cid) - the fast path the pointer service uses).

Memwal engine (relayer: embed + encrypt + search):

agent ──(MCP tools / TypeScript API)──► MemwalMemory ──► relayer (embed + SEAL-encrypt + Walrus + vector search)
                                            │
                                            ▼
                                   local index (tags, CIDs, blob IDs, IPFS mirrors)

Every remember goes straight to the relayer (no batching). Recall is a relayer vector search enriched with local tags/CIDs. Optional Lighthouse pinning gives each record a public IPFS mirror.

Storage networks

	`lh-ipfs-walrus`	`lh-ipfs-filecoin` (default)	`s3`	`local-fs`
Backing	Walrus blobs on Sui	IPFS + Filecoin deals	AWS S3 / R2 / MinIO	Local folder
Needs	`LIGHTHOUSE_API_KEY`	`LIGHTHOUSE_API_KEY`	`S3_BUCKET` (+ endpoint/creds)	`dir` (or `MEMORY_DIR`)
Gateway	`gateway-walrus.lighthouse.storage`	`gateway.lighthouse.storage`	`S3_PUBLIC_BASE_URL` or `s3://…`	`file://…`
Walrus blob IDs	Yes	-	-	-

See Choose a Network for guidance, and Rebuild & Recovery for the pointer service.

warning

Batched blobs and index snapshots are stored unencrypted anyone with a CID can read them. Don't store secrets. Native encryption is under development until then, encrypt sensitive data on your end before storing, or use Memwal (SEAL-encrypted blobs).

Get Started

Head to the Quick Start to store your first agent memory in a few minutes, or browse the How To guides for storing and recalling.

What is Lighthouse Memory?​

The three layers​

What You Can Do​

How It Works​

Storage networks​

Get Started​