@memofs/adapter-openai

@memofs/adapter-openai

         

OpenAI embeddings adapter for MemoFS.

What is this?

OpenAI Embedder adapter for MemoFS. Provides first-class integration with OpenAI's embedding models (text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002) through MemoFS's provider-neutral embedder contract.

Installation

npm install @memofs/adapter-openai

Requires Node.js >= 22.

You also need an OpenAI API key from platform.openai.com.

Quick Start

import { createOpenAIEmbedder } from "@memofs/adapter-openai";

const embedder = createOpenAIEmbedder({
 apiKey: process.env.OPENAI_API_KEY!,
 model: "text-embedding-3-large",
});

// Embed a batch of texts
const result = await embedder.embed([
 "MemoFS provides unified memory runtime for AI agents",
 "OpenAI offers state-of-the-art embedding models",
]);

console.log(result.embeddings); // number[][]
console.log(result.usage); // { promptTokens, totalTokens }

Configuration

Embedder Options

Option	Type	Default	Description
apiKey	string	required	OpenAI API key
model	string	"text-embedding-3-large"	Embedding model to use
dimensions	number	model default	Output dimensions (for text-embedding-3 models)
encodingFormat	"float" | "base64"	"float"	Output format for embeddings
timeout	number	30000	Request timeout in milliseconds
maxRetries	number	3	Maximum retry attempts
batchSize	number	100	Maximum texts per batch request
organization	string	—	OpenAI organization ID (optional)

Supported Models

Model	Dimensions	Max Tokens	Use Case
text-embedding-3-large	3072 (configurable)	8191	Highest quality
text-embedding-3-small	1536 (configurable)	8191	Balanced quality/speed
text-embedding-ada-002	1536	8191	Legacy, cost-effective

Integration with MemoFS Core

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";
import { createOpenAIEmbedder } from "@memofs/adapter-openai";

const store = createNodeFsMemoryStore({ rootDir: "." });

const memo = new MemoFS({
  store,
  projectId: "my-app",
  embedder: createOpenAIEmbedder({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-large",
    dimensions: 1536, // Optional: reduce dimensions for speed
  }),
});

// The embedder powers hybrid recall; embeddings persist to
// `.memofs/indexes/embeddings.jsonl` via the file-backed recall store.

Advanced: Custom Client

import { OpenAI } from "openai";
import { createOpenAIEmbedder } from "@memofs/adapter-openai";

const customClient = new OpenAI({
 apiKey: process.env.OPENAI_API_KEY!,
 baseURL: "https://custom-proxy.example.com/v1", // For proxies, Azure, etc.
 defaultHeaders: { "x-custom-header": "value" },
});

const embedder = createOpenAIEmbedder({
 client: customClient,
 model: "text-embedding-3-large",
});

Testing

The package exports fake implementations for testing:

import { createFakeOpenAIClient } from "@memofs/adapter-openai/testing";

const fakeClient = createFakeOpenAIClient({
 embeddings: [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
 usage: { promptTokens: 10, totalTokens: 10 },
});

Boundary

This package owns the OpenAI embedder adapter implementation. It does not own the MemoFS core contracts, other provider adapters, or the OpenAI service itself.

Contributing

See our central Contributing Guide and development scripts for details on formatting, linting, and testing within the monorepo.

License

MIT