@ledgermem/memory

Official TypeScript / JavaScript SDK for LedgerMem Memory — long-term memory infrastructure for AI agents.

npm install @ledgermem/memory

Zero runtime dependencies. Works in Node 18+, Bun, Deno, browsers, Cloudflare Workers, and any other modern JS runtime with fetch.

Quickstart

import { LedgerMem } from '@ledgermem/memory'

const memory = new LedgerMem({
  apiKey: process.env.LEDGERMEM_API_KEY!,
  workspaceId: process.env.LEDGERMEM_WORKSPACE_ID!,
})

// Store an atomic fact
await memory.add({ content: 'User prefers Japanese short-grain rice for onigiri.' })

// Retrieve relevant facts
const { hits } = await memory.search({ query: 'what kind of rice does the user like?' })
for (const hit of hits) {
  console.log(hit.score.toFixed(2), hit.content)
}

API surface

| Method | Purpose | |---|---| | search({ query, limit?, actorId? }) | Hybrid 7-strategy retrieval. Returns SearchResponse. | | add({ content, metadata?, actorId? }) | Store an atomic fact. Returns Memory. | | update(id, { content?, metadata? }) | Patch existing memory. | | delete(id) | Remove a memory. | | list({ limit?, cursor?, actorId? }) | Cursor-paginated list. |

Errors

All HTTP failures throw LedgerMemHTTPError with .status and .body. Aborted requests throw LedgerMemTimeoutError. Both inherit from LedgerMemError.

import { LedgerMem, LedgerMemHTTPError } from '@ledgermem/memory'

try {
  await memory.search({ query: 'rice' })
} catch (err) {
  if (err instanceof LedgerMemHTTPError && err.status === 401) {
    console.error('API key rejected:', err.body)
  } else {
    throw err
  }
}

Configuration

| Option | Default | Notes | |---|---|---| | apiKey | (required) | from https://app.proofly.dev/settings/api-keys | | workspaceId | (required) | from the dashboard URL | | actorId | none | optional default actor scope | | baseUrl | https://api.proofly.dev | override for self-hosted | | timeoutMs | 30000 | per-request abort timeout | | fetch | global fetch | inject for testing or proxying |

Develop

npm install
npm test
npm run build

License

MIT