TypeScript SDK Reference.

The memosift package on npm. Tool-result interception, persistent memory, the MCP server, the CLI, and 8 framework adapters in one install.

Requires Node.js 20+. One package — includes the SDK, every framework adapter, the MCP server, the memosift CLI, and the bundled agent skill.

Pick your mode

Compare in detail

A — Inspector

Local-only primitives — classify, extract metadata, scan. No cloud, no API key.

Compliance · telemetry · routing

B — Sidecar

Track turns to the cloud, recall across sessions. No tool-result mutation.

Long-running agents · cross-session memory

C — Co-pilot

Track + recall + auto-stub large tool results in the model's view (≥2 KB).

Auto-everything · context-budget driven

By mode — code patterns

The same SDK serves all three integration modes. Pick the one your agent needs and use the matching pattern.

Mode A

Inspector

Local-only primitives — no cloud, no API key. Free under MIT.

// Pure local — no MemoSift instance needed
import { classify, extractMetadata, scan, SecurityMode } from "memosift";

const contentType = classify(myToolOutput);
const metadata = extractMetadata(myToolOutput, contentType);

const result = scan(myToolOutput, { mode: SecurityMode.REDACT });
console.log(result.content);   // secrets masked
console.log(result.findings);  // SecurityFinding[]

Mode B

Sidecar

Push turns to the cloud, recall across sessions. No tool-result mutation.

// Track + recall against the MemoSift cloud
import { MemoSift } from "memosift";

const ms = new MemoSift({
  apiKey: process.env.MEMOSIFT_API_KEY!,
  baseUrl: "https://dev.memosift.com",
});

// After each turn:
await ms.track(messages, { sessionId: "my-session" });

// When you need recall:
const result = await ms.recall("user's question", { sessionId: "my-session" });
for (const item of result.items) {
  console.log(item.content.slice(0, 120));
}

Mode C

Co-pilot

Adapter wraps the LLM client; large tool results auto-stub in the model's view.

// Tool results above ~2 KB are silently replaced with artifact stubs
import Anthropic from "@anthropic-ai/sdk";
import { MemoSift, wrapAnthropic } from "memosift";

const ms = new MemoSift({
  apiKey: process.env.MEMOSIFT_API_KEY!,
  baseUrl: "https://dev.memosift.com",
});
const client = wrapAnthropic(new Anthropic(), {
  memosift: ms,
  session: ms.session("my-session"),
});

// Use `client` exactly like the original Anthropic SDK.
const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [...],
});

Pro tier — getting an API key

Anything beyond Mode A (Inspector primitives) requires a MemoSift cloud account. The asynchronous extraction + reconciliation pipeline that powers track, recall, compress, and explore is hosted at https://dev.memosift.com.

Go to memosift.com and sign up.
Create a project from the dashboard.
Create an API key inside that project (it starts with msk_).
Configure your SDK to point at the cloud at https://dev.memosift.com.
Pass the key when constructing MemoSift({...}).
You're live — track, recall, compress, explore all work.

import { MemoSift } from "memosift";

const ms = new MemoSift({
  apiKey: process.env.MEMOSIFT_API_KEY!,        // the msk_... key from step 3
  baseUrl: "https://dev.memosift.com",          // the cloud URL from step 4
});

Quickstart

agent.ts

import { MemoSift } from "memosift";

const ms = new MemoSift({
  apiKey: process.env.MEMOSIFT_API_KEY!,
  baseUrl: "https://dev.memosift.com",
});

// After each agent turn:
await ms.track(
  [
    { role: "user", content: "find me CSV files" },
    { role: "assistant", content: "Found 3 CSVs." },
  ],
  { sessionId: "my-session" },
);

// When you want recall:
const result = await ms.recall("user's question", { sessionId: "my-session" });
for (const item of result.items) {
  console.log(item.content.slice(0, 120));
}

// When you want a structured context block:
const ctx = await ms.compress({ sessionId: "my-session" });
console.log(ctx.contextBlock);

Methods

Every method on the MemoSift class. Async-first; all calls return promises.

ms.track(messages, options)

Ship a conversation turn to the cloud. Queues locally if cloud is unreachable.

await ms.track(
  messages: Array<{ role: string; content: string }>,
  { sessionId: string, interceptResults?: InterceptResult[] }
): Promise<void>

ms.recall(query, options)

Hybrid recall over memories + artifacts. Three modes (query / intent_version / turn) and two speeds (fast ~100-190ms / deep ~300-500ms).

await ms.recall(
  query: string,
  {
    sessionId: string,
    limit?: number,        // default 10
    scope?: "session",
    mode?: "fast" | "deep",
    filters?: RecallFilters,
  }
): Promise<RecallResult>

ms.compress(options)

Fetch a structured session-context block. Pure SQL assembly — no LLM call. Target <50ms.

await ms.compress({
  sessionId: string,
  memoriesPerIntent?: number,
  orphanMemoriesLimit?: number,
  orderBy?: "importance" | "recency" | "blended",
  sinceTurn?: number,
  cursor?: string,
  maxTokens?: number,
  includeArtifacts?: boolean,
}): Promise<CompressResult>

ms.explore(options)

Zero-embedding 4-axis graph traversal from a known memory or artifact.

await ms.explore({
  itemId: string,
  kind: "memory" | "artifact",
  sessionId: string,
  limit?: number,
}): Promise<ExploreResult>

ms.fetch(artifactId)

Fetch artifact metadata + content in one call.

await ms.fetch(artifactId: string): Promise<FetchResult>

ms.session(sessionId)

Stateful wrapper bound to one session — every method accepts session context implicitly.

const session = ms.session("my-session");
await session.track(messages);
await session.recall("query");

intercept(content, options)

Local-only primitive: classify, extract metadata, scan for security findings, and stub if oversized. Free under MIT — no API key needed.

import { intercept } from "memosift";

await intercept(toolOutput, {
  toolName: "csv_fetch",
  securityMode?: "FLAG" | "REDACT" | "BLOCK",
}): Promise<InterceptResult>

Framework adapters

All 8 adapters ship inside the memosiftpackage. Each one wires MemoSift into the framework's native extension point. Vercel AI is TypeScript-only.

Anthropic

wrapAnthropic(...)

peer dep: @anthropic-ai/sdk

Proxies messages.create / messages.stream. Walks tool_result content blocks; mutates oversized blocks in place.

import Anthropic from "@anthropic-ai/sdk";
import { MemoSift, wrapAnthropic } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const session = ms.session("my-session");
const client = wrapAnthropic(new Anthropic(), { memosift: ms, session });

OpenAI

wrapOpenAI(...)

peer dep: openai

Proxies both chat.completions.create AND responses.create. Walks role=tool messages and function_call_output entries; mutates oversized payloads in place.

import OpenAI from "openai";
import { MemoSift, wrapOpenAI } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const session = ms.session("my-session");
const client = wrapOpenAI(new OpenAI(), { memosift: ms, session });

OpenAI Agents SDK

wrapOpenAIAgentsTool(...)

peer dep: @openai/agents

Wraps individual tool definitions to intercept their results.

import { MemoSift, wrapOpenAIAgentsTool } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const wrappedTool = wrapOpenAIAgentsTool(myTool, { memosift: ms, session: ms.session("my-session") });

Claude Agent SDK

installClaudeAgentMemoSift(...)

peer dep: @anthropic-ai/claude-agent-sdk

Installs PostToolUse hooks via the Claude Agent SDK's native hook system.

import { MemoSift, installClaudeAgentMemoSift } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
installClaudeAgentMemoSift(myAgent, { memosift: ms, session: ms.session("my-session") });

LangChain

memosiftCallback(...)

peer dep: @langchain/core

Returns a BaseCallbackHandler — LangChain's native callback protocol. Pass via callbacks=[...] to any chain, agent, or tool.

import { ChatOpenAI } from "@langchain/openai";
import { MemoSift, memosiftCallback } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const handler = memosiftCallback({ memosift: ms, session: ms.session("my-session") });
const llm = new ChatOpenAI({ callbacks: [handler] });

LangGraph

withLangGraphMemoSift(...)

peer dep: @langchain/langgraph

Wraps a compiled graph so its tool-call results flow through MemoSift.

import { MemoSift, withLangGraphMemoSift } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const wrapped = withLangGraphMemoSift(myCompiledGraph, { memosift: ms, session: ms.session("my-session") });

Vercel AI SDK

memosiftMiddleware(...)TypeScript only

peer dep: ai

LanguageModelV1Middleware that wraps generateText / streamText calls and intercepts tool-result content.

import { generateText } from "ai";
import { MemoSift, memosiftMiddleware } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const middleware = memosiftMiddleware({ memosift: ms, session: ms.session("my-session") });
// Pass via the Vercel AI SDK's middleware option.

Generic

wrapGenericClient(...)

Configurable Proxy for any client. You declare which methods to intercept and supply an extract function.

import { MemoSift, wrapGenericClient } from "memosift";

const ms = new MemoSift({ apiKey: process.env.MEMOSIFT_API_KEY!, baseUrl: "https://dev.memosift.com" });
const wrapped = wrapGenericClient(myClient, {
  memosift: ms,
  session: ms.session("my-session"),
  methods: ["chat.completions.create"],
  extract: (result, ctx) => [{ toolName: "myTool", content: String(result) }],
});

CLI

The memosift binary ships with the npm package — no global install required. Run via npx or invoke directly when installed locally.

memosift login                 # save your API key locally
memosift install-skill         # install the agent skill into the current project
memosift install               # wire MemoSift hooks into Claude Code settings
memosift mcp                   # run as MCP server over stdio (for Claude Code)
memosift hook post-tool-use    # individual hook handlers
memosift config get|set|list   # manage local config
memosift doctor                # diagnostic / troubleshooting

Teach your AI coding agent

The package ships with an installable skill that teaches Claude Code, Cursor, Codex CLI, Copilot, or Windsurf how to wire MemoSift into your code correctly.

# After installing the SDK, run from your project root:
memosift install-skill

# Or install everywhere this project supports:
memosift install-skill --all

# Or install globally for Claude Code:
memosift install-skill --user

The CLI auto-detects which agents are configured (.claude/, .cursor/rules/, AGENTS.md) and writes the appropriate format for each.

Full CLI reference