MemoryAI — Node.js SDK

Persistent memory for AI agents and bots. Zero dependencies, native fetch (Node 18+).

npm install memoryai

Quick Start

import { MemoryAI } from 'memoryai';

const mem = new MemoryAI({ apiKey: 'hm_sk_...' });

await mem.store('khách thích màu đỏ', { tags: ['customer:123'], priority: 'hot' });
const results = await mem.recall('sở thích khách', { tags: ['customer:123'] });
console.log(results);

Bot Examples

Zalo Bot

import { MemoryAI } from 'memoryai';

const mem = new MemoryAI({
  apiKey: process.env.MEMORYAI_KEY!,
  graceful: true, // never crash the bot
});

async function handleMessage(userId: string, text: string) {
  // Recall context
  const memories = await mem.recall(text, { tags: [`zalo:${userId}`], limit: 3 });

  // ... send to LLM with memories as context ...

  // Store what you learned
  await mem.store(assistantReply, { tags: [`zalo:${userId}`], source: 'zalo-bot' });
}

Telegram Bot

```typescript
const mem = new MemoryAI({
  apiKey: process.env.MEMORYAI_KEY!,
  graceful: true,
});

bot.on('message', async (ctx) => {
  const userId = String(ctx.from.id);
  const context = await mem.bootstrap({ taskDescription: `telegram:${userId}` });
  // ... use context in your LLM prompt ...
  await mem.store(reply, { tags: [`tg:${userId}`] });
});

Shopee Bot

const mem = new MemoryAI({
  apiKey: process.env.MEMORYAI_KEY!,
  graceful: true,
  circuitBreaker: { threshold: 3, cooldownMs: 60_000 },
});

async function handleShopeeChat(shopId: string, buyerId: string, message: string) {
  const tag = `shopee:${shopId}:${buyerId}`;
  const memories = await mem.recall(message, { tags: [tag], limit: 5 });
  // ... generate reply with context ...
  await mem.store(reply, { tags: [tag], source: 'shopee' });
}

Graceful Mode

For bots that must never crash — graceful: true makes all methods return null (or [] for recall) instead of throwing on errors.

const mem = new MemoryAI({ apiKey: '...', graceful: true });

const result = await mem.store('test'); // null on error, StoreResult on success
const memories = await mem.recall('test'); // [] on error, MemoryResult[] on success

Circuit Breaker

Built-in circuit breaker prevents cascading failures. After N consecutive failures, the circuit opens and rejects requests immediately for a cooldown period.

// Default: 5 failures → open for 30s
const mem = new MemoryAI({ apiKey: '...' });

// Custom thresholds
const mem2 = new MemoryAI({
  apiKey: '...',
  circuitBreaker: { threshold: 3, cooldownMs: 60_000 },
});

// Disable circuit breaker
const mem3 = new MemoryAI({ apiKey: '...', circuitBreaker: false });

// Check state
mem.getCircuitState(); // 'CLOSED' | 'OPEN' | 'HALF_OPEN'
mem.resetCircuit();

Retry + Backoff

Automatic retry with exponential backoff for transient errors (429, 502, 503, 504, network errors). Default: 3 retries with [1s, 2s, 4s] backoff.

const mem = new MemoryAI({
  apiKey: '...',
  retries: 5, // max retries
  timeout: 15_000, // per-request timeout
});

Full API Reference

| Method | Description | |--------|-------------| | store(content, opts?) | Store a memory chunk | | storeCode(content, opts) | Store code with IDE metadata | | recall(query, opts?) | Search memories | | stats() | Usage statistics | | compact(content, opts?) | Compact text into memory | | compactProject(content, opts) | Compact code with file metadata | | indexProject(fileTree, opts?) | Index project file tree | | learn(opts) | Store action + result + lesson | | bootstrap(opts?) | Get context block for session start | | explore(chunkId, limit?) | Explore graph neighbors | | clusters(limit?) | Get topic clusters | | listEntities(opts?) | List tracked entities | | entityChunks(name, limit?) | Get chunks for an entity | | handoffStart(conversation, opts?) | Start session handoff | | handoffRestore(opts?) | Restore from handoff | | handoffComplete(opts?) | Complete handoff | | handoffStatus() | Check handoff status | | l2Store(bankName, content, opts?) | Store in reasoning bank (Pro+) | | l2Recall(query, opts?) | Recall from reasoning banks (Pro+) | | l2Compress(bankName) | Compress reasoning bank | | l2Stats() | Reasoning layer stats | | sessionRecover(opts?) | Recover session context | | contextMonitor(opts) | Monitor context window | | snapshotCreate() | Create memory snapshot | | snapshotList() | List snapshots | | snapshotRestore(id) | Restore from snapshot | | exportData() | Export all data | | importData(chunks) | Import data | | deleteData() | Delete all data | | healthDetailed() | Detailed health check |

Get API Key

Sign up at memoryai.dev to get your API key.

License

MIT