Memory Cards & Enrichment

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:

{
  "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:

memvid enrich memory.mv2 --engine rules

Extracts:

Email addresses → entity: <local>, 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:

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:

# 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

# 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

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

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

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

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

<John_Smith> <job_title> "Senior Engineer" .
<John_Smith> <reports_to> <Jane_Doe> .
<Acme_Corp> <headquarters> "San Francisco" .
<Acme_Corp> <founded> "2015" .

Schema: Predicate Management

Define and view predicate schemas:

# 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

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

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:

memvid state memory.mv2 --entity "John Smith"
# team: Infrastructure

Query the history:

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

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

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

memvid enrich memory.mv2 --engine claude --force

Performance Tuning

Parallel Workers

# 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

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

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

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

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

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

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

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

# Default: only enriches new frames
memvid enrich memory.mv2 --engine groq

4. Export for Integration

Use exports to integrate with other tools:

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

Check if frames have text content:
memvid stats memory.mv2

Try verbose mode to see extraction:

memvid enrich memory.mv2 --engine rules --verbose

Content may be too short or unstructured

”API rate limited”

Reduce workers and increase batch size:

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”

Check if entity appears in source:

memvid find memory.mv2 --query "Entity Name"

Force re-enrichment:

memvid enrich memory.mv2 --engine claude --force

​What Are Memory Cards?

​Memory Card Types

​Facts

​Preferences

​Events

​Relationships

​Profiles

​Enrichment Engines

​Rules Engine

​Candle Engine (Local LLM)

​Cloud Engines

​CLI Commands

​Enrich: Extract Memory Cards

​Memories: View Extracted Cards

​State: O(1) Entity Lookup

​Facts: Audit Fact History

​Export: Standard Formats

​Schema: Predicate Management

​SDK Usage

​Python

​Node.js

​Version Relations

​Deduplication

​Incremental Enrichment

​Performance Tuning

​Parallel Workers

​Batch Size

​Engine Selection by Use Case

​Use Cases

​Personal Knowledge Management

​Meeting Minutes

​Research Papers

​Customer Information

​Best Practices

​1. Choose the Right Engine

​2. Enrich After Bulk Imports

​3. Use Incremental Mode

​4. Export for Integration

​Troubleshooting

​”No memory cards extracted”

​”API rate limited”

​“Low confidence scores”

​”Missing expected entities”

​Next Steps

Graph Search

Deduplication

What Are Memory Cards?

Memory Card Types

Facts

Preferences

Events

Relationships

Profiles

Enrichment Engines

Rules Engine

Candle Engine (Local LLM)

Cloud Engines

CLI Commands

Enrich: Extract Memory Cards

Memories: View Extracted Cards

State: O(1) Entity Lookup

Facts: Audit Fact History

Export: Standard Formats

Schema: Predicate Management

SDK Usage

Python

Node.js

Version Relations

Deduplication

Incremental Enrichment

Performance Tuning

Parallel Workers

Batch Size

Engine Selection by Use Case

Use Cases

Personal Knowledge Management

Meeting Minutes

Research Papers

Customer Information

Best Practices

1. Choose the Right Engine

2. Enrich After Bulk Imports

3. Use Incremental Mode

4. Export for Integration

Troubleshooting

”No memory cards extracted”

”API rate limited”

“Low confidence scores”

”Missing expected entities”

Next Steps