@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

``bash
npm install @memvid/sdk
`

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

Quick Start

`javascript
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

$3

`javascript
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 });
`

$3

`javascript
// 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"
});
`

$3

For large imports, putMany is significantly faster:

`javascript
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);
`

$3

`javascript
// 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 |

$3

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

`javascript
// 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:

`javascript
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.

$3

`javascript
// 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
`

$3

`javascript
// 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);
`

$3

Always close the memory when done:

`javascript
await mv.seal();
`

External Embeddings

For more control over embeddings, use external providers:

`javascript
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:

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

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

Framework Integrations

$3

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

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

$3

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

$3

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

$3

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

Error Handling

Errors include a code for programmatic handling:

`javascript
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