Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.memvid.com/llms.txt

Use this file to discover all available pages before exploring further.

Memvid files have configurable storage capacity to help you manage resources effectively. This page explains how capacity works and how to manage it.

​
Capacity Tiers

When creating a memory file, you can specify the storage tier:
TierCapacityWAL SizeTypical Use
Free50 MB70 KBPersonal notes, small projects
Starter25 GB70 KBDevelopment, prototyping
Pro125 GB70 KBProduction workloads
EnterpriseUnlimited70 KBScale and mission-critical production

​
Creating with a Tier

# Create with default (free) tier
memvid create knowledge.mv2

# Create with dev tier
memvid create knowledge.mv2 --tier dev

# Create with enterprise tier
memvid create knowledge.mv2 --tier enterprise

# Create with explicit size
memvid create knowledge.mv2 --size 500MB
memvid create knowledge.mv2 --capacity 2GB

from memvid_sdk import use

# Open or create with default capacity
mem = use('basic', 'knowledge.mv2')

# Capacity is set at creation time
mem = use('basic', 'new-memory.mv2', mode='create')

​
Checking Capacity

​
CLI

memvid stats knowledge.mv2
Output: 
Memory: knowledge.mv2

Documents:         150
Active Frames:     148
Size:              52.4 MB
Capacity:          1.0 GB
Utilization:       5.2%

Indices:
  Lexical:         Yes
  Vector:          Yes
  Time:            Yes

​
JSON Output

memvid stats knowledge.mv2 --json

{
  "frame_count": 150,
  "active_frame_count": 148,
  "size_bytes": 54945587,
  "capacity_bytes": 1073741824,
  "storage_utilisation_percent": 5.2
}

​
Python SDK

stats = mem.stats()
print(f"Size: {stats['size_bytes']} bytes")
print(f"Capacity: {stats['capacity_bytes']} bytes")
print(f"Utilization: {stats['storage_utilisation_percent']:.1f}%")

​
Node.js SDK

const stats = await mv.stats();
console.log(`Size: ${stats.sizeBytes} bytes`);
console.log(`Capacity: ${stats.capacityBytes} bytes`);
console.log(`Utilization: ${stats.storageUtilisationPercent.toFixed(1)}%`);

​
Capacity Exceeded Errors

When you try to add content that would exceed the file’s capacity, you’ll get a CapacityExceeded error (MV001).

​
CLI

Error: CapacityExceeded
File capacity: 25000000000 bytes (25 GB)
Current usage: 24000000000 bytes (24 GB)
Requested: 2000000000 bytes (2 GB)

Solutions:
1. Delete unused frames: memvid delete knowledge.mv2 --frame-id <id>
2. Vacuum to reclaim space: memvid doctor knowledge.mv2 --vacuum
3. Create a larger memory file: memvid create new.mv2 --tier dev

​
Python SDK

from memvid_sdk import use, CapacityExceededError

try:
    mem.put(file="large-file.pdf")
except CapacityExceededError as e:
    print(f"MV001: {e}")
    # Handle by cleaning up or using a larger file

​
Node.js SDK

import { open, CapacityExceededError } from '@memvid/sdk';

const mv = await open('knowledge.mv2');

try {
  await mv.put({ title: 'Large Document', label: 'docs', file: 'large-file.pdf' });
  await mv.seal();
} catch (error) {
  if (error instanceof CapacityExceededError) {
    console.log('MV001:', error.message);
  }
}

​
Managing Capacity

​
Reclaiming Space

After deleting documents, reclaim unused space: 
# Check current usage
memvid stats knowledge.mv2

# Delete old content
memvid delete knowledge.mv2 --frame-id 42 --yes
memvid delete knowledge.mv2 --uri "mv2://old/doc.md" --yes

# Vacuum to reclaim space
memvid doctor knowledge.mv2 --vacuum

# Verify space was reclaimed
memvid stats knowledge.mv2

​
Moving to a Larger File

If you need more capacity, create a new file and migrate: 
# Create new file with larger capacity
memvid create new-knowledge.mv2 --tier dev

# Export content from old file (using SDK)

from memvid_sdk import use

# Open old file read-only
old = use('basic', 'knowledge.mv2', read_only=True)

# Create new file with larger capacity
new = use('basic', 'new-knowledge.mv2', mode='create')

# Migrate content
timeline = old.timeline(limit=10000)
for entry in timeline['entries']:
    frame = old.frame(f"mv2://{entry['uri']}")
    if frame:
        new.put(text=frame['content'], title=frame['title'])

new.seal()

​
WAL Size and Capacity

The Write-Ahead Log (WAL) size scales with file capacity:
File CapacityWAL SizeCheckpoint Threshold
< 100 MB1 MB768 KB (75%)
< 1 GB4 MB3 MB (75%)
< 10 GB16 MB12 MB (75%)
≥ 10 GB64 MB48 MB (75%)
The WAL checkpoints automatically when it reaches 75% capacity, or you can force a checkpoint with seal().

​
Monitoring Capacity

​
Environment Variables

# Set default capacity for new files
export MEMVID_DEFAULT_TIER=dev

​
In Scripts

from memvid_sdk import use

def check_capacity_before_ingest(path: str, needed_bytes: int) -> bool:
    """Check if there's enough capacity before ingesting."""
    mem = use('basic', path, read_only=True)
    stats = mem.stats()

    available = stats['capacity_bytes'] - stats['size_bytes']
    if available < needed_bytes:
        print(f"Warning: Only {available} bytes available, need {needed_bytes}")
        return False
    return True

# Usage
if check_capacity_before_ingest('knowledge.mv2', 50_000_000):
    mem = use('basic', 'knowledge.mv2')
    mem.put(file='large-file.pdf')
    mem.seal()

​
Best Practices

​
Capacity Planning

  1. Start small: Begin with the free tier for testing
  2. Monitor usage: Check storage_utilisation_percent regularly
  3. Plan ahead: Upgrade before hitting capacity limits
  4. Use compression: Enable vector compression for large collections

​
Storage Optimization

  1. Batch ingestion: Use put_many() for better storage efficiency
  2. Vector compression: 16x smaller vectors with minimal quality loss
  3. Clean up deletions: Run --vacuum after bulk deletes
  4. Choose appropriate tier: Match tier to your use case

​
Error Handling

Always handle capacity errors gracefully: 
from memvid_sdk import use, CapacityExceededError

def safe_put(mem, text: str, title: str) -> bool:
    try:
        mem.put(text=text, title=title)
        return True
    except CapacityExceededError:
        print(f"Capacity exceeded, skipping: {title}")
        return False

​
Next Steps

Memory Architecture

Understand the internal structure of .mv2 files

Troubleshooting

Solve common capacity and error issues