🗂️ Manage Memories - List, Get, Forget, Status

Beyond remember and recall, both engines expose the same four management calls. Shapes differ slightly per engine - this page covers each one with its return type.

list() - browse newest first

// batched: no tag filter here - filter client-side or use recall({ tags })
await memory.list({ limit: 20 })

// memwal: native tag filter
await memory.list({ limit: 20, tags: ['preference'] })

• Returns newest first, flushed and pending (batched) or all indexed entries (memwal).
• Scores are 0 - this is for browsing, not ranking. Use recall() when order matters.
• Memwal items include walrusUrl, cid, pinned, and gatewayUrl; batched items include cid, batchId, pending, and gatewayUrl.

const items = await memory.list({ limit: 5 })
console.log(items[0])
// batched: { id, cid, batchId, content, tags, agent, createdAt, sizeBytes, pending?, score: 0, keywordScore: 0, gatewayUrl? }
// memwal:  { id, blobId, cid, content, tags, createdAt, pinned, gatewayUrl?, walrusUrl, network, namespace }

get() - full record by id or CID

await memory.get(stored.id) // UUID (batched) or relayer job id (memwal)
await memory.get('baf…')     // batch/snapshot CID (batched) or record CID (memwal)
await memory.get('walrus-blob-id') // memwal only

• Batched returns the full MemoryRecord (with embedding / embeddingModel when the local embedder was active). It checks pending → index → storage fetch, and throws Memory <ref> not found in batch <cid> when the id is absent from the referenced blob.
• By batch CID, get() and forget() act on one record only - the first index entry stored in that batch. A batch usually holds up to flushEvery memories, so get(batchCid) returns just the first of them and forget(batchCid) removes just that one (the blob is kept because the others still reference it). Use memory ids to target a specific record, and list() to see what a batch contains. On a machine whose local index has never seen the CID, get(batchCid) throws Memory <cid> not found in batch <cid>.
• Memwal returns the MemoryIndexEntry ({ record, cid, pinned, sizeBytes, gatewayUrl? }). Unknown local refs fall back to a gateway fetch for pinned CIDs; otherwise it throws and suggests recall() - memories written from other machines are semantically recallable without a local record.

forget() - remove a memory

await memory.forget(idOrCid)
// batched: { removed, blobDeleted?, note }
// memwal:  { removed, blobDeleted, note }

Case	What happens
Batched, pending	Dropped locally, never uploaded (blobDeleted: false)
Batched, by batch CID	Only the first record in that batch is forgotten - the rest stay, and so does the blob. Forget by memory id instead
Batched, flushed	Removed from the index. Backing blob deleted only when no other memory references it. S3/local-fs = hard delete; Lighthouse = stops renewal (readable until expiry)
Memwal	Local copy removed + IPFS mirror unpinned. The relayer has no delete API - the encrypted blob lapses on its own and may still surface in recall() as indexed: false

removed: false means the id was not found in the local index - nothing changed.

warning

Forgetting a flushed batched memory does not erase it. forget() only edits the local index - it records no tombstone. Until its whole batch blob is deleted:

• The record stays in the blob. If other memories share the batch, the blob is kept and the record's content stays readable to anyone with the CID (batch blobs are plaintext).
• It comes back on rebuild(). Rebuild re-reads every batch blob, so a forgotten record in a kept blob is restored to the index.
• It stays in earlier snapshots. Any snapshotIndex() CID taken before the forget still contains it, and rebuildLocal() / restoreIndex() from that snapshot restores it. Take a fresh snapshot (and back it up) after forgetting.

Even when the blob is deleted, Lighthouse storage only stops renewal, and copies already fetched through public IPFS gateways may persist. Don't store anything you may need to truly erase - see the encryption warning in the Introduction.

status() - inspect the store

// batched
await memory.status()
// {
//   engine: 'batched', storage: 'lh-ipfs-filecoin', namespace: 'demo', agent: 'agent',
//   memories: 42, pendingMemories: 3, flushEvery: 10,
//   embeddings: 'local:Xenova/all-MiniLM-L6-v2' | 'keyword:off',
//   indexPath: '.memory-sdk/demo.index.json', lastSnapshotCid: 'baf…' // last batch CID, not a snapshot
// }

// memwal
await memory.status()
// {
//   network: 'mainnet', relayerUrl: 'https://…', relayer: 'ok (v…)',
//   dashboardUrl: 'https://…', namespace: 'demo', agent: 'agent',
//   memories: 12, pinnedMemories: 10, pendingPins: 2,
//   ipfs: 'lighthouse (pinned, publicly resolvable)' | 'local CIDs (computed, not pinned)',
//   indexPath: '.memory-sdk/memwal/mainnet.demo.index.json'
// }

Use status() to check pendingMemories before ending a session (batched), pendingPins after writes (memwal), and embeddings when recall quality drops (keyword fallback active).