create() will OVERWRITE existing files without warning!| Function | Purpose | If File Exists | Parameter Order |
|---|---|---|---|
create(path, kind) | Create new .mv2 file | DELETES all data | path first, then kind |
use(kind, path) | Open existing .mv2 file | Preserves data | kind first, then path |
const mem = existsSync(path) ? await use('basic', path) : await create(path, 'basic');
- CLI
- Node.js
- Python
Install
npm install -g memvid-cli
Works on macOS, Linux, and Windows. Requires Node.js 14+.
Create & Ingest
# Create a new memory
memvid create knowledge.mv2
# Add documents
echo "Alice works at Anthropic as a Senior Engineer in San Francisco." | \
memvid put knowledge.mv2 --title "Team Info"
echo "Bob joined OpenAI last month as a Research Scientist." | \
memvid put knowledge.mv2 --title "New Hires"
echo "Project Alpha has a budget of $500k and is led by Alice." | \
memvid put knowledge.mv2 --title "Projects"
Search
# Search works immediately (BM25 lexical search)
memvid find knowledge.mv2 --query "who works at AI companies"
Ask Questions
# Ask with LLM synthesis (requires OPENAI_API_KEY)
export OPENAI_API_KEY=sk-...
memvid ask knowledge.mv2 --question "What is Alice's role?" --use-model openai
Extract Facts
# Extract structured facts
memvid enrich knowledge.mv2 --engine rules
# Query entity state (O(1) lookup)
memvid state knowledge.mv2 "Alice"
Entity: Alice
employer: Anthropic
role: Senior Engineer
location: San Francisco
Install
npm install @memvid/sdk
Create & Ingest
import { create, use } from '@memvid/sdk';
import { existsSync } from 'fs';
const path = 'knowledge.mv2';
// IMPORTANT: create() for NEW files, use() for EXISTING files
const mem = existsSync(path)
? await use('basic', path) // Open existing
: await create(path, 'basic'); // Create new
// Add documents
await mem.put({
title: 'Team Info',
label: 'team',
text: 'Alice works at Anthropic as a Senior Engineer in San Francisco.'
});
await mem.put({
title: 'New Hires',
label: 'team',
text: 'Bob joined OpenAI last month as a Research Scientist.'
});
await mem.put({
title: 'Projects',
label: 'project',
text: 'Project Alpha has a budget of $500k and is led by Alice.'
});
Search
// Search works immediately (BM25 lexical search)
const results = await mem.find('who works at AI companies', { k: 5 });
console.log(results.hits.map(h => h.title));
// ['Team Info', 'New Hires']
Ask Questions
// Ask with LLM synthesis
const answer = await mem.ask("What is Alice's role?", {
model: 'gpt-4o-mini',
modelApiKey: process.env.OPENAI_API_KEY
});
console.log(answer.answer);
// "Alice is a Senior Engineer at Anthropic in San Francisco."
Extract Facts
// Extract structured facts
await mem.enrich('rules');
// Query entity state (O(1) lookup)
const alice = await mem.state('Alice');
console.log(alice.slots);
// { employer: 'Anthropic', role: 'Senior Engineer', location: 'San Francisco' }
Install
pip install memvid-sdk
Create & Ingest
from memvid_sdk import create, use
import os
path = 'knowledge.mv2'
# IMPORTANT: create() for NEW files, use() for EXISTING files
if os.path.exists(path):
mem = use('basic', path) # Open existing
else:
mem = create(path) # Create new (kind='basic' is default)
# enable_lex() not needed - lexical search enabled by default
# Add documents
mem.put(
title='Team Info',
label='team',
metadata={},
text='Alice works at Anthropic as a Senior Engineer in San Francisco.'
)
mem.put(
title='New Hires',
label='team',
metadata={},
text='Bob joined OpenAI last month as a Research Scientist.'
)
mem.put(
title='Projects',
label='project',
metadata={},
text='Project Alpha has a budget of $500k and is led by Alice.'
)
Search
# Search works immediately (BM25 lexical search)
results = mem.find('who works at AI companies', k=5)
print([h['title'] for h in results['hits']])
# ['Team Info', 'New Hires']
Ask Questions
# Ask with LLM synthesis
answer = mem.ask(
"What is Alice's role?",
model='gpt-4o-mini',
api_key=os.environ['OPENAI_API_KEY']
)
print(answer['answer'])
# "Alice is a Senior Engineer at Anthropic in San Francisco."
Extract Facts
# Extract structured facts
mem.enrich(engine='rules')
# Query entity state (O(1) lookup)
alice = mem.state('Alice')
print(alice['slots'])
# {'employer': 'Anthropic', 'role': 'Senior Engineer', 'location': 'San Francisco'}
What You Built
In 5 minutes, you created a complete AI memory system with:| Feature | Description |
|---|---|
| Hybrid Search | Combines lexical (BM25) and semantic (vector) search |
| LLM Q&A | Natural language questions with sourced answers |
| Entity Extraction | Structured facts with O(1) lookups |
| Single File | Everything stored in one portable .mv2 file |
Next Steps
CLI Reference
Complete command reference for all 38+ commands
Node.js SDK
Full API reference with TypeScript types
Python SDK
Complete Python API with examples
Embedding Providers
OpenAI, Gemini, Mistral, and local models
Memory Cards
Deep dive into O(1) entity lookups
Framework Integrations
LangChain, LlamaIndex, Vercel AI, and more
Common Patterns
Using External Embeddings
- Node.js
- Python
import { create, use, OpenAIEmbeddings } from '@memvid/sdk';
import { existsSync } from 'fs';
const embedder = new OpenAIEmbeddings({
apiKey: process.env.OPENAI_API_KEY,
model: 'text-embedding-3-small'
});
const path = 'project.mv2';
const mem = existsSync(path)
? await use('basic', path)
: await create(path, 'basic');
await mem.putMany(docs, { embedder });
await mem.find('query', { embedder });
from memvid_sdk import create, use
from memvid_sdk.embeddings import OpenAIEmbeddings
import os
embedder = OpenAIEmbeddings(
api_key=os.environ['OPENAI_API_KEY'],
model='text-embedding-3-small'
)
path = 'project.mv2'
if os.path.exists(path):
mem = use('basic', path)
else:
mem = create(path)
mem.put_many(docs, embedder=embedder)
mem.find('query', embedder=embedder)
Batch Ingestion
- Node.js
- Python
const docs = [
{ title: 'Doc 1', label: 'kb', text: 'Content 1' },
{ title: 'Doc 2', label: 'kb', text: 'Content 2' },
{ title: 'Doc 3', label: 'kb', text: 'Content 3' }
];
await mem.putMany(docs);
docs = [
{'title': 'Doc 1', 'label': 'kb', 'text': 'Content 1'},
{'title': 'Doc 2', 'label': 'kb', 'text': 'Content 2'},
{'title': 'Doc 3', 'label': 'kb', 'text': 'Content 3'}
]
mem.put_many(docs)
PDF Ingestion with Tables
- CLI
- Node.js
- Python
memvid put project.mv2 --input report.pdf --title "Q4 Report" --tables
memvid tables list project.mv2
memvid tables export project.mv2 --table-id tbl_001 -o table.csv
await mem.put({ file: 'report.pdf', title: 'Q4 Report', label: 'report' });
await mem.putPdfTables('report.pdf', true);
const tables = await mem.listTables();
mem.put(title='Q4 Report', label='report', metadata={}, file='report.pdf')
mem.put_pdf_tables('report.pdf', embed_rows=True)
tables = mem.list_tables()