🗂️ 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.
• 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, 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.

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…'
// }

// 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).