> ## 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.

# Storage Capacity

> Understanding storage tiers and capacity management in Memvid

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:

| Tier       | Capacity  | WAL Size | Typical Use                           |
| ---------- | --------- | -------- | ------------------------------------- |
| Free       | 50 MB     | 70 KB    | Personal notes, small projects        |
| Starter    | 25 GB     | 70 KB    | Development, prototyping              |
| Pro        | 125 GB    | 70 KB    | Production workloads                  |
| Enterprise | Unlimited | 70 KB    | Scale and mission-critical production |

### Creating with a Tier

```bash theme={null}
# 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
```

```python theme={null}
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

```bash theme={null}
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

```bash theme={null}
memvid stats knowledge.mv2 --json
```

```json theme={null}
{
  "frame_count": 150,
  "active_frame_count": 148,
  "size_bytes": 54945587,
  "capacity_bytes": 1073741824,
  "storage_utilisation_percent": 5.2
}
```

### Python SDK

```python theme={null}
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

```typescript theme={null}
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

```python theme={null}
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

```typescript theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# Create new file with larger capacity
memvid create new-knowledge.mv2 --tier dev

# Export content from old file (using SDK)
```

```python theme={null}
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 Capacity | WAL Size | Checkpoint Threshold |
| ------------- | -------- | -------------------- |
| \< 100 MB     | 1 MB     | 768 KB (75%)         |
| \< 1 GB       | 4 MB     | 3 MB (75%)           |
| \< 10 GB      | 16 MB    | 12 MB (75%)          |
| ≥ 10 GB       | 64 MB    | 48 MB (75%)          |

The WAL checkpoints automatically when it reaches 75% capacity, or you can force a checkpoint with `seal()`.

***

## Monitoring Capacity

### Environment Variables

```bash theme={null}
# Set default capacity for new files
export MEMVID_DEFAULT_TIER=dev
```

### In Scripts

```python theme={null}
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:

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Memory Architecture" icon="database" href="/concepts/memory-architecture">
    Understand the internal structure of .mv2 files
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting/cli">
    Solve common capacity and error issues
  </Card>
</CardGroup>