Skip to main content
This guide walks through diagnosing and resolving the most common issues you’ll encounter with Memvid.

​
Quick Diagnosis

Run these commands to quickly identify issues: 
# Check file health
memvid verify knowledge.mv2 --deep

# View file stats
memvid stats knowledge.mv2 --json

# Check for locks
lsof knowledge.mv2

​
Common Issues

​
”File is locked” when opening

  • FileLocked: File is locked by another process
  • Operations hang indefinitely
  • Cannot open file in Python/Node.js
# Find process holding the lock
lsof knowledge.mv2

# Check for zombie processes
ps aux | grep memvid
  1. Wait for the other process to finish
  2. Kill the blocking process (if stuck): 
    kill -9 <PID>
  3. Open in read-only mode: 
    mem = use('basic', 'knowledge.mv2', read_only=True)
  4. Check for crashed processes - if a process crashed while holding a lock, restart your terminal/IDE

​
Search returns no results

  • mem.find() returns empty results
  • CLI search shows “0 results”
  • Expected documents not appearing
# Check if file has content
memvid stats knowledge.mv2

# Check which indices are enabled
memvid info knowledge.mv2

# Try different search modes
memvid find knowledge.mv2 --query "test" --mode lex
memvid find knowledge.mv2 --query "test" --mode sem
  1. Verify content exists: 
    memvid timeline knowledge.mv2 --limit 10
  2. Check search mode - try lex for exact matches, sem for semantic: 
    # Exact keyword match
results = mem.find('exact phrase', mode='lex')

# Semantic/conceptual match
results = mem.find('related concept', mode='sem')
  3. Rebuild indices if they’re corrupted: 
    memvid doctor knowledge.mv2 --rebuild-lex-index --rebuild-vec-index
  4. Check embeddings were enabled during ingestion: 
    memvid put knowledge.mv2 --input doc.pdf --embeddings

​
“CapacityExceeded” error

  • CapacityExceeded: Memory file exceeded capacity limit
  • put() operations fail
  • Cannot add new content
# Check current usage
memvid stats knowledge.mv2 --json | jq '.size_bytes, .capacity_bytes'

# Check ticket info
memvid tickets list knowledge.mv2
  1. Upgrade your plan for more capacity: 
    memvid tickets sync knowledge.mv2 --memory-id YOUR_ID
  2. Delete old content: 
    memvid delete knowledge.mv2 --before "2024-01-01" --yes
  3. Vacuum to reclaim space: 
    memvid doctor knowledge.mv2 --vacuum
  4. Archive and create new file: 
    mv knowledge.mv2 archive/knowledge-$(date +%Y%m%d).mv2
memvid create knowledge.mv2

​
Slow query performance

  • Queries taking >100ms
  • Timeouts on large files
  • High memory usage during search
# Check file size
ls -lh knowledge.mv2

# Check frame count
memvid stats knowledge.mv2 --json | jq '.frame_count'

# Profile a query
time memvid find knowledge.mv2 --query "test" --json
  1. Reduce k value for fewer results: 
    results = mem.find('query', k=5)  # Instead of k=50
  2. Use specific search mode: 
    # Lexical is faster for exact matches
results = mem.find('exact term', mode='lex')
  3. Add scope filters: 
    results = mem.find('query', scope='category:docs')
  4. Enable vector compression for smaller index: 
    memvid put knowledge.mv2 --input docs/ --vector-compression
  5. Split into multiple files for very large datasets: 
    # Query multiple files in parallel
import asyncio

async def search_all(query):
    files = ['docs.mv2', 'wiki.mv2', 'papers.mv2']
    tasks = [search_file(f, query) for f in files]
    return await asyncio.gather(*tasks)

​
Import errors in Python

  • ImportError: cannot import name 'use' from 'memvid_sdk'
  • ModuleNotFoundError: No module named 'memvid_sdk'
  • ImportError: libmemvid.so not found
# Check installation
pip show memvid-sdk

# Check Python version
python --version

# List installed packages
pip list | grep memvid
  1. Install/reinstall the SDK: 
    pip install --upgrade memvid-sdk
  2. Check Python version (requires 3.8+): 
    python3 --version
  3. Use correct virtual environment: 
    source venv/bin/activate
pip install memvid-sdk
  4. On Apple Silicon, ensure you’re using native Python: 
    # Check architecture
python -c "import platform; print(platform.machine())"
# Should show 'arm64' on Apple Silicon

​
Native binding errors in Node.js

  • Error: Cannot find module '../index.node'
  • Error: The module was compiled against a different Node.js version
  • Segmentation fault on import
# Check Node version
node --version

# Check if native module exists
ls node_modules/@memvid/sdk/*.node

# Check platform
node -e "console.log(process.platform, process.arch)"
  1. Reinstall with rebuild: 
    rm -rf node_modules package-lock.json
npm install
  2. Check Node.js version (requires 18+): 
    nvm use 18
npm rebuild
  3. Install build tools if needed: 
    # macOS
xcode-select --install

# Ubuntu
sudo apt install build-essential

# Windows
npm install -g windows-build-tools

​
File corruption after crash

  • CorruptFile: Invalid header magic bytes
  • VerificationFailed: Checksum mismatch
  • File won’t open after system crash
# Verify file integrity
memvid verify knowledge.mv2 --deep

# Check file header
xxd knowledge.mv2 | head -5
  1. Run the doctor command: 
    memvid doctor knowledge.mv2 --vacuum
  2. Rebuild indices: 
    memvid doctor knowledge.mv2 \
  --rebuild-lex-index \
  --rebuild-vec-index \
  --rebuild-time-index
  3. If recovery fails, restore from backup: 
    cp /backups/knowledge.mv2 ./knowledge.mv2
  4. Prevent future corruption:
    • Always call mem.seal() before exiting
    • Use UPS/battery backup for critical systems
    • Enable automatic backups

​
Framework adapter not working

  • mem.tools returns empty or None
  • Framework-specific methods missing
  • Type errors with framework objects
from memvid_sdk import use

mem = use('langchain', 'knowledge.mv2')
print(f"Tools: {mem.tools}")
print(f"Type: {type(mem.tools)}")
  1. Install the framework dependency: 
    # For LangChain
pip install langchain langchain-openai

# For LlamaIndex
pip install llama-index

# For CrewAI
pip install crewai
  2. Use correct adapter name: 
    # Correct
mem = use('langchain', 'knowledge.mv2')
mem = use('llamaindex', 'knowledge.mv2')
mem = use('crewai', 'knowledge.mv2')

# Incorrect
mem = use('lang-chain', 'knowledge.mv2')  # Wrong!
  3. Check framework version compatibility: 
    pip show langchain  # Check version

​
Diagnostic Commands

​
Full Health Check

#!/bin/bash
# health-check.sh

FILE=$1

echo "=== Memvid Health Check ==="
echo "File: $FILE"
echo ""

echo "--- Basic Info ---"
memvid stats "$FILE" --json | jq '.'

echo ""
echo "--- Verification ---"
memvid verify "$FILE" --deep

echo ""
echo "--- Lock Status ---"
lsof "$FILE" 2>/dev/null || echo "No locks detected"

echo ""
echo "--- Ticket Info ---"
memvid tickets list "$FILE"

​
Performance Profile

import time
from memvid_sdk import use

def profile_operations(filepath: str):
    """Profile common Memvid operations."""

    print(f"Profiling: {filepath}\n")

    mem = use('basic', filepath, read_only=True)

    # Profile search
    start = time.perf_counter()
    for _ in range(10):
        mem.find('test query', k=10)
    search_time = (time.perf_counter() - start) / 10
    print(f"Average search time: {search_time*1000:.2f}ms")

    # Profile ask
    start = time.perf_counter()
    mem.ask('What is this about?')
    ask_time = time.perf_counter() - start
    print(f"Ask time: {ask_time*1000:.2f}ms")

    # Profile timeline
    start = time.perf_counter()
    mem.timeline(limit=100)
    timeline_time = time.perf_counter() - start
    print(f"Timeline time: {timeline_time*1000:.2f}ms")

    print("\n✅ Profiling complete")

profile_operations('knowledge.mv2')

​
Still Having Issues?

Error Reference

Complete error code documentation

GitHub Issues

Search existing issues or report new ones

Discord Community

Get real-time help from the community

Email Support

Contact our support team