Documentation

Learn how to integrate Erised visual memory into your applications.

Quick Start

Get up and running with Erised in under 5 minutes. This guide will show you how to add images to memory and search them using natural language.

1. Install the SDK

pip install git+https://github.com/exla-ai/erised.git

2. Add an image to memory

from erised import ErisedClient

client = ErisedClient(api_key="your-api-key")

# Add an image to memory
# You can pass a file path, URL, or raw image bytes
result = client.add(
    image="screenshot.png",
    user_id="user123",
    metadata={"app": "vscode", "action": "editing"}
)

print(f"Memory ID: {result['memory_id']}")

3. Search by natural language

results = client.search(
    "code editor with dark theme",
    user_id="user123"
)

for r in results["results"]:
    print(f"{r['memory_id']}: {r['score']:.2f}")

4. Get the image back

# Get image bytes
image_bytes = client.get_image(memory_id="abc-123")

# Save to file
with open("retrieved.png", "wb") as f:
    f.write(image_bytes)

# Or get the full URL
url = client.get_image_url(memory_id="abc-123")
print(url)  # Requires auth header to access

Output example: Search returns results with similarity scores (typically 5-15, higher is better) and image_url for each match.

Installation

Python SDK

Install the Erised Python client using pip:

bash

pip install git+https://github.com/exla-ai/erised.git

Environment Variables

Set your API key as an environment variable (optional):

bash

export ERISED_API_KEY="your-api-key"

API Reference

ErisedClient

Initialize the client with your API key:

python

from erised import ErisedClient

client = ErisedClient(
    api_key="your-api-key",           # Required
)

Tip: The default timeout is 120 seconds to accommodate model inference time. Cold starts may take 20-30 seconds.

Add Memory

Add an image to visual memory. The image is processed through state-of-the-art models to generate semantic embeddings.

python

result = client.add(
    image="path/to/image.png",    # Path, bytes, or file-like object
    user_id="user123",            # Required - for memory isolation
    metadata={"key": "value"},    # Optional custom metadata
    memory_id="custom-id"         # Optional custom ID
)

# Response
{
    "memory_id": "abc-123-def",
    "message": "Memory added successfully"
}

Supported Image Types

PNG, JPEG, GIF, WebP
File path (string or Path object)
Raw bytes
File-like object with read() method

Search

Search your visual memories using natural language queries. Results are ranked by semantic similarity.

python

results = client.search(
    query="terminal with error message",  # Natural language query
    user_id="user123",                     # Filter by user
    filters={"app": "vscode"},             # Additional filters
    top_k=10,                              # Max results
    score_threshold=5.0                    # Min similarity score
)

# Response
{
    "results": [
        {
            "memory_id": "abc-123",
            "user_id": "user123",
            "timestamp": "2025-12-06T...",
            "image_url": "/v1/images/user123/abc-123.png",
            "score": 8.75,
            "metadata": {"app": "vscode"}
        },
        ...
    ]
}

Understanding Scores

Scores typically range from 5-15, with higher being more relevant. A score above 7 usually indicates a strong semantic match.

List Memories

List all memories, optionally filtered by user.

python

memories = client.list(
    user_id="user123",   # Optional filter
    limit=100,           # Max results
    offset=0             # Pagination offset
)

# Response
{
    "memories": [...],
    "total": 42,
    "limit": 100,
    "offset": 0
}

Get Memory

Retrieve a specific memory by ID.

python

memory = client.get(memory_id="abc-123")

# Response
{
    "memory_id": "abc-123",
    "user_id": "user123",
    "timestamp": "2025-12-06T...",
    "image_url": "/v1/images/user123/abc-123.png",
    "metadata": {...}
}

Delete Memory

Delete a memory by ID. This removes both the image and its embeddings.

python

result = client.delete(memory_id="abc-123")

# Response
{
    "message": "Deleted abc-123"
}

cURL Examples

Use the API directly with cURL for testing or non-Python environments.

Add Memory

bash

curl -X POST https://viraat--erised-erisedapi-serve.modal.run/v1/memories/add \
  -H "Authorization: Bearer $ERISED_API_KEY" \
  -F "file=@screenshot.png" \
  -F "user_id=user123" \
  -F 'metadata={"app": "vscode"}'

Search Memories

bash

curl -X POST https://viraat--erised-erisedapi-serve.modal.run/v1/memories/search \
  -H "Authorization: Bearer $ERISED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "code editor with dark theme",
    "filters": {"user_id": "user123"},
    "top_k": 10
  }'

List Memories

bash

curl https://viraat--erised-erisedapi-serve.modal.run/v1/memories?user_id=user123 \
  -H "Authorization: Bearer $ERISED_API_KEY"

Delete Memory

bash

curl -X DELETE https://viraat--erised-erisedapi-serve.modal.run/v1/memories/abc-123 \
  -H "Authorization: Bearer $ERISED_API_KEY"

API Endpoint

Base URLhttps://viraat--erised-erisedapi-serve.modal.run

AuthBearer token in Authorization header