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

# Tickets & Capacity

> Manage access tickets, capacity limits, and subscription plans

Commands for managing your memory file's capacity and syncing tickets from the dashboard.

***

## Overview

Memvid uses a ticket system for capacity management:

* **Tickets** authorize storage capacity
* **Binding** connects a file to a dashboard memory
* **Plans** determine your capacity limits

```mermaid theme={null}
flowchart LR
    D[Dashboard] -->|Upgrade Plan| T[New Ticket]
    T -->|memvid tickets sync| M[knowledge.mv2]
    M -->|Increased Capacity| S[Store More Data]
```

***

## memvid tickets sync

Synchronize tickets from the dashboard.

### Synopsis

```bash theme={null}
memvid tickets sync <FILE> --memory-id <ID> [OPTIONS]
```

### Arguments

| Argument | Description           |
| -------- | --------------------- |
| `FILE`   | Path to the .mv2 file |

### Options

| Option                | Description                          | Default  |
| --------------------- | ------------------------------------ | -------- |
| `--memory-id <ID>`    | Memory ID (UUID or 24-char ObjectId) | Required |
| `--json`              | JSON output                          | Disabled |
| `--lock-timeout <MS>` | Wait timeout for lock                | 250ms    |
| `--force`             | Force lock takeover                  | Disabled |

### Examples

```bash theme={null}
# Sync with dashboard memory
memvid tickets sync project.mv2 --memory-id mem_abc123

# With environment API key
MEMVID_API_KEY=mv_live_xxx memvid tickets sync project.mv2 --memory-id mem_abc123
```

### Response

```
Syncing tickets for project.mv2...

Memory ID: mem_abc123
Memory Name: Production Memory

Ticket applied:
  Issuer: memvid.com
  Sequence: 43 (was: 42)
  Capacity: 1 GB
  Expires in: 30d

Binding status:
  Already bound: yes

Sync complete.
```

### JSON Output

```json theme={null}
{
  "success": true,
  "memory_id": "mem_abc123",
  "already_bound": true,
  "ticket": {
    "issuer": "memvid.com",
    "seq_no": 43,
    "capacity_bytes": 1073741824,
    "expires_in_secs": 2592000
  }
}
```

***

## memvid tickets apply

Apply a ticket to a memory file.

### Synopsis

```bash theme={null}
memvid tickets apply <FILE> --memory-id <ID> [OPTIONS]
```

### Options

| Option             | Description           |
| ------------------ | --------------------- |
| `--memory-id <ID>` | Memory ID (required)  |
| `--from-api`       | Fetch ticket from API |
| `--json`           | JSON output           |

### Examples

```bash theme={null}
# Apply ticket from API
memvid tickets apply project.mv2 --memory-id mem_abc123 --from-api
```

***

## memvid tickets issue

Issue a new ticket (for self-hosted/enterprise).

### Synopsis

```bash theme={null}
memvid tickets issue <FILE> [OPTIONS]
```

### Options

| Option                | Description           | Default  |
| --------------------- | --------------------- | -------- |
| `--issuer <ISSUER>`   | Ticket issuer         | Required |
| `--seq <SEQ>`         | Sequence number       | Required |
| `--expires-in <SECS>` | Expiration in seconds | None     |
| `--capacity <BYTES>`  | Capacity in bytes     | None     |
| `--json`              | JSON output           | Disabled |

### Examples

```bash theme={null}
# Issue enterprise ticket
memvid tickets issue project.mv2 \
  --issuer "enterprise.example.com" \
  --seq 1 \
  --expires-in 31536000 \
  --capacity 10737418240
```

***

## memvid tickets list

Show current ticket information.

### Synopsis

```bash theme={null}
memvid tickets list <FILE> [OPTIONS]
```

### Options

| Option   | Description |
| -------- | ----------- |
| `--json` | JSON output |

### Examples

```bash theme={null}
memvid tickets list project.mv2
```

### Response

```
Ticket for project.mv2

Status: ACTIVE

Ticket Details:
  Issuer: memvid.com
  Sequence: 43
  Capacity: 1 GB
  Expires: 2024-02-20T10:30:00Z (30d remaining)

Usage:
  Current size: 125.6 MB
  Capacity: 1 GB
  Available: 898.4 MB
  Usage: 12.2%
```

### JSON Output

```json theme={null}
{
  "path": "project.mv2",
  "active": true,
  "ticket": {
    "issuer": "memvid.com",
    "seq_no": 43,
    "capacity_bytes": 1073741824,
    "expires_at": "2024-02-20T10:30:00Z",
    "expires_in_secs": 2592000
  },
  "usage": {
    "current_bytes": 131691315,
    "capacity_bytes": 1073741824,
    "available_bytes": 942050509,
    "usage_percent": 12.2
  }
}
```

***

## memvid tickets revoke

Clear ticket metadata from a file.

### Synopsis

```bash theme={null}
memvid tickets revoke <FILE> [OPTIONS]
```

### Options

| Option                | Description         |
| --------------------- | ------------------- |
| `--json`              | JSON output         |
| `--lock-timeout <MS>` | Wait timeout        |
| `--force`             | Force lock takeover |

### Examples

```bash theme={null}
memvid tickets revoke project.mv2
```

***

## memvid plan show

Show current plan and capacity.

### Synopsis

```bash theme={null}
memvid plan show [OPTIONS]
```

### Options

| Option   | Description |
| -------- | ----------- |
| `--json` | JSON output |

### Examples

```bash theme={null}
memvid plan show
```

### Response

```
Memvid Plan

Plan: Developer
Status: Active

Limits:
  Memories: 10 / 25
  Total capacity: 2.5 GB / 10 GB
  API calls: 45,231 / 100,000 (monthly)

Features:
  - Semantic search: included
  - LLM enrichment: included
  - Table extraction: included
  - Encryption: included
  - Priority support: not included

Billing:
  Next renewal: 2024-02-01
  Amount: $29/month

Upgrade: https://memvid.com/dashboard/plan
```

### JSON Output

```json theme={null}
{
  "plan": "developer",
  "status": "active",
  "limits": {
    "memories": {"used": 10, "limit": 25},
    "capacity_bytes": {"used": 2684354560, "limit": 10737418240},
    "api_calls": {"used": 45231, "limit": 100000, "period": "monthly"}
  },
  "features": {
    "semantic_search": true,
    "llm_enrichment": true,
    "table_extraction": true,
    "encryption": true,
    "priority_support": false
  },
  "billing": {
    "next_renewal": "2024-02-01",
    "amount_cents": 2900,
    "currency": "usd"
  }
}
```

***

## memvid plan sync

Sync plan ticket from dashboard.

### Synopsis

```bash theme={null}
memvid plan sync [OPTIONS]
```

### Options

| Option   | Description |
| -------- | ----------- |
| `--json` | JSON output |

### Examples

```bash theme={null}
MEMVID_API_KEY=mv_live_xxx memvid plan sync
```

***

## memvid plan clear

Clear cached plan ticket.

### Synopsis

```bash theme={null}
memvid plan clear [OPTIONS]
```

### Options

| Option   | Description |
| -------- | ----------- |
| `--json` | JSON output |

***

## Bind and Unbind Memory

### Bind Memory

Associate a local memory file with a dashboard memory ID:

```bash theme={null}
memvid bind knowledge.mv2 --memory-id YOUR_MEMORY_ID
```

After binding, you can sync tickets without specifying the memory ID each time.

### Unbind Memory

Remove the dashboard association from a local file:

```bash theme={null}
memvid unbind knowledge.mv2
```

<Warning>
  After unbinding, you'll need to rebind before syncing tickets again.
</Warning>

***

## Best Practices

### Initial Setup

```bash theme={null}
# 1. Create memory file
memvid create project.mv2

# 2. Sync with dashboard (binds and applies ticket)
MEMVID_API_KEY=mv_live_xxx memvid tickets sync project.mv2 --memory-id mem_abc123

# 3. Verify binding
memvid binding project.mv2
```

### Monitoring Capacity

```bash theme={null}
# Check current usage
memvid tickets list project.mv2

# Check plan limits
memvid plan show

# Script to alert on low capacity
USAGE=$(memvid tickets list project.mv2 --json | jq '.usage.usage_percent')
if (( $(echo "$USAGE > 80" | bc -l) )); then
  echo "Warning: Memory at ${USAGE}% capacity"
fi
```

### Refreshing Tickets

```bash theme={null}
# Tickets are refreshed automatically on sync
memvid tickets sync project.mv2 --memory-id mem_abc123

# Force refresh (re-fetch from API)
memvid tickets apply project.mv2 --memory-id mem_abc123 --from-api
```

### Enterprise Self-Hosting

```bash theme={null}
# Issue tickets with your own signing key
memvid tickets issue project.mv2 \
  --issuer "internal.company.com" \
  --seq 1 \
  --expires-in 31536000 \
  --capacity 107374182400  # 100 GB

# Verify ticket
memvid tickets list project.mv2
```

### Capacity Planning

```bash theme={null}
# Estimate storage needs
# ~1 MB per 1000 documents (text only)
# ~10 MB per 1000 documents (with embeddings)
# ~50 MB per 1000 documents (with PDFs)

# Check current size
memvid stats project.mv2 --json | jq '.size_bytes'

# Project growth
# size_per_doc * docs_per_month * months
```

***

## Environment Variables

| Variable         | Description                                   |
| ---------------- | --------------------------------------------- |
| `MEMVID_API_KEY` | API key for ticket sync                       |
| `MEMVID_API_URL` | Custom API endpoint (default: api.memvid.com) |

```bash theme={null}
# Set API key globally
export MEMVID_API_KEY=mv_live_xxx

# Then sync without --api-key flag
memvid tickets sync knowledge.mv2 --memory-id abc-123
```

***

## Troubleshooting

### CapacityExceeded Error

If you see this error when adding content:

```
Error: CapacityExceeded: Memory file exceeded capacity limit
```

**Solutions:**

1. **Upgrade and sync:**
   ```bash theme={null}
   # After upgrading in dashboard
   memvid tickets sync knowledge.mv2 --memory-id YOUR_ID
   ```

2. **Delete old content:**
   ```bash theme={null}
   memvid delete knowledge.mv2 --frame-id 42 --yes
   memvid doctor knowledge.mv2 --vacuum
   ```

3. **Create a new memory:**
   ```bash theme={null}
   mv knowledge.mv2 knowledge-archive.mv2
   memvid create knowledge.mv2
   ```

### Ticket Sync Failed

If sync fails:

```bash theme={null}
# Check your API key is set
echo $MEMVID_API_KEY

# Verify memory ID is correct
memvid tickets list knowledge.mv2

# Try with explicit API key
MEMVID_API_KEY=mv_live_xxx memvid tickets sync knowledge.mv2 --memory-id YOUR_ID
```

### Invalid Ticket Error

If you see `TicketInvalid` or `TicketReplay`:

```bash theme={null}
# Re-sync to get fresh ticket
memvid tickets sync knowledge.mv2 --memory-id YOUR_ID
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Maintenance & Repair" icon="wrench" href="/cli/maintenance-and-tickets">
    Verify and repair memory files
  </Card>

  <Card title="Error Reference" icon="circle-exclamation" href="/errors/reference">
    All error codes and solutions
  </Card>
</CardGroup>