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 erised

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 erised

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 ColQwen2.5 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://api.erised.exla.ai/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://api.erised.exla.ai/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://api.erised.exla.ai/v1/memories?user_id=user123 \
  -H "Authorization: Bearer $ERISED_API_KEY"

Delete Memory

bash

curl -X DELETE https://api.erised.exla.ai/v1/memories/abc-123 \
  -H "Authorization: Bearer $ERISED_API_KEY"

API Endpoint

Base URLhttps://api.erised.exla.ai

AuthBearer token in Authorization header