Skip to main content

🔍 Recall Memories

recall searches all memories — flushed and pending — and returns the best matches. Search runs fully locally against the index; no network round trips.

const matches = await memory.recall('how do I escalate for ACME?', {
  tags: ['customer'],   // optional: only memories carrying at least one of these tags
  limit: 5,             // default 5
})

console.log(matches[0])
// {
//   id: '80cc2055-…',
//   content: 'Customer ACME is on the enterprise plan; …',
//   score: 0.62,            // final ranking score
//   semanticScore: 0.71,    // cosine similarity (0..1)
//   keywordScore: 0.41,     // keyword/tag overlap
//   tags: ['customer', 'escalation'],
//   cid: 'Qm…',
//   gatewayUrl: 'https://gateway…/ipfs/Qm…'
// }

How scoring works​

With embeddings on (the default):

score = 0.7 × cosine(query, memory) + 0.3 × min(1, keywordScore)
  • Semantic component — both query and memories are embedded locally with all-MiniLM-L6-v2 (runs in-process via ONNX; the ~25 MB model downloads once, and no content leaves the machine). This is what lets "which hosting platform is used for releases?" find "deploys to Vercel on the main branch" with zero shared keywords.
  • Keyword component — matching content words dampened by memory length (hits / √words), plus +0.5 for each tag that appears in the query.
  • Ties break by recency.

Memories stored before embeddings were enabled are embedded lazily on first recall, then persisted.

If the embedding model cannot load (e.g. offline on first use), recall degrades gracefully to pure keyword scoring — status() reports which mode is active.

Other read operations​

await memory.list({ limit: 20 })   // newest first, flushed + pending
await memory.get(idOrCid)          // full record (content, tags, metadata) by id or CID
await memory.status()              // counts, pending, network, embeddings mode
await memory.blobIds(idOrCid)      // Walrus-native blob IDs (ipfs-walrus only)

Every flushed memory is also readable by anyone directly from the gateway:

curl https://gateway-walrus.lighthouse.storage/ipfs/<CID>