API Reference - Memvid

Comprehensive documentation for all Memvid APIs across CLI, Python SDK, Node.js SDK, and core Rust APIs.

Python SDK

pip install memvid-sdkFull Python API with type hints and async support.

Node.js SDK

npm install @memvid/sdkTypeScript-first with full type definitions.

CLI Reference

memvid <command>Command-line interface for all operations.

Core API

memvid-coreLow-level Rust API for open/mutate/search/ask.

Core Operations

Create / Open

Node.js
Python
CLI

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

// Open existing or create if not exists
const memAuto = await use('basic', 'knowledge.mv2', { mode: 'auto' });

// Create new
const memCreate = await use('basic', 'knowledge.mv2', { mode: 'create' });

// Open existing
const memOpen = await use('basic', 'knowledge.mv2', { mode: 'open' });

// Shorthand
const mem2 = await create('knowledge.mv2');

from memvid_sdk import use, create

# Open existing or create if not exists
mem = use('basic', 'knowledge.mv2', mode='auto')

# Create new (fails if exists)
mem = use('basic', 'knowledge.mv2', mode='create')

# Open existing (fails if not exists)
mem = use('basic', 'knowledge.mv2', mode='open')

# Shorthand for create
mem = create('knowledge.mv2')

# Create new file
memvid create knowledge.mv2

# Open is implicit in other commands
memvid find knowledge.mv2 --query "test"

Put (Store)

Node.js
Python
CLI

// Store text content
const frameId = await mem.put({
  title: 'Document Title',
  label: 'category',
  text: 'The content to store...',
  tags: ['tag1', 'tag2'],
  metadata: { author: 'John', date: '2024-01-15' },
});

// Store from file
const frameId = await mem.put({
  title: 'PDF Document',
  label: 'documents',
  file: '/path/to/document.pdf',
});

# Store text content
frame_id = mem.put({
    "title": "Document Title",
    "label": "category",
    "text": "The content to store...",
    "tags": ["tag1", "tag2"],
    "metadata": {"author": "John", "date": "2024-01-15"}
})

# Store from file
frame_id = mem.put({
    "title": "PDF Document",
    "label": "documents",
    "file": "/path/to/document.pdf"
})

# Store from URL
frame_id = mem.put({
    "title": "Web Page",
    "label": "web",
    "uri": "https://example.com/page"
})

# Store text
memvid put knowledge.mv2 \
  --title "Document Title" \
  --label "category" \
  --text "The content to store..."

# Store file
memvid put knowledge.mv2 \
  --input document.pdf \
  --label "documents"

# Store folder
memvid put knowledge.mv2 \
  --input ./docs/ \
  --embeddings \
  --recursive

Find (Search)

Node.js
Python
CLI

// Basic search
const results = await mem.find('search query', { k: 10 });

// With options
const results = await mem.find('search query', {
  k: 10,
  mode: 'auto',
  scope: 'label:docs',
  snippetChars: 200,
});

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

# Basic search
results = mem.find("search query", k=10)

# With options
results = mem.find(
    "search query",
    k=10,                    # Number of results
    mode="auto",             # auto, lex, or sem
    scope="label:docs",      # Filter by label
    snippet_chars=200        # Snippet length
)

# Access results
for hit in results.hits:
    print(f"{hit.title} (score: {hit.score})")
    print(f"  {hit.snippet}")

# Basic search
memvid find knowledge.mv2 --query "search query"

# With options
    memvid find knowledge.mv2 \
      --query "search query" \
      --top-k 10 \
      --mode auto \
      --json

Ask (Q&A)

Node.js
Python
CLI

// Basic question
const answer = await mem.ask('What is the main feature?');
console.log(answer.answer);

// With options
const answer = await mem.ask('What is the main feature?', {
  k: 5,
  mode: 'auto',
  model: 'openai:gpt-4o-mini',
  maskPii: true,
});

console.log(`Answer: ${answer.answer}`);
console.log(`Sources: ${answer.sources.map(s => s.title)}`);

# Basic question
answer = mem.ask("What is the main feature?")
print(answer["answer"])

# With options
answer = mem.ask(
    "What is the main feature?",
    k=5,                     # Context documents
    mode="auto",             # Search mode
    model="openai:gpt-4o-mini",  # LLM model
    mask_pii=True            # Mask sensitive data
)

# Access answer details
print(f"Answer: {answer.get('answer')}")
print(f"Sources: {[s.get('title') for s in answer.get('sources', [])]}")
print(f"Context: {answer.get('context')}")

# Basic question
memvid ask knowledge.mv2 --question "What is the main feature?"

# With options
    memvid ask knowledge.mv2 \
      --question "What is the main feature?" \
      --top-k 5 \
      --mode hybrid \
      --json

Timeline

Node.js
Python
CLI

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

// With time range
const timeline = await mem.timeline({
  limit: 50,
  since: 1700000000,
  until: 1710000000,
  reverse: true,
});

for (const entry of timeline.entries) {
  console.log(`[${entry.timestamp}] ${entry.title}`);
}

# Get recent entries
timeline = mem.timeline(limit=50)

# With time range
timeline = mem.timeline(
    limit=50,
    since=1700000000,        # Unix timestamp
    until=1710000000,
    reverse=True             # Newest first
)

for entry in timeline.entries:
    print(f"[{entry.timestamp}] {entry.title}")

# Recent entries
memvid timeline knowledge.mv2 --limit 50

# With time range
memvid timeline knowledge.mv2 \
  --since 1700000000 \
  --until 1710000000 \
  --reverse

Stats

Node.js
Python
CLI

const stats = await mem.stats();
console.log(`Frames: ${stats.frame_count}`);
console.log(`Size: ${stats.size_bytes} bytes`);

stats = mem.stats()
print(f"Frames: {stats['frame_count']}")
print(f"Size: {stats['size_bytes']} bytes")
print(f"Capacity: {stats['capacity_bytes']} bytes")

memvid stats knowledge.mv2 --json

Seal (Close)

Node.js
Python
CLI

// Always seal when done
await mem.seal();

# Always seal when done to ensure data is written
mem.seal()

# Or use context manager
with use('basic', 'knowledge.mv2') as mem:
    mem.put(...)
# Automatically sealed

# Explicit seal (usually not needed)
memvid seal knowledge.mv2

Types Reference

PutInput

interface PutInput {
  title: string;           // Document title (required)
  label: string;           // Category label (required)
  text?: string;           // Text content
  file?: string;           // Path to file
  uri?: string;            // URL to fetch
  tags?: string[];         // Searchable tags
  labels?: string[];       // Additional labels
  metadata?: object;       // Custom metadata
  searchText?: string;     // Override search text
  enableEmbedding?: boolean; // Generate vectors
  autoTag?: boolean;       // Auto-generate tags
  extractDates?: boolean;  // Extract dates for timeline
}

FindInput

interface FindInput {
  k?: number;              // Number of results (default: 10)
  mode?: 'auto' | 'lex' | 'sem';  // Search mode
  snippetChars?: number;   // Snippet length
  scope?: string;          // Filter expression
  cursor?: string;         // Pagination cursor
}

AskInput

interface AskInput {
  k?: number;              // Context documents
  mode?: 'auto' | 'lex' | 'sem';  // Search mode
  model?: string;          // LLM model
  maskPii?: boolean;       // Mask sensitive data
  contextOnly?: boolean;   // Return context without LLM
  snippetChars?: number;   // Snippet length
  scope?: string;          // Filter expression
}

SearchResult

interface SearchResult {
  hits: Hit[];             // Matching documents
  total: number;           // Total matches
  cursor?: string;         // Next page cursor
}

interface Hit {
  frameId: number;         // Document ID
  title: string;           // Document title
  label: string;           // Category label
  text: string;            // Full text
  snippet: string;         // Highlighted excerpt
  score: number;           // Relevance score
  metadata?: object;       // Custom metadata
}

AskResult

interface AskResult {
  text: string;            // Generated answer
  answer: string;          // Alias for text
  sources: Source[];       // Source documents
  context: string;         // Aggregated context
  confidence?: number;     // Confidence score
}

interface Source {
  title: string;
  snippet: string;
  score: number;
}

Error Handling

See the Error Reference for complete error documentation.

from memvid_sdk import (
    MemvidError,
    CapacityExceededError,
    TicketInvalidError,
    LockedError,
)

try:
    mem.put(...)
except CapacityExceededError:
    print("Storage full, upgrade your plan")
except LockedError:
    print("File locked by another process")
except MemvidError as e:
    print(f"Error [{e.code}]: {e.message}")

Next Steps

Python SDK Guide

Complete Python documentation

Node.js SDK Guide

Complete Node.js documentation

CLI Reference

All CLI commands

Error Reference

Error codes and solutions

Get Started

Comparisons

Install

Hosting

Architecture

Search & Retrieval

Enrichment

Media Processing

Embeddings

Security & Limits

Performance

CLI

Python SDK

Node.js SDK

Examples & Packages

Testing

Help

​Quick Navigation

Python SDK

Node.js SDK

CLI Reference

Core API

​Core Operations

​Create / Open

​Put (Store)

​Find (Search)

​Ask (Q&A)

​Timeline

​Stats

​Seal (Close)

​Types Reference

​PutInput

​FindInput

​AskInput

​SearchResult

​AskResult

​Error Handling

​Next Steps

Python SDK Guide

Node.js SDK Guide

CLI Reference

Error Reference

Quick Navigation

Core Operations

Create / Open

Put (Store)

Find (Search)

Ask (Q&A)

Timeline

Stats

Seal (Close)

Types Reference

PutInput

FindInput

AskInput

SearchResult

AskResult

Error Handling

Next Steps