@contextwindow/sdk

Persistent memory for AI agents. Store, recall, and manage user context across conversations.

Early Access — ContextWindow is in early access. The API is stable but we're actively adding features. Found a bug or have a feature request? Report it here.

Install

npm install @contextwindow/sdk

Quick Start

import { ContextWindow } from '@contextwindow/sdk';

const cw = new ContextWindow({ apiKey: 'cw_...' });
const user = cw.withUser('user_123');

// Store memories
await user.remember([
  { content: 'Prefers dark mode', type: 'preference' },
  { content: 'Works at Acme Corp', type: 'fact' },
]);

// Recall relevant memories
const { memories } = await user.recall('What does the user prefer?');
console.log(memories[0].content); // "Prefers dark mode"
console.log(memories[0].score);   // 0.94

// Get a formatted string ready for your system prompt
const context = await user.recallForPrompt('user context');
// "You know this about the user:\n- Prefers dark mode\n- Works at Acme Corp"

Use with OpenAI

import { ContextWindow, openaiTools, handleToolCall } from '@contextwindow/sdk';
import OpenAI from 'openai';

const cw = new ContextWindow({ apiKey: 'cw_...' });
const user = cw.withUser('user_123');
const openai = new OpenAI();

// Give the AI memory abilities
const res = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Remember that I like sushi' }],
  tools: openaiTools,
});

// Execute tool calls automatically
for (const tc of res.choices[0].message.tool_calls ?? []) {
  await handleToolCall(user, tc.function.name, JSON.parse(tc.function.arguments));
}

Use with Claude

import { ContextWindow, claudeTools, handleToolCall } from '@contextwindow/sdk';
import Anthropic from '@anthropic-ai/sdk';

const cw = new ContextWindow({ apiKey: 'cw_...' });
const user = cw.withUser('user_123');
const anthropic = new Anthropic();

const res = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Remember that I like sushi' }],
  tools: claudeTools,
});

for (const block of res.content) {
  if (block.type === 'tool_use') {
    await handleToolCall(user, block.name, block.input);
  }
}

Ingest Conversations

Send full conversations and let ContextWindow extract facts automatically:

await user.ingest([
  { role: 'user', content: 'I just moved to Tokyo' },
  { role: 'assistant', content: "That's exciting!" },
  { role: 'user', content: "I'm starting at Google next month" },
]);

// Automatically extracts:
// → "User moved to Tokyo" (event)
// → "User starting at Google" (fact)

Smart Routing

Route messages to the optimal model automatically. Simple messages go to a fast, cheap model. Complex messages go to a powerful model. The SDK detects your provider (OpenAI or Anthropic) and picks the right model for each.

// No model needed — smart routing is on by default
const result = await user.runWithTools({
  client: anthropic,
  // autoRoute is on by default — picks the best model per message
  messages: [{ role: 'user', content: 'Hi, I need to refill my prescription' }],
  tools: [...claudeTools, ...myTools],
  onToolCall: (name, args) => handleMyTool(name, args),
});

// Force a specific model when needed:
const result2 = await user.runWithTools({
  client: anthropic,
  model: 'claude-sonnet-4-6',  // model takes priority over autoRoute
  messages: [...],
  tools: [...],
});

For plan limits, classification details, and full configuration: Smart Routing docs →

API Methods

| Method | Description | |--------|-------------| | withUser(userId) | Create a scoped client — no need to pass userId on every call | | remember(facts) | Store facts, preferences, events | | recall(query, options?) | Semantic search over memories | | recallForPrompt(query) | Recall + format as system prompt string | | forget(options) | Delete by ID or filter | | ingest(conversation) | Extract facts from conversations automatically | | list(options?) | Paginated listing with filters | | route(message) | Smart model routing — returns tier + recommended model | | usage() | Current plan usage and limits |

Configuration

const cw = new ContextWindow({
  apiKey: 'cw_...',                              // Required
  baseUrl: 'https://api.mycontextwindow.com',     // Optional (default)
  debug: false,                                   // Optional — log SDK activity
  retry: {                                        // Optional — built-in retry
    maxRetries: 3,                                // Default: 3
    initialDelay: 500,                            // Default: 500ms
    maxDelay: 10000,                              // Default: 10s
  },
});

Documentation

For advanced configuration, all method parameters, response types, and integration guides:

Read the full documentation →

License

MIT