API Reference - Memvid

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

REST API

https://api.memvid.comHTTP REST API for cloud service access.

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

​Quick Navigation

REST API

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