♻️ Rebuild & Recovery
The local search index is a cache — the source of truth is on the network. Every batch blob embeds a full index snapshot, so the entire memory store can be reconstructed from just your API key.
const memory = Memory.fromEnv()
const result = await memory.rebuild()
// { restored: 42, source: 'snapshot' }
Or via MCP: ask the agent to run memory_rebuild_index.
How rebuild works
- Lists your account's files on the selected network.
- Loads the newest batch blob's embedded index snapshot (embedding vectors included — no re-embedding needed).
- Merges in records from any blobs newer than that snapshot, including legacy one-record-per-blob files from older versions.
- Writes the restored index locally; recall works immediately.
If no snapshot exists at all, rebuild falls back to re-reading every memory blob (source: 'blobs').
Durability model
| Failure | Recovery |
|---|---|
| Session ends | Flushed memories are on the network; pending memories are in the local index — nothing lost |
| Local machine lost before flush | Pending (unflushed) memories are gone — flush before ending important sessions, or set MEMORY_FLUSH_EVERY=1 |
| Local index deleted | rebuild() restores from the newest batch snapshot |
| Snapshots unreadable | rebuild() falls back to re-reading every memory blob |
| New machine | Set LIGHTHOUSE_API_KEY, run rebuild() |
Forgetting memories
await memory.forget(id)
// { removed: true, blobDeleted: false }
- A pending memory is simply dropped locally.
- A flushed memory is removed from the index. Because batched memories share one blob, the underlying file is deleted from Lighthouse only when no other memory references it (
blobDeleted: true). Until then, the forgotten content remains inside the shared blob on the network. - On Walrus, deletion stops storage renewal — content remains readable until the current storage period expires, then is reclaimed. Deletion is irreversible after that.