Skip to main content
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