💾 Store Memories

Store information durably with remember. Memories buffer locally as pending and upload in batches — one blob per flushEvery memories (default 10), which also carries a full index snapshot for recovery.

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

const memory = Memory.fromEnv()

const result = await memory.remember(
  'Customer ACME is on the enterprise plan; escalations go to the sev-1 channel.',
  {
    tags: ['customer', 'escalation'],          // optional, used for filtered recall
    metadata: { source: 'support-bot' },       // optional structured payload
  }
)

console.log(result)
// {
//   id: '80cc2055-…',        // memory id (UUID)
//   flushed: false,          // true when this write triggered a batch upload
//   pendingCount: 1          // memories still buffered locally
// }

Flushing

Pending memories are searchable immediately but live only on the local machine until flushed:

const flushed = await memory.flush()
// { flushedMemories: 3, cid: 'Qm…', gatewayUrl: 'https://gateway…/ipfs/Qm…' }

Flush happens automatically once flushEvery memories are pending. Tune it with the MEMORY_FLUSH_EVERY environment variable — 1 uploads on every write (maximum durability), higher values pack more memories per blob (maximum quota efficiency).

Why batching matters on Walrus

Walrus erasure-codes every blob, so each upload counts ~63 MB against your account quota regardless of its actual size. One batch blob holding many memories costs the same quota as one holding a single memory.

Configuration

Env var	Default	Purpose
LIGHTHOUSE_API_KEY	— (required)	Lighthouse API key
MEMORY_NETWORK	ipfs-walrus	ipfs-walrus or ipfs-filecoin
MEMORY_NAMESPACE	default	Isolates memories per agent/project
MEMORY_AGENT	agent	Agent id recorded on each memory
MEMORY_FLUSH_EVERY	10	Batch size before automatic flush
MEMORY_EMBEDDINGS	local	off disables semantic search
MEMORY_DIR	~/.lighthouse-memory	Local index location

What gets stored

Each memory is a JSON record inside the batch blob:

{
  "v": 1,
  "id": "80cc2055-9256-40b9-af83-5ecf8ea522ce",
  "namespace": "default",
  "agent": "support-bot",
  "content": "Customer ACME is on the enterprise plan; …",
  "tags": ["customer", "escalation"],
  "metadata": { "source": "support-bot" },
  "createdAt": "2026-07-22T14:59:03.427Z",
  "embedding": [0.0123, -0.0456, "…"],
  "embeddingModel": "local:Xenova/all-MiniLM-L6-v2"
}

Anyone with the batch CID can read it from the gateway — do not store secrets.