👋 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 blob on Walrus (via Lighthouse IPFS Walrus) or on Lighthouse's standard IPFS + Filecoin network, addressed by an IPFS-compatible CID.
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 Lighthouse API key.
What You Can Do
- Store memories durably — facts, decisions, preferences, and context are written to decentralized storage and retrievable by CID from public gateways.
- Recall by meaning — semantic search runs locally with an in-process embedding model (no extra API key, nothing leaves the machine), combined with keyword and tag matching.
- Connect any agent via MCP — a bundled Model Context Protocol server exposes memory as tools for Claude Code, Claude Desktop, and any MCP-capable agent.
- Batch writes to save quota — memories buffer locally and flush as one blob carrying both the new records and a full index snapshot.
- Recover from nothing — rebuild the local search index entirely from the network.
How It Works
agent ──(MCP tools / TypeScript API)──► Memory
│
┌──────────────────┼─────────────────────┐
▼ ▼ ▼
batch blob local search index embedded index
(memories JSON (content, tags, snapshot (inside
on Walrus or vectors — fast every batch blob,
IPFS/Filecoin) local recall) for recovery)
- Remember — the agent stores content (plus tags and metadata). The memory is embedded locally and buffered as pending.
- Flush — pending memories upload as one batch blob that also carries a complete index snapshot, so every flush doubles as a backup.
- Recall — queries rank memories by a hybrid of cosine similarity and keyword/tag overlap, over both flushed and pending memories.
- Rebuild — on a new machine, the index is restored from the newest batch blob (or by re-reading every memory blob).
Storage Networks
ipfs-walrus (default) | ipfs-filecoin | |
|---|---|---|
| Backing | Walrus blobs on Sui | IPFS + Filecoin deals |
| Gateway | gateway-walrus.lighthouse.storage | gateway.lighthouse.storage |
| Walrus blob IDs | Yes | — |
See Choose a Network for guidance.
Memories are stored unencrypted — anyone with a CID can read them. Don't store secrets. Encrypted memory will follow Lighthouse's encrypted-upload support.
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, recalling, and connecting agents over MCP.
Source code: github.com/lighthouse-web3/memory