🧩 SDK Overview

The Memory SDK is a set of published @lighthouse-ai/* npm packages that gives agents three primitives - remember / recall / forget - over swappable engines, storages, and embedders. No cloning - install what you need:

npm install @lighthouse-ai/core @lighthouse-ai/engine-batched @lighthouse-ai/store-local-fs @lighthouse-ai/embed-keyword
# add more as needed: @lighthouse-ai/store-lighthouse @lighthouse-ai/store-s3 @lighthouse-ai/embed-local @lighthouse-ai/engine-memwal @lighthouse-ai/cloud-sync

Packages

Package	Role	Import
@lighthouse-ai/core	Interfaces, factory, registry, CID, scoring. Zero network deps.	import { createStorage, createEmbedder } from '@lighthouse-ai/core'
@lighthouse-ai/engine-batched	DIY engine: you embed locally, memories buffer and flush as one blob per flushEvery	import { BatchedEngine } from '@lighthouse-ai/engine-batched'
@lighthouse-ai/engine-memwal	Relayer engine: embed + SEAL-encrypt + search in the Walrus relayer	import { MemwalMemory } from '@lighthouse-ai/engine-memwal'
@lighthouse-ai/store-local-fs	Local folder adapter	import '@lighthouse-ai/store-local-fs'
@lighthouse-ai/store-lighthouse	Lighthouse Walrus / Filecoin adapter	import '@lighthouse-ai/store-lighthouse'
@lighthouse-ai/store-s3	S3 / R2 / MinIO adapter	import '@lighthouse-ai/store-s3'
@lighthouse-ai/embed-local	On-device MiniLM vectors	import '@lighthouse-ai/embed-local'
@lighthouse-ai/embed-keyword	Keyword-only, zero deps	import '@lighthouse-ai/embed-keyword'
@lighthouse-ai/cloud-sync	Pointer-service client (backupIndex / restoreIndex)	import { backupIndex, restoreIndex } from '@lighthouse-ai/cloud-sync'

core never imports the others. Adding a layer is one registerStorage / registerEmbedder call (see Core & Factory).

Composition pattern

Side-effect imports self-register each package so the factory can find it. You can also pass an instance directly.

import '@lighthouse-ai/store-lighthouse'
import '@lighthouse-ai/embed-local'
import { createStorage, createEmbedder } from '@lighthouse-ai/core'
import { BatchedEngine } from '@lighthouse-ai/engine-batched'

// Factory + registry path
const storage = await createStorage('lh-ipfs-filecoin', { apiKey: process.env.LIGHTHOUSE_API_KEY })
const embedder = await createEmbedder('local')
const memory = new BatchedEngine(storage, { namespace: 'demo', embedder })

// Direct-instance path (same result, no registry lookup)
import { LocalFsStorage } from '@lighthouse-ai/store-local-fs'
const memory2 = new BatchedEngine(new LocalFsStorage({ dir: './blobs' }), { namespace: 'demo', embedder: null })

Engines at a glance

Engine	Who embeds / searches / encrypts	Batching	Needs
batched	You supply the embedder; engine batches into one blob per flushEvery (default 10, min 1) on any storage	Yes - flush() / auto-flush	storage + embedder (defaults: lh-ipfs-filecoin + local)
memwal	Relayer embeds, SEAL-encrypts, and searches; you keep tags/CIDs locally	No - every remember goes straight to the relayer	MEMWAL_PRIVATE_KEY + MEMWAL_ACCOUNT_ID

import { MemwalMemory } from '@lighthouse-ai/engine-memwal'
const memwal = await MemwalMemory.fromEnv() // MEMWAL_* + optional LIGHTHOUSE_API_KEY

Common engine interface (MemoryEngine)

Both engines implement:

remember(content, opts?) // { tags?, metadata? } -> RememberResult
recall(query, opts?)     // { tags?, limit? } (+ memwal: { maxDistance? })
list(opts?)              // { limit? } (+ memwal: { tags? })
get(idOrCid)             // full record
forget(idOrCid)          // { removed, blobDeleted?, note }
status()                 // engine, namespace, counts, index state
flush?()                 // batched only
rebuild?()               // batched: from blobs
snapshotIndex?()         // both: one CID for the whole local index
rebuildLocal?(cid)       // both: merge a snapshot CID

Memwal adds analyze(), verify(), blobIds(), restore(), and repinPending() - see Memwal Engine.

Local state

Everything saved lives in .memory-sdk/ in the folder you run from (git-ignored):

.memory-sdk/
  <namespace>.index.json   # batched search index: entries + pending queue
  blobs/                   # local-fs blobs (batch JSON + CID pointers)
  memwal/                  # memwal local index (<network>.<namespace>.index.json)

Writes are atomic (tmp file + rename); a missing index just starts empty. Relocate with MEMORY_DIR (batched) or MEMWAL_MEMORY_DIR (memwal). To back the batched index with something else (e.g. Dynamo in the hosted API), pass indexStore to BatchedEngine - it satisfies the IndexStore interface (path, load(), save()).

The cloud-sync auth token is a credential and lives separately at ~/.memory-sdk-cloud/token (mode 0600).

Where to go next

• Core & Factory - createStorage, createEmbedder, registry, MemoryRecord / RecallMatch types
• Batched Engine - every method, return shape, and batching rules
• Memwal Engine - relayer methods, pinning, verification
• Storages - local-fs, s3, lh-ipfs-* options and capabilities
• Embedders - local vs keyword vs remote, scoring formula
• Cloud Sync - backupIndex / restoreIndex pointer client
• Configuration - full env-var table