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

# Python SDK

> Build AI applications with persistent memory in Python

The Python SDK provides a simple, Pythonic interface for working with Memvid memory files.

## Installation

```bash theme={null}
pip install memvid-sdk
```

<Info>
  **Requirements:** Python 3.8+, macOS/Linux/Windows. Native bindings included.
</Info>

## Quick Start

```python theme={null}
import memvid_sdk as memvid
import os

# Create a new memory file
mem = memvid.create('knowledge.mv2')

# Add documents
mem.put(
    title='Meeting Notes',
    label='notes',
    metadata={'source': 'slack'},
    text='Alice mentioned she works at Anthropic...',
    enable_embedding=True
)

# Search
results = mem.find('who works at AI companies?')
print(results['hits'])

# Ask questions with AI
answer = mem.ask(
    'What does Alice do?',
    model='gpt-4o-mini',
    api_key=os.environ['OPENAI_API_KEY']
)
print(answer['text'])

# Close when done
mem.close()
```

## Context Manager

```python theme={null}
import memvid_sdk as memvid

# Automatically closes when done
with memvid.use('basic', 'memory.mv2') as mem:
    mem.put(title='Doc', label='test', metadata={}, text='Content')
    results = mem.find('query')
```

## API Reference

| Category             | Methods                                                                          | Description                      |
| -------------------- | -------------------------------------------------------------------------------- | -------------------------------- |
| **File Operations**  | `create`, `use`, `close`                                                         | Create, open, close memory files |
| **Data Ingestion**   | `put`, `put_many`                                                                | Add documents with embeddings    |
| **Search**           | `find`, `ask`, `timeline`                                                        | Query your memory                |
| **Memory Cards**     | `memories`, `state`, `enrich`, `add_memory_cards`                                | Structured fact extraction       |
| **Tables**           | `put_pdf_tables`, `list_tables`, `get_table`                                     | PDF table extraction             |
| **Sessions**         | `session_start`, `session_end`, `session_replay`                                 | Time-travel debugging            |
| **Tickets**          | `sync_tickets`, `current_ticket`, `get_capacity`                                 | Capacity management              |
| **Cloud Management** | `configure`, `create_project`, `list_projects`, `create_memory`, `list_memories` | Dashboard API                    |
| **Utilities**        | `verify`, `doctor`, `mask_pii`                                                   | Maintenance and utilities        |

## Framework Adapters

```python theme={null}
# LangChain
mem = memvid.use('langchain', 'knowledge.mv2')
retriever = mem.as_retriever()

# LlamaIndex
mem = memvid.use('llamaindex', 'knowledge.mv2')
query_engine = mem.as_query_engine()

# CrewAI
mem = memvid.use('crewai', 'knowledge.mv2')
tools = mem.tools

# AutoGen
mem = memvid.use('autogen', 'knowledge.mv2')

# Haystack
mem = memvid.use('haystack', 'knowledge.mv2')
```

## Embedding Providers

```python theme={null}
from memvid_sdk.embeddings import (
    OpenAIEmbeddings,
    GeminiEmbeddings,
    MistralEmbeddings,
    CohereEmbeddings,
    VoyageEmbeddings,
    NvidiaEmbeddings,
    LOCAL_EMBEDDING_MODELS
)
import os

# OpenAI
openai = OpenAIEmbeddings(api_key=os.environ['OPENAI_API_KEY'])

# Gemini
gemini = GeminiEmbeddings(api_key=os.environ['GEMINI_API_KEY'])

# Mistral
mistral = MistralEmbeddings(api_key=os.environ['MISTRAL_API_KEY'])

# Local models (no API required)
mem.put(
    title='Doc',
    label='test',
    metadata={},
    text='Content',
    enable_embedding=True,
    embedding_model=LOCAL_EMBEDDING_MODELS['BGE_SMALL']
)
```

**Local Embedding Models:**

| Model       | Dimensions | Speed   | Quality |
| ----------- | ---------- | ------- | ------- |
| `BGE_SMALL` | 384        | Fastest | Good    |
| `BGE_BASE`  | 768        | Fast    | Better  |
| `NOMIC`     | 768        | Fast    | Better  |
| `GTE_LARGE` | 1024       | Slower  | Best    |

## Entity Extraction

```python theme={null}
# Extract facts using rules engine
result = mem.enrich('rules')

# View extracted cards
cards = mem.memories()
print(f"Extracted {cards['count']} memory cards")

# Get entity state (O(1) lookup)
alice = mem.state('Alice')
print(alice['slots'])
# {'employer': 'Anthropic', 'role': 'Engineer'}

# Add memory cards manually
mem.add_memory_cards([
    {'entity': 'Alice', 'slot': 'employer', 'value': 'Anthropic'},
    {'entity': 'Bob', 'slot': 'team', 'value': 'Infrastructure'}
])
```

## Session Recording

Record and replay agent sessions to debug RAG failures:

```python theme={null}
# Start recording session
session_id = mem.session_start("Debug Session")

# Perform operations (all recorded)
mem.put(title="Meeting Notes", label="notes", metadata={}, text="Discussed Q4...")
results = mem.find("roadmap", k=5)

# Add checkpoints at key moments
mem.session_checkpoint()

# End session
summary = mem.session_end()
print(f"Recorded {summary['action_count']} actions")

# Replay with different parameters
replay_result = mem.session_replay(
    session_id,
    adaptive=True,
    top_k=20
)
print(f"Match rate: {replay_result['match_rate']:.1%}")

# Delete session when done
mem.session_delete(session_id)
```

## Error Handling

```python theme={null}
from memvid_sdk import (
    CapacityExceededError,
    LockedError,
    VecDimensionMismatchError,
    EmbeddingFailedError,
    MemvidError
)

try:
    mem.put(title='Doc', label='test', metadata={}, text='Content')
except CapacityExceededError:
    print('Storage limit reached')
except LockedError:
    print('File locked by another process')
except VecDimensionMismatchError:
    print('Embedding dimension mismatch')
except EmbeddingFailedError:
    print('Embedding generation failed')
except MemvidError as e:
    print(f'Error [{e.code}]: {e.message}')
```

| Error Class                 | Code  | Description                    |
| --------------------------- | ----- | ------------------------------ |
| `CapacityExceededError`     | MV001 | Storage limit reached          |
| `TicketInvalidError`        | MV002 | Invalid ticket signature       |
| `LexIndexDisabledError`     | MV004 | Lexical search not enabled     |
| `LockedError`               | MV007 | File locked by another process |
| `FrameNotFoundError`        | MV010 | Requested frame doesn't exist  |
| `VecIndexDisabledError`     | MV011 | Vector search not enabled      |
| `VecDimensionMismatchError` | MV014 | Wrong embedding dimension      |
| `EmbeddingFailedError`      | MV015 | Embedding generation failed    |

See [Error Reference](/errors/reference) for complete documentation.

## Environment Variables

| Variable            | Description            |
| ------------------- | ---------------------- |
| `MEMVID_API_KEY`    | Dashboard API key      |
| `OPENAI_API_KEY`    | OpenAI API key         |
| `GEMINI_API_KEY`    | Google Gemini API key  |
| `MISTRAL_API_KEY`   | Mistral AI API key     |
| `ANTHROPIC_API_KEY` | Anthropic API key      |
| `COHERE_API_KEY`    | Cohere API key         |
| `VOYAGE_API_KEY`    | Voyage AI API key      |
| `NVIDIA_API_KEY`    | NVIDIA API key         |
| `MEMVID_MODELS_DIR` | Model cache directory  |
| `MEMVID_OFFLINE`    | Use cached models only |

## Type Hints

The SDK includes full type hints for IDE support:

```python theme={null}
from typing import Dict, Any

def process_memory(path: str) -> Dict[str, Any]:
    mem = memvid.use('basic', path)
    results: Dict[str, Any] = mem.find('query')
    return results
```

## SDK Reference

<CardGroup cols={2}>
  <Card title="Overview" icon="book" href="/python-sdk/overview">
    Complete API reference with all methods
  </Card>

  <Card title="Querying" icon="magnifying-glass" href="/python-sdk/querying">
    Search modes, filters, and retrieval patterns
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK Recipes" icon="flask" href="/quickstart/sdk-recipes">
    Common patterns and recipes
  </Card>

  <Card title="Framework Integrations" icon="puzzle-piece" href="/frameworks/overview">
    LangChain, LlamaIndex, and more
  </Card>
</CardGroup>