Skip to main content
This guide walks you through creating your first memory, adding documents, and searching. You’ll be up and running in under 5 minutes.

​
Prerequisites

Install the CLI using one of these methods: 
brew install memvid/tap/memvid
Verify your installation: 
memvid --version

​
Step 1: Create Your First Memory

Create a new .mv2 memory file: 
memvid create my-knowledge.mv2
Output: 
✓ Created memory at my-knowledge.mv2
  Capacity: 1.0 GB (1073741824 bytes)
  Size: 4.0 MB
  Indexes: lexical | vector
Check the memory info: 
memvid stats my-knowledge.mv2
You’ll see the initial state: 0 documents, 1 GB capacity.

​
Step 2: Add Documents

​
Add Text Content

Add some text directly: 
echo "Memvid is a portable AI memory system. It stores embeddings, indices, and data in a single .mv2 file." | memvid put my-knowledge.mv2 --input - --title "What is Memvid"

​
Add Files

Add documents from your filesystem: 
# Add a single file with vector compression
memvid put my-knowledge.mv2 --input document.pdf --vector-compression

# Add all files in a directory
memvid put my-knowledge.mv2 --input ./documents/ --vector-compression

​
Add with Metadata

Organize your content with tracks and tags: 
memvid put my-knowledge.mv2 \
  --input notes.md \
  --track "notes" \
  --tag "category=meeting" \
  --vector-compression

​
Step 3: Search Your Memory

memvid find my-knowledge.mv2 --query "portable memory"
Output: 
Found 1 result for "portable memory":

[1] Score: 0.95 | Frame: 1
    What is Memvid
    Memvid is a portable AI memory system. It stores embeddings...

​
Search Modes

Combines keyword and semantic search for best results:
memvid find my-knowledge.mv2 --query "how to store AI data" --mode auto

​
JSON Output

Get results in JSON format for scripting: 
memvid find my-knowledge.mv2 --query "memory" --json

​
Step 4: Ask Questions

Use AI to synthesize answers from your documents: 
# Using local model (tinyllama)
memvid ask my-knowledge.mv2 --question "What is Memvid and how does it work?"

# Using OpenAI (requires API key)
export OPENAI_API_KEY=your-key
memvid ask my-knowledge.mv2 --question "What is Memvid?" --use-model openai

# Using Anthropic
export ANTHROPIC_API_KEY=your-key
memvid ask my-knowledge.mv2 --question "What is Memvid?" --use-model claude

​
Step 5: Browse Timeline

View documents chronologically: 
# Recent documents
memvid timeline my-knowledge.mv2 --limit 10

# Filter by time range
memvid timeline my-knowledge.mv2 --since 1704067200 --until 1706745600

# View a specific document
memvid view my-knowledge.mv2 --frame-id 1

​
Step 6: Verify Integrity

Ensure your memory file is healthy: 
# Basic verification
memvid verify my-knowledge.mv2

# Deep verification
memvid verify my-knowledge.mv2 --deep

# Confirm single-file integrity
memvid verify-single-file my-knowledge.mv2
This checks checksums, index integrity, and confirms the file is self-contained with no auxiliary files.

​
Next Steps

You’ve created your first memory, added documents, and run searches. Here’s what to explore next:

CLI Reference

Complete reference for all CLI commands

Python SDK

Build applications with the Python SDK

Node.js SDK

Build applications with the Node.js SDK

Concepts

Understand how Memvid works

​
Complete Example

Here’s a complete workflow for building a documentation knowledge base: 
# 1. Create the memory
memvid create docs.mv2

# 2. Ingest documentation with vector compression
memvid put docs.mv2 \
  --input ./docs/ \
  --vector-compression \
  --track "documentation"

# 3. Add API reference
memvid put docs.mv2 \
  --input ./api-reference/ \
  --vector-compression \
  --track "api"

# 4. Check stats
memvid stats docs.mv2

# 5. Search for information
memvid find docs.mv2 --query "authentication setup" --mode auto

# 6. Ask questions
export OPENAI_API_KEY=your-key
memvid ask docs.mv2 \
  --question "How do I configure OAuth?" \
  --use-model openai

# 7. Verify integrity
memvid verify docs.mv2 --deep
Your documentation is now searchable with both keywords and natural language queries!

​
Using with SDKs

​
Python

pip install memvid-sdk

from memvid_sdk import use

# Open read-only (for queries)
mem = use('basic', 'docs.mv2', read_only=True)

# Search
results = mem.find('authentication', k=5)
for hit in results['hits']:
    print(f"{hit['score']:.2f}: {hit['title']}")

# Ask questions
answer = mem.ask('How do I configure OAuth?', model='openai:gpt-4o')
print(answer['answer'])

​
Node.js

npm install @memvid/sdk

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

// Open read-only
const mem = await use('basic', 'docs.mv2', { readOnly: true });

// Search
const results = await mem.find('authentication', { k: 5 });
results.hits.forEach(hit => {
  console.log(`${hit.score.toFixed(2)}: ${hit.title}`);
});

// Ask questions
const answer = await mem.ask('How do I configure OAuth?', {
  model: 'openai:gpt-4o-mini'
});
console.log(answer.answer);