> ## 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. # Memory Cards & Enrichment > Extract structured knowledge from your documents with entity-attribute-value triples Memory cards transform unstructured text into **structured knowledge** - entity-attribute-value triples that enable O(1) lookups, fact tracking, and relationship queries. Enrichment is the process of automatically extracting these cards from your content. *** ## What Are Memory Cards? A memory card captures a single piece of knowledge: ```json theme={null} { "entity": "John Smith", "slot": "job_title", "value": "Senior Engineer", "kind": "fact", "confidence": 0.92, "source_frame": "frame_abc123", "extracted_at": "2024-12-31T10:30:00Z" } ``` | Field | Description | | -------------- | ---------------------------------------------------------- | | `entity` | The subject (person, company, concept) | | `slot` | The attribute or property name | | `value` | The current value | | `kind` | Type: fact, preference, event, profile, relationship, goal | | `confidence` | Extraction confidence (0.0-1.0) | | `source_frame` | Which document this came from | *** ## Memory Card Types ### Facts Objective information that can be verified: ``` Entity: Acme Corp Slot: headquarters Value: San Francisco, CA Entity: Python Slot: creator Value: Guido van Rossum ``` ### Preferences Subjective choices or opinions: ``` Entity: user Slot: preferred_language Value: TypeScript Entity: team Slot: meeting_day Value: Tuesday ``` ### Events Time-bound occurrences: ``` Entity: Project Alpha Slot: launch_date Value: 2024-03-15 Entity: Q4 Review Slot: scheduled Value: 2024-12-20T14:00:00Z ``` ### Relationships Connections between entities: ``` Entity: John Smith Slot: reports_to Value: Jane Doe Entity: Acme Corp Slot: acquired Value: StartupXYZ ``` ### Profiles Descriptive attributes: ``` Entity: Sarah Chen Slot: expertise Value: Machine Learning, NLP Entity: Product Team Slot: size Value: 12 members ``` *** ## Enrichment Engines Memvid supports multiple extraction engines with different speed/quality/cost tradeoffs: | Engine | Speed | Quality | Cost | Requires | | --------- | ------- | --------- | ------ | ------------------------------ | | `rules` | Fastest | Basic | Free | Nothing | | `candle` | Fast | Good | Free | Auto-downloads model (\~2.4GB) | | `groq` | Fast | Excellent | Low | `GROQ_API_KEY` | | `openai` | Medium | Excellent | Medium | `OPENAI_API_KEY` | | `claude` | Medium | Best | Higher | `ANTHROPIC_API_KEY` | | `gemini` | Fast | Excellent | Low | `GOOGLE_API_KEY` | | `xai` | Fast | Excellent | Medium | `XAI_API_KEY` | | `mistral` | Fast | Good | Low | `MISTRAL_API_KEY` | ### Rules Engine Pattern-based extraction using regex. Fast and free but limited: ```bash theme={null} memvid enrich memory.mv2 --engine rules ``` Extracts: * Email addresses → `entity: , slot: email` * Phone numbers → `entity: contact, slot: phone` * Dates → `entity: document, slot: date_mentioned` * URLs → `entity: document, slot: link` ### Candle Engine (Local LLM) Runs Phi-3.5-mini locally via HuggingFace Candle: ```bash theme={null} memvid enrich memory.mv2 --engine candle ``` * First run downloads \~2.4GB model * No API key required * Good quality, runs on CPU (GPU optional) * Slower than API-based engines ### Cloud Engines For best quality, use cloud LLMs: ```bash theme={null} # Groq (fastest cloud option) export GROQ_API_KEY=gsk_xxx memvid enrich memory.mv2 --engine groq # OpenAI export OPENAI_API_KEY=sk-xxx memvid enrich memory.mv2 --engine openai # Claude (highest quality) export ANTHROPIC_API_KEY=sk-ant-xxx memvid enrich memory.mv2 --engine claude # Gemini export GOOGLE_API_KEY=xxx memvid enrich memory.mv2 --engine gemini ``` *** ## CLI Commands ### Enrich: Extract Memory Cards ```bash theme={null} # Basic enrichment with rules (fast, free) memvid enrich memory.mv2 --engine rules # Enrich with Groq (recommended balance) memvid enrich memory.mv2 --engine groq # Enrich with verbose output memvid enrich memory.mv2 --engine groq --verbose # Force re-enrichment of all frames memvid enrich memory.mv2 --engine claude --force # Parallel processing for speed memvid enrich memory.mv2 --engine groq --workers 20 --batch-size 10 ``` Output: ``` Enriching memory.mv2 with groq engine... Processing: 150 frames Extracted: 423 memory cards Entities: 87 unique Time: 12.3s Top entities: - John Smith (34 facts) - Acme Corp (28 facts) - Project Alpha (19 facts) ``` ### Memories: View Extracted Cards ```bash theme={null} # List all memory cards memvid memories memory.mv2 # JSON output memvid memories memory.mv2 --json ``` Output: ``` Memory Cards (423 total) Entity: John Smith job_title: Senior Engineer (confidence: 0.94) team: Platform (confidence: 0.89) reports_to: Jane Doe (confidence: 0.91) expertise: Rust, Python (confidence: 0.87) Entity: Acme Corp headquarters: San Francisco (confidence: 0.96) founded: 2015 (confidence: 0.92) employees: 250 (confidence: 0.78) ... ``` ### State: O(1) Entity Lookup Get the current state of any entity instantly: ```bash theme={null} # Query single entity memvid state memory.mv2 --entity "John Smith" # JSON output memvid state memory.mv2 --entity "John Smith" --json ``` Output: ``` Entity: John Smith Current State: job_title: Senior Engineer team: Platform reports_to: Jane Doe expertise: Rust, Python location: San Francisco start_date: 2022-03-15 Last updated: 2024-12-30T14:22:00Z Source frames: 12 ``` ### Facts: Audit Fact History Track how facts changed over time with full provenance: ```bash theme={null} # All facts for an entity memvid facts memory.mv2 --entity "John Smith" # Filter by predicate memvid facts memory.mv2 --entity "John Smith" --predicate job_title # Filter by source frame memvid facts memory.mv2 --frame-id frame_abc123 # JSON output memvid facts memory.mv2 --entity "John Smith" --json ``` Output: ``` Fact History: John Smith → job_title 1. "Junior Engineer" (2024-01-15) Source: frame_001 (onboarding.pdf) Confidence: 0.91 2. "Engineer" (2024-06-01) Source: frame_089 (promotion_announcement.md) Confidence: 0.94 Relation: UPDATES previous 3. "Senior Engineer" (2024-11-15) Source: frame_142 (team_update.md) Confidence: 0.94 Relation: UPDATES previous Current value: Senior Engineer ``` ### Export: Standard Formats Export facts to standard knowledge graph formats: ```bash theme={null} # N-Triples (RDF) memvid export memory.mv2 --format ntriples --out facts.nt # JSON memvid export memory.mv2 --format json --out facts.json # CSV memvid export memory.mv2 --format csv --out facts.csv # Filter by entity memvid export memory.mv2 --format json --filter-entity "Acme Corp" --out acme.json ``` N-Triples output: ``` "Senior Engineer" . . "San Francisco" . "2015" . ``` ### Schema: Predicate Management Define and view predicate schemas: ```bash theme={null} # Infer schema from existing facts memvid schema infer memory.mv2 # List current schemas memvid schema list memory.mv2 # Manually define predicate type memvid schema set memory.mv2 job_title string memvid schema set memory.mv2 employee_count integer memvid schema set memory.mv2 is_active boolean ``` Output: ``` Predicate Schema: job_title: string (inferred from 45 facts) team: string (inferred from 32 facts) employee_count: integer (inferred from 12 facts) founded: date (inferred from 8 facts) headquarters: string (inferred from 8 facts) is_public: boolean (inferred from 5 facts) ``` *** ## SDK Usage ### Python ```python theme={null} from memvid import use mem = use('basic', 'memory.mv2') # Enrich documents mem.enrich(engine="groq") # Get current entity state (O(1) lookup) john = mem.get_entity_state("John Smith") print(f"Job: {john['job_title']}") print(f"Team: {john['team']}") # Get all facts for an entity facts = mem.get_facts(entity="John Smith") for fact in facts: print(f"{fact.slot}: {fact.value} (from {fact.source_frame})") # Get fact history for specific attribute title_history = mem.get_facts( entity="John Smith", predicate="job_title" ) for fact in title_history: print(f"{fact.extracted_at}: {fact.value}") # Query preferences prefs = mem.get_preferences(entity="user") print(f"Preferred language: {prefs.get('preferred_language')}") # Get memory timeline timeline = mem.get_memory_timeline(entity="Project Alpha") for event in timeline: print(f"{event.timestamp}: {event.slot} = {event.value}") ``` ### Node.js ```typescript theme={null} import { use } from '@anthropics/memvid' const mem = await use('basic', 'memory.mv2') // Enrich documents await mem.enrich({ engine: "groq" }) // Get current entity state const john = await mem.getEntityState("John Smith") console.log(`Job: ${john.job_title}`) console.log(`Team: ${john.team}`) // Get all facts for an entity const facts = await mem.getFacts({ entity: "John Smith" }) for (const fact of facts) { console.log(`${fact.slot}: ${fact.value}`) } // Query by predicate const titles = await mem.getFacts({ entity: "John Smith", predicate: "job_title" }) ``` *** ## Version Relations Memory cards track how values change over time: | Relation | Meaning | | ---------- | ------------------------------ | | `SETS` | Initial value (no previous) | | `UPDATES` | Replaces previous value | | `EXTENDS` | Adds to previous value (lists) | | `RETRACTS` | Removes/invalidates previous | Example tracking: ``` Frame 001: John Smith → team = "Backend" [SETS] Frame 045: John Smith → team = "Platform" [UPDATES] Frame 089: John Smith → team = "Platform" [no change, skipped] Frame 112: John Smith → team = "Infrastructure" [UPDATES] ``` Query the current value: ```bash theme={null} memvid state memory.mv2 --entity "John Smith" # team: Infrastructure ``` Query the history: ```bash theme={null} memvid facts memory.mv2 --entity "John Smith" --predicate team # Shows all 3 values with timestamps and sources ``` *** ## Deduplication Memory cards are automatically deduplicated: * **Same entity + slot**: Keeps highest confidence value * **Same value**: Skips if already exists * **Different sources**: Tracks all sources for provenance ```python theme={null} # These produce one card, not three mem.put("John works as an engineer") # Extracts: job_title = engineer mem.put("John is an engineer at Acme") # Same fact, different source mem.put("John Smith - Engineer") # Same fact, skipped ``` *** ## Incremental Enrichment By default, enrichment only processes new frames: ```bash theme={null} # First run: processes all 100 frames memvid enrich memory.mv2 --engine groq # Enriched 100 frames, extracted 250 cards # Add more documents memvid put memory.mv2 --input new_docs/ # Second run: only processes new frames memvid enrich memory.mv2 --engine groq # Enriched 15 frames (85 already enriched), extracted 42 cards ``` Force full re-enrichment: ```bash theme={null} memvid enrich memory.mv2 --engine claude --force ``` *** ## Performance Tuning ### Parallel Workers ```bash theme={null} # More workers = faster (but more API calls) memvid enrich memory.mv2 --engine groq --workers 20 # Fewer workers = slower but less rate limiting memvid enrich memory.mv2 --engine openai --workers 5 ``` ### Batch Size ```bash theme={null} # Larger batches = fewer API calls memvid enrich memory.mv2 --engine groq --batch-size 20 # Smaller batches = more granular progress memvid enrich memory.mv2 --engine claude --batch-size 5 ``` ### Engine Selection by Use Case | Use Case | Recommended Engine | | --------------------- | ------------------ | | Quick testing | `rules` | | Offline/privacy | `candle` | | Production (balanced) | `groq` | | Maximum accuracy | `claude` | | Cost-sensitive | `gemini` | *** ## Use Cases ### Personal Knowledge Management Track facts about people, projects, and topics: ```bash theme={null} # Ingest your notes memvid put brain.mv2 --input ~/notes/ # Extract knowledge memvid enrich brain.mv2 --engine groq # Query what you know about someone memvid state brain.mv2 --entity "Sarah from Marketing" ``` ### Meeting Minutes Extract action items and decisions: ```bash theme={null} # Transcribe and ingest memvid put meetings.mv2 --input recording.mp3 # Enrich with Claude for best accuracy memvid enrich meetings.mv2 --engine claude # Find all action items assigned to John memvid facts meetings.mv2 --entity "John" --predicate assigned_action ``` ### Research Papers Build a knowledge graph from literature: ```bash theme={null} # Ingest papers memvid put research.mv2 --input papers/ # Extract entities and relationships memvid enrich research.mv2 --engine groq # Export to knowledge graph format memvid export research.mv2 --format ntriples --out research.nt ``` ### Customer Information Track customer preferences and history: ```bash theme={null} # Ingest support tickets memvid put customers.mv2 --input tickets/ # Extract customer facts memvid enrich customers.mv2 --engine groq # Get customer state memvid state customers.mv2 --entity "customer_12345" ``` *** ## Best Practices ### 1. Choose the Right Engine Start with `rules` for testing, graduate to `groq` for production: ```bash theme={null} # Development memvid enrich memory.mv2 --engine rules --verbose # Production memvid enrich memory.mv2 --engine groq ``` ### 2. Enrich After Bulk Imports Wait until documents are loaded before enriching: ```bash theme={null} # Load all documents first memvid put memory.mv2 --input docs/ # Then enrich in one pass memvid enrich memory.mv2 --engine groq ``` ### 3. Use Incremental Mode Let Memvid track what's been enriched: ```bash theme={null} # Default: only enriches new frames memvid enrich memory.mv2 --engine groq ``` ### 4. Export for Integration Use exports to integrate with other tools: ```bash theme={null} # For graph databases memvid export memory.mv2 --format ntriples --out facts.nt # For spreadsheets memvid export memory.mv2 --format csv --out facts.csv ``` *** ## Troubleshooting ### "No memory cards extracted" 1. Check if frames have text content: ```bash theme={null} memvid stats memory.mv2 ``` 2. Try verbose mode to see extraction: ```bash theme={null} memvid enrich memory.mv2 --engine rules --verbose ``` 3. Content may be too short or unstructured ### "API rate limited" Reduce workers and increase batch size: ```bash theme={null} memvid enrich memory.mv2 --engine groq --workers 5 --batch-size 20 ``` ### "Low confidence scores" * Try a better engine (`claude` > `groq` > `rules`) * Content may be ambiguous * Check source document quality ### "Missing expected entities" 1. Check if entity appears in source: ```bash theme={null} memvid find memory.mv2 --query "Entity Name" ``` 2. Force re-enrichment: ```bash theme={null} memvid enrich memory.mv2 --engine claude --force ``` *** ## Next Steps Query entity relationships with Logic Mesh How duplicate content is handled