MemoryKit

TypeScript SDK

Official TypeScript/JavaScript SDK for MemoryKit. Zero dependencies, full type safety.

Zero deps

Native fetch only — no axios, no node-fetch.

Typed errors

Every error is an instanceof check. No string matching.

globeEdge-ready

Works in Node.js, Bun, Deno, Cloudflare Workers, Vercel Edge.

Installation

npm install memorykit

Requires Node.js 18+. TypeScript 5.0+ is optional — works with plain JavaScript too.

Quick start

Install and initialize

import { MemoryKit } from "memorykit";
 
const mk = new MemoryKit({
  apiKey: process.env.MEMORYKIT_API_KEY,
});

Store a memory

const memory = await mk.memories.create({
  content: "User prefers dark mode and metric units.",
  tags: ["preferences"],
  userId: "user_123",
});
const results = await mk.memories.search({
  query: "What does the user prefer?",
  limit: 5,
});
for (const hit of results.results) {
  console.log(`[${hit.score.toFixed(2)}] ${hit.content}`);
}

Configuration options

const mk = new MemoryKit({
  apiKey: "ctx_...",
  baseUrl: "https://api.memorykit.io/v1", // default
  timeout: 30_000,    // ms, default 30s
  maxRetries: 3,      // automatic retries on 429/5xx
});

Memories

Create and manage

// Create
const memory = await mk.memories.create({
  content: "Meeting notes from Q4 planning...",
  title: "Q4 Planning",
  tags: ["meetings", "q4"],
  userId: "user_123",
});
 
// List with pagination
const page = await mk.memories.list({ limit: 20, status: "completed" });
console.log(page.data.length, "memories");
if (page.hasMore) {
  const next = await mk.memories.list({ cursor: page.cursor });
}
 
// Get by ID
const mem = await mk.memories.get("mem_abc123");
 
// Update
await mk.memories.update("mem_abc123", {
  title: "Updated Title",
  tags: ["meetings", "q4", "important"],
});
 
// Delete
await mk.memories.delete("mem_abc123");

Upload files

Supports PDF, DOCX, XLSX, PPTX, TXT, CSV, Markdown, HTML, and JSON.

const file = new File([buffer], "report.pdf", { type: "application/pdf" });
await mk.memories.upload({ file, title: "Q4 Report", userId: "user_123" });

Batch ingest

Up to 100 memories in a single request.

const result = await mk.memories.batchIngest({
  items: [
    { content: "First fact", tags: ["facts"] },
    { content: "Second fact", tags: ["facts"] },
  ],
});
console.log(`${result.accepted} accepted, ${result.rejected} rejected`);

Reprocess

Triggers re-chunking and re-embedding for an existing memory.

await mk.memories.reprocess("mem_abc123");

Search

Combines vector similarity, full-text search, and reranking.

const results = await mk.memories.search({
  query: "quarterly revenue targets",
  limit: 10,
  tags: "finance",
  precision: "high",
});
for (const hit of results.results) {
  console.log(`[${hit.score.toFixed(2)}] ${hit.title}`);
}

RAG query

Coming Soon — memories.query() is not available in the current SDK release. Use memories.search() for retrieval. LLM-powered query with answer generation will be available in a future release.

Streaming

Coming Soon — memories.stream() is not available in the current SDK release. Use memories.search() for retrieval. Streaming responses will be available in a future release.

Chats

Coming Soon — Chat methods (chats.create(), chats.sendMessage(), chats.streamMessage(), chats.getHistory()) are not available in the current SDK release. Conversational RAG with chat sessions will be available in a future release.

Users

// Upsert (create or update)
await mk.users.upsert({
  id: "user_123",
  name: "Alice",
  email: "alice@example.com",
  metadata: { plan: "pro" },
});
 
// Track events
await mk.users.createEvent("user_123", {
  type: "page_view",
  data: { page: "/settings" },
});
 
// GDPR erasure — delete user and all associated data
await mk.users.delete("user_123", { cascade: true });

Webhooks

// Subscribe to events
const webhook = await mk.webhooks.create({
  url: "https://example.com/webhook",
  events: ["memory.completed", "memory.failed"],
});
console.log("Signing secret:", webhook.secret);
 
// Test delivery
const test = await mk.webhooks.test(webhook.id);
console.log("Delivered:", test.success);

Error handling

All errors are typed — use instanceof to handle specific cases:

import {
  MemoryKitError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
} from "memorykit";
 
try {
  const result = await mk.memories.search({ query: "..." });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — invalid or expired API key
  } else if (error instanceof RateLimitError) {
    // 429 — back off, retryAfter tells you how long
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    // 400/422 — check error.errors for field-level details
    console.log(error.errors);
  } else if (error instanceof NotFoundError) {
    // 404
  } else if (error instanceof MemoryKitError) {
    // catch-all for other API errors
    console.log(error.statusCode, error.message);
  }
}

Retryable errors (429, 5xx) are automatically retried with exponential backoff up to maxRetries times. You don't need to implement retry logic yourself.

Runtime compatibility

RuntimeStatusNotes
Node.js 18+✅Full support
Bun✅Full support
Deno✅import { MemoryKit } from "npm:memorykit"
Cloudflare Workers✅Edge-compatible
Vercel Edge✅Edge-compatible
Browser⚠️Works, but exposes your API key — use a server proxy
npm

Package on npm

GitHub

Source code

Changelog

Release notes

Edit on GitHub

Previous

Build a personal assistant

Next

Python SDK

On this page