Memvid Memory Skill

Organized interface for memvid-cli - single-file AI memory with hybrid search, entity extraction, and persistent storage.

Core Concepts

What is Memvid?

• •Single .mv2 file containing all data, indexes, and embeddings
• •No database, no servers, no cloud dependencies
• •Git-friendly (can commit, scp, share the file)
• •Hybrid search: BM25 lexical + vector similarity
• •Entity extraction via Memory Cards (O(1) lookups)

Memory File Location: ./memory.mv2 (project root, same level as .git)

Embedding Model: text-embedding-3-large (3072 dimensions) via -m openai-large

Environment Setup

OPENAI_API_KEY is automatically loaded from .mcp-credentials.json via:

source ~/.config/opencode/scripts/load-mcp-credentials-safe.sh

This happens automatically in OpenCode workflows.

Common Operations

1. Search Memory

Semantic Search (uses embeddings):

memvid find ./memory.mv2 --query "your search query" --mode sem --top-k 10 -m openai-large

Lexical Search (keyword-based, fast):

memvid find ./memory.mv2 --query "exact keywords" --mode lex --top-k 10

Auto Mode (automatic selection):

memvid find ./memory.mv2 --query "your query" --mode auto --top-k 10

Search Modes:

• •--mode sem: Vector/semantic search (meaning-based)
• •--mode lex: BM25 lexical search (keyword-based)
• •--mode auto: Automatic selection

2. Store Memory

With Embeddings (recommended):

echo '{"title":"Topic Name","label":"procedure","text":"Full description of what was learned"}' | memvid put ./memory.mv2 --embedding -m openai-large

Quick Text (with label):

echo "Key insight about topic" | memvid put ./memory.mv2 --label fact --embedding -m openai-large

From File:

memvid put ./memory.mv2 --input document.pdf --embedding -m openai-large

Labels (use Graphiti convention):

• •procedure: Workflows and multi-step processes
• •preference: Coding patterns and preferences
• •fact: Key insights, gotchas, important details

3. Entity State Lookup

Check entity state (O(1) lookup via Memory Cards):

memvid state ./memory.mv2 "EntityName"

Returns structured facts about the entity (employer, role, relationships, etc.).

4. Check Statistics

memvid stats ./memory.mv2

Shows:

• •Frame count
• •Storage usage
• •Embedding dimensions
• •Index status
• •Quality metrics

5. Ask Questions (LLM-powered Q&A)

memvid ask ./memory.mv2 --question "What did we decide about authentication?" --use-model openai

Returns sourced answers with citations.

6. Timeline and History

memvid timeline ./memory.mv2

View chronological history of stored memories.

Workflow Integration

At Task Start (AGENTS.md Pattern)

Search for relevant context:

source ~/.config/opencode/scripts/load-mcp-credentials-safe.sh
memvid find ./memory.mv2 --query "[task description]" --mode sem --top-k 10 -m openai-large

At Task End (AGENTS.md Pattern)

Store learnings:

source ~/.config/opencode/scripts/load-mcp-credentials-safe.sh
echo '{"title":"[Topic]","label":"procedure","text":"[What was learned]"}' | memvid put ./memory.mv2 --embedding -m openai-large

Two-Strike Rule Integration

After 2 failed fixes, search for similar past issues:

memvid find ./memory.mv2 --query "error debugging failed fix" --mode sem --top-k 5 -m openai-large

Storage Guidelines

When to Store:

• •Solution differed from initial approach
• •Debugging revealed non-obvious cause
• •Pattern discovered that should be reused
• •Decision made with important context

When to Skip:

• •Behavior matched documentation/expectation
• •Trivial or well-known information
• •Temporary or session-specific data

Storage Optimization:

# Vector compression (16x storage savings)
memvid put ./memory.mv2 --input file.pdf --embedding --vector-compression -m openai-large

Advanced Features

Enrichment (Entity Extraction)

# Extract entities and relationships
memvid enrich ./memory.mv2 --engine rules

Creates Memory Cards for O(1) entity lookups.

Session Replay (Time Travel)

# Start recording session
memvid session start ./memory.mv2 --name "task-name"

# End session
memvid session end ./memory.mv2

# Replay with different parameters
memvid session replay ./memory.mv2 --session abc123 --top-k 10

Maintenance

# Rebuild indexes and reclaim space
memvid doctor ./memory.mv2 --vacuum --rebuild-time-index --rebuild-lex-index

Common Patterns

Pattern 1: Research Task Memory

# Store research findings
echo '{"title":"API Authentication Research","label":"procedure","text":"Investigated JWT vs OAuth. Chose JWT for stateless microservices. Refresh token stored in httpOnly cookie, access token in memory. 15min expiry."}' | memvid put ./memory.mv2 --embedding -m openai-large

Pattern 2: Bug Fix Documentation

# Document bug fix
echo '{"title":"React Hydration Error Fix","label":"fact","text":"Hydration errors caused by useLayoutEffect on SSR. Solution: use useEffect or check typeof window !== undefined before DOM access."}' | memvid put ./memory.mv2 --embedding -m openai-large

Pattern 3: Architecture Decision

# Store decision
echo '{"title":"Database Choice Decision","label":"preference","text":"Chose PostgreSQL over MongoDB for e-commerce. Strong ACID guarantees needed for transactions. Referential integrity critical for orders/inventory."}' | memvid put ./memory.mv2 --embedding -m openai-large

Pattern 4: Recall Previous Decision

# Search for past decisions
memvid find ./memory.mv2 --query "why did we choose postgresql database" --mode sem --top-k 5 -m openai-large

Error Handling

Common Issues

Error: Lock failure

• •Cause: File being written by another process
• •Solution: Wait and retry, or check for zombie processes

Error: OPENAI_API_KEY not found

• •Cause: Environment variable not set
• •Solution: Run source ~/.config/opencode/scripts/load-mcp-credentials-safe.sh

Error: Capacity exceeded

• •Cause: Free tier 50MB limit reached
• •Solution: Use --vector-compression or upgrade plan

Warning: Uncompressed vectors

• •Cause: Large embeddings without compression
• •Solution: Add --vector-compression flag (16x smaller)

Performance Tips

1. •Use lexical search for exact keywords (--mode lex)
2. •Use semantic search for concepts (--mode sem)
3. •Enable vector compression for large datasets (--vector-compression)
4. •Batch operations when storing multiple entries
5. •Regular maintenance (memvid doctor monthly)

Integration with AGENTS.md Tiers

Tier 1 (<30 lines):

• •Memvid search: Optional
• •Store: Optional (only if useful pattern discovered)

Tier 2 (30-100 lines):

• •Memvid search: MANDATORY (skip only if <30s task)
• •Store: MANDATORY

Tier 3 (100+ lines):

• •Memvid search: MANDATORY (before exploration)
• •Store: MANDATORY

Tier 4 (Critical/Deployment):

• •All Tier 3 requirements
• •Store rollback procedures
• •Document deployment decisions

Quick Reference

Notes

• •Use project-relative path: ./memory.mv2 (same level as .git)
• •Flag -m openai-large maps to text-embedding-3-large (3072 dimensions)
• •Memory file is portable: can git commit, scp, share
• •Recommended: Add memory.mv2 to .gitignore to keep learnings local
• •Free tier: 50MB capacity (~194 documents with embeddings)
• •Use --vector-compression to fit ~3000 documents in 50MB