---

name: memvid description: Single-file AI memory with memvid-cli for persistent knowledge storage and retrieval using text-embedding-3-large (3072 dimensions). Use when storing learnings, searching past context, managing session memory, or implementing long-term memory for AI agents. Triggers include "remember", "recall", "search memory", "store this", "what did we learn", or any task requiring persistent memory across sessions. license: MIT compatibility: opencode

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:

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

This happens automatically in OpenCode workflows.

Common Operations

1. Search Memory

Semantic Search (uses embeddings):

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

Lexical Search (keyword-based, fast):

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

Auto Mode (automatic selection):

Copymemvid 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):

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

Quick Text (with label):

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

From File:

Copymemvid 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):

Copymemvid state ./memory.mv2 "EntityName"

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

4. Check Statistics

Copymemvid stats ./memory.mv2

Shows:

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

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

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

Returns sourced answers with citations.

6. Timeline and History

Copymemvid timeline ./memory.mv2

View chronological history of stored memories.

Workflow Integration

At Task Start (AGENTS.md Pattern)

Search for relevant context:

Copysource ~/.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:

Copysource ~/.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:

Copymemvid 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:

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

Advanced Features

Enrichment (Entity Extraction)

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

Creates Memory Cards for O(1) entity lookups.

Session Replay (Time Travel)

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

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

Common Patterns

Pattern 1: Research Task Memory

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

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

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

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