Lighthouse Memory

Durable long-term memory for AI agents, stored on Walrus via the Lighthouse x Walrus integration — or on Lighthouse's standard IPFS + Filecoin network, selectable per store with the network parameter (ipfs-walrus | ipfs-filecoin).

Agents get remember / recall / forget primitives whose contents live as verifiable blobs on the Walrus network (on Sui), addressed by IPFS-compatible CIDs, and retrievable through Lighthouse gateways. Memory survives sessions, machines, and runtimes.

How it works

agent ──(MCP tools / TS API)──► Memory
                                   │
                     ┌─────────────┼──────────────────┐
                     ▼             ▼                  ▼
              memory blob    local search index   index snapshot
              (JSON on       (~/.walrus-agent-    (also on Walrus,
               Walrus, CID)    memory/*.json)       for recovery)

• Memories are batched into immutable JSON blobs on Walrus, uploaded through upload-walrus.lighthouse.storage and readable by anyone with the CID at https://gateway-walrus.lighthouse.storage/ipfs/<CID>. Writes buffer locally as pending and flush as one blob per flushEvery memories (default 10) — each blob also carries a full index snapshot, so a flush is simultaneously a backup. Pending memories are searchable immediately but live only on the local machine until flushed (flush() / memory_flush).
• A local index (content, tags, CIDs, embedding vectors) makes recall fast without network round trips.
• Semantic recall by default: memories are embedded locally with all-MiniLM-L6-v2 (via @huggingface/transformers, ~25 MB model downloaded once, no API key, nothing leaves the machine). Recall ranks by 0.7 × cosine similarity + 0.3 × keyword/tag overlap; memories stored before embeddings existed are embedded lazily on first recall. If the model can't load, recall degrades to keyword scoring.
• Every batch blob embeds the full index, so the index can be rebuilt from the network (rebuild) — restore full memory on a brand-new machine from just your API key. Legacy one-blob-per-memory files and standalone snapshots from older versions are still read.
• Walrus-native blob IDs for any memory are available via blobIds() for Sui ecosystem tooling.

Note: memories are stored unencrypted in this version — anyone with a CID can read it. Lighthouse's encrypted-upload support for Walrus is "coming soon" in their docs; don't store secrets in the meantime.

Setup

1. Get a Lighthouse Walrus API key

1. Open the Lighthouse Walrus Dashboard and sign in with a Sui wallet (Slush).
2. Go to API Keys, create a key, and copy it.

(Programmatic alternative: sign an auth message with a Sui keypair — see Create an API Key.)

2. Install

npm install
npm test        # offline smoke test, no API key needed

3. Configure

| Env var | Required | Default | Purpose | | --- | --- | --- | --- | | LIGHTHOUSE_API_KEY | yes | — | Lighthouse API key | | MEMORY_NETWORK | no | ipfs-walrus | Storage backend: ipfs-walrus or ipfs-filecoin (aliases walrus/filecoin accepted) | | MEMORY_NAMESPACE | no | default | Isolates memories per agent/project | | MEMORY_AGENT | no | agent | Agent id recorded on each memory | | MEMORY_DIR | no | ~/.lighthouse-memory | Local index location | | MEMORY_FLUSH_EVERY | no | 10 | Upload a batch blob once this many memories are pending (1 = upload on every write) | | MEMORY_EMBEDDINGS | no | local | Set off to disable semantic search (keyword-only) |

Use as MCP server (any agent, automatically)

Run the server over stdio:

LIGHTHOUSE_API_KEY=lh_... npm run mcp

Add to Claude Code:

claude mcp add walrus-memory \
  --env LIGHTHOUSE_API_KEY=lh_... \
  -- npx tsx /path/to/Memory-1/src/mcp-server.ts

The agent then has these tools and will store/recall memory on Walrus on its own:

| Tool | What it does | | --- | --- | | memory_remember | Store content (+tags, metadata); buffers locally, flushes to Walrus in batches | | memory_flush | Force all pending memories onto Walrus as one batch blob now | | memory_recall | Semantic + keyword search over memories (flushed and pending), optional tag filter | | memory_list | Newest-first listing | | memory_get | Fetch the full record from Walrus by id or CID | | memory_forget | Remove from index; deletes the blob once no other memory shares it | | memory_rebuild_index | Restore the index from Walrus on a new machine | | memory_status | Namespace, count, index path, last snapshot CID |

Use as a library

import { Memory, LighthouseClient } from '@lighthouse-web3/memory'

const memory = new Memory(
  new LighthouseClient(process.env.LIGHTHOUSE_API_KEY!, {
    network: 'ipfs-walrus', // or 'ipfs-filecoin'
  }),
  { namespace: 'support-bot', agent: 'triage-agent' }
)

const stored = await memory.remember(
  'Customer ACME is on the enterprise plan; escalations go to the sev-1 channel.',
  { tags: ['customer', 'escalation'] }
)
// stored.cid → IPFS-compatible CID, backed by a Walrus blob on Sui
// stored.gatewayUrl → https://gateway-walrus.lighthouse.storage/ipfs/<CID>

const matches = await memory.recall('how do I escalate for ACME?')
const record = await memory.get(matches[0].id)     // full record from Walrus
const blobIds = await memory.blobIds(matches[0].id) // Walrus-native blob IDs

Live demo (uploads real blobs):

LIGHTHOUSE_API_KEY=lh_... npm run demo

Durability model

| Failure | Recovery | | --- | --- | | Session ends | Flushed memories are on Walrus; pending memories are in the local index — nothing lost | | Local machine lost before flush | Pending (unflushed) memories are gone — call memory_flush before ending important sessions, or set MEMORY_FLUSH_EVERY=1 | | Local index deleted | rebuild() restores from the newest batch blob's embedded index snapshot | | Snapshots unreadable | rebuild() falls back to re-reading every memory blob via the Lighthouse file list | | New machine | Set LIGHTHOUSE_API_KEY, run memory_rebuild_index |

Deletion (forget) stops Lighthouse from renewing Walrus storage for that blob; the content remains readable until the current storage period expires, then is reclaimed.

Choosing a network

| | ipfs-walrus (default) | ipfs-filecoin | | --- | --- | --- | | Backing | Walrus blobs on Sui | IPFS + Filecoin deals | | Gateway | gateway-walrus.lighthouse.storage | gateway.lighthouse.storage | | Quota accounting | ~63 MB per blob (erasure coding) | Actual file size | | Walrus blob IDs | Yes (blobIds()) | No (returns []) |

Each network keeps its own local index per namespace, so the same namespace on both networks never mixes. Memories written to one network are recalled/rebuilt from that network only.

Storage quota caveat (free tier)

Walrus erasure-codes every blob, so each upload counts ~63 MB against your Lighthouse Walrus quota regardless of its actual size (walrusFileSizeInBytes in the file list). The free tier is ~100 MB — roughly one blob. Batching is how this stays workable: one blob carries flushEvery memories and the index snapshot. Raise MEMORY_FLUSH_EVERY to pack more memories per blob (a blob holds tens of thousands of memories before its real size matters), or buy storage in the Lighthouse dashboard (DataCap / x402 stablecoin payments).

References

• Walrus Memory product page — Mysten's own hosted memory layer (memwal SDKs); this project is a self-hosted alternative built directly on Lighthouse x Walrus storage
• Lighthouse IPFS-Walrus docs
• Lighthouse Walrus dashboard