Single-file AI memory system for Node.js. Store, search, and query documents with built-in RAG.
npm install @memvid/sdkA 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.
``bash`
npm install @memvid/sdk
The package automatically installs the correct binary for your platform (macOS, Linux, or Windows).
`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();
`
`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 });
`
`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"
});
`
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);`
`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 |
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.
`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
`
`javascript
// Get recent entries
const entries = await mv.timeline({ limit: 20 });
// Get statistics
const stats = await mv.stats();
console.log(Documents: ${stats.frame_count});Size: ${stats.size_bytes} bytes
console.log();`
Always close the memory when done:
`javascript`
await mv.seal();
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"
`
`javascript
import { use } from "@memvid/sdk";
const mv = await use("langchain", "notes.mv2");
const tools = mv.tools; // StructuredTool instances for agents
`
`javascript`
const mv = await use("llamaindex", "notes.mv2");
const engine = mv.asQueryEngine();
const response = await engine.query("What is the timeline?");
`javascript`
const mv = await use("openai", "notes.mv2");
const functions = mv.functions; // JSON schemas for tool_calls
`javascript`
const mv = await use("vercel-ai", "notes.mv2");
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 |
| 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 | Architecture | Local Embeddings |
|----------|--------------|------------------|
| macOS | ARM64 (Apple Silicon) | Yes |
| macOS | x64 (Intel) | Yes |
| Linux | x64 (glibc) | Yes |
| Windows | x64 | No (use OpenAI) |
- Node.js 18 or later
- For local embeddings: macOS or Linux (Windows requires OpenAI)
- Documentation: https://docs.memvid.com
- GitHub: https://github.com/memvid/memvid
- Discord: https://discord.gg/2mynS7fcK7
- Website: https://memvid.com
Apache-2.0