@memvid/sdk

A single-file AI memory system for Node.js. Store documents, search with BM25 + vector ranking, and run RAG queries from a portable .mv2 file.

Built on Rust via N-API. No database setup, no external services required.

Install

npm install @memvid/sdk

The package automatically installs the correct binary for your platform (macOS, Linux, or Windows).

Quick Start

import { create } from "@memvid/sdk";

// Create a memory file
const mv = await create("notes.mv2");

// Store some documents
await mv.put({
  title: "Project Update",
  label: "meeting",
  text: "Discussed Q4 roadmap. Alice will handle the frontend refactor.",
  metadata: { date: "2024-01-15", attendees: ["Alice", "Bob"] }
});

await mv.put({
  title: "Technical Decision",
  label: "architecture",
  text: "Decided to use PostgreSQL for the main database. Redis for caching.",
});

// Search by keyword
const results = await mv.find("database");
console.log(results.hits);

// Ask a question
const answer = await mv.ask("What database are we using?", {
  model: "openai:gpt-4o-mini"
});
console.log(answer.text);

// Close the file
await mv.seal();

Core API

Opening and Creating

import { create, use } from "@memvid/sdk";

// Create a new memory file
const mv = await create("notes.mv2");

// Open an existing file
const mv = await use("basic", "notes.mv2", { mode: "open" });

// Create or open (auto mode)
const mv = await use("basic", "notes.mv2", { mode: "auto" });

// Open read-only
const mv = await use("basic", "notes.mv2", { readOnly: true });

Storing Documents

// Store text content
await mv.put({
  title: "Meeting Notes",
  label: "meeting",
  text: "Discussed the new API design.",
  metadata: { date: "2024-01-15", priority: "high" },
  tags: ["api", "design", "q1"]
});

// Store a file (PDF, DOCX, TXT, etc.)
await mv.put({
  title: "Q4 Report",
  label: "reports",
  file: "./documents/q4-report.pdf"
});

// Store with both text and file
await mv.put({
  title: "Contract Summary",
  label: "legal",
  text: "Key terms: 2-year agreement, auto-renewal clause.",
  file: "./contracts/agreement.pdf"
});

Batch Ingestion

For large imports, putMany is significantly faster:

const documents = [
  { title: "Doc 1", label: "notes", text: "First document content..." },
  { title: "Doc 2", label: "notes", text: "Second document content..." },
  // ... thousands more
];

const frameIds = await mv.putMany(documents);
console.log(`Added ${frameIds.length} documents`);

Searching

// Lexical search (BM25 ranking)
const results = await mv.find("machine learning", { k: 10 });

for (const hit of results.hits) {
  console.log(`${hit.title}: ${hit.snippet}`);
}

Search options:

| Option | Type | Description | |--------|------|-------------| | k | number | Number of results (default: 10) | | snippetChars | number | Snippet length (default: 240) | | mode | string | "lex", "sem", or "auto" | | scope | string | Filter by URI prefix |

Semantic Search

Semantic search requires embeddings. You can generate them during ingestion:

// Using local embeddings (bge-small, nomic, etc.)
await mv.put({
  title: "Document",
  text: "Content here...",
  enableEmbedding: true,
  embeddingModel: "bge-small"
});

// Using OpenAI embeddings
await mv.put({
  title: "Document",
  text: "Content here...",
  enableEmbedding: true,
  embeddingModel: "openai-small"  // requires OPENAI_API_KEY
});

Then search semantically:

const results = await mv.find("neural networks", { mode: "sem" });

Windows users: Local embedding models (bge-small, nomic, etc.) are not available on Windows due to ONNX runtime limitations. Use OpenAI embeddings instead by setting OPENAI_API_KEY.

Question Answering (RAG)

// Basic RAG query
const answer = await mv.ask("What did we decide about the database?");
console.log(answer.text);

// With specific model
const answer = await mv.ask("Summarize the meeting notes", {
  model: "openai:gpt-4o-mini",
  k: 6  // number of documents to retrieve
});

// Get context only (no LLM synthesis)
const context = await mv.ask("What was discussed?", { contextOnly: true });
console.log(context.context);  // Retrieved document snippets

Timeline and Stats

// Get recent entries
const entries = await mv.timeline({ limit: 20 });

// Get statistics
const stats = await mv.stats();
console.log(`Documents: ${stats.frame_count}`);
console.log(`Size: ${stats.size_bytes} bytes`);

Closing

Always close the memory when done:

await mv.seal();

External Embeddings

For more control over embeddings, use external providers:

import { create, OpenAIEmbeddings, getEmbedder } from "@memvid/sdk";

// Create memory file
const mv = await create("knowledge.mv2");

// Initialize embedding provider
const embedder = new OpenAIEmbeddings({ model: "text-embedding-3-small" });

// Prepare documents
const documents = [
  { title: "ML Basics", label: "ai", text: "Machine learning enables systems to learn from data." },
  { title: "Deep Learning", label: "ai", text: "Deep learning uses neural networks with multiple layers." },
];

// Ingest with external embeddings
await mv.putMany(documents, { embedder });

// Search using external embeddings
const results = await mv.find("neural networks", { mode: "sem", k: 3, embedder });

for (const hit of results.hits) {
  console.log(`${hit.title}: ${hit.score.toFixed(3)}`);
}

Built-in providers:

• OpenAIEmbeddings (requires OPENAI_API_KEY)
• CohereEmbeddings (requires COHERE_API_KEY)
• VoyageEmbeddings (requires VOYAGE_API_KEY)
• NvidiaEmbeddings (requires NVIDIA_API_KEY)
• GeminiEmbeddings (requires GOOGLE_API_KEY or GEMINI_API_KEY)
• MistralEmbeddings (requires MISTRAL_API_KEY)

Use the factory function for quick setup:

import { getEmbedder } from "@memvid/sdk";

// Create any supported provider
const embedder = getEmbedder("openai");  // or "cohere", "voyage", "nvidia", "gemini", "mistral"

Framework Integrations

LangChain

import { use } from "@memvid/sdk";

const mv = await use("langchain", "notes.mv2");
const tools = mv.tools;  // StructuredTool instances for agents

LlamaIndex

const mv = await use("llamaindex", "notes.mv2");
const engine = mv.asQueryEngine();
const response = await engine.query("What is the timeline?");

OpenAI Function Calling

const mv = await use("openai", "notes.mv2");
const functions = mv.functions;  // JSON schemas for tool_calls

Vercel AI SDK

const mv = await use("vercel-ai", "notes.mv2");

Error Handling

Errors include a code for programmatic handling:

import { MemvidError } from "@memvid/sdk";

try {
  await mv.put({ title: "Doc", text: "Content" });
} catch (err) {
  if (err instanceof MemvidError) {
    switch (err.code) {
      case "MV001": console.error("Storage capacity exceeded"); break;
      case "MV007": console.error("File is locked"); break;
      case "MV015": console.error("Embedding failed"); break;
      default: console.error(`Error ${err.code}: ${err.message}`);
    }
  }
}

Common error codes:

| Code | Description | |------|-------------| | MV001 | Storage capacity exceeded | | MV007 | File locked by another process | | MV010 | Frame not found | | MV013 | File not found | | MV015 | Embedding failed |

Environment Variables

| Variable | Description | |----------|-------------| | OPENAI_API_KEY | For OpenAI embeddings and LLM synthesis | | OPENAI_BASE_URL | Custom OpenAI-compatible endpoint | | NVIDIA_API_KEY | For NVIDIA NIM embeddings | | MEMVID_MODELS_DIR | Local embedding model cache directory | | MEMVID_API_KEY | For capacity beyond the free tier | | MEMVID_OFFLINE | Set to 1 to disable network features |

Platform Support

| Platform | Architecture | Local Embeddings | |----------|--------------|------------------| | macOS | ARM64 (Apple Silicon) | Yes | | macOS | x64 (Intel) | Yes | | Linux | x64 (glibc) | Yes | | Windows | x64 | No (use OpenAI) |

Requirements

• Node.js 18 or later
• For local embeddings: macOS or Linux (Windows requires OpenAI)

More Information

• Documentation: https://docs.memvid.com
• GitHub: https://github.com/memvid/memvid
• Discord: https://discord.gg/2mynS7fcK7
• Website: https://memvid.com

License

Apache-2.0