Client API | r3 Documentation

Complete reference for the RecallClient class and all available methods.

RecallClient

The main client class for interacting with Recall's hybrid memory system.

Constructor

// TypeScript
new RecallClient(options?: RecallClientOptions)
interface RecallClientOptions {
  redisUrl?: string;
  mem0ApiKey?: string;
  environment?: string;
  cacheConfig?: CacheConfig;
  syncConfig?: SyncConfig;
  [key: string]: any;
}

# Python
RecallClient(
    redis_url: str | None = None,
    mem0_api_key: str | None = None,
    environment: str = "development",
    cache_config: CacheConfig | None = None,
    sync_config: SyncConfig | None = None,
    **kwargs
)

Parameters

Parameter	Type	Default	Description
`redis_url`	`string`	`"redis://localhost:6379"`	Redis connection URL
`mem0_api_key`	`string`	`None`	Mem0 API key for cloud storage
`environment`	`string`	`"development"`	Environment name (development, staging, production)
`cache_config`	`CacheConfig`	`None`	Cache configuration options
`sync_config`	`SyncConfig`	`None`	Synchronization configuration

Example

from recall import RecallClient
# Basic initialization
client = RecallClient(
    redis_url="redis://localhost:6379",
    mem0_api_key="m0-xxxxxxxxxxxx"
)
# With configuration
client = RecallClient(
    redis_url="redis://localhost:6379",
    mem0_api_key="m0-xxxxxxxxxxxx",
    environment="production",
    cache_config=CacheConfig(ttl=3600),
    sync_config=SyncConfig(mode="eager")
)

import { RecallClient } from "@recall/client";
// Basic initialization
const client = new RecallClient({
  redisUrl: "redis://localhost:6379",
  mem0ApiKey: "m0-xxxxxxxxxxxx",
});
// With configuration
const client = new RecallClient({
  redisUrl: "redis://localhost:6379",
  mem0ApiKey: "m0-xxxxxxxxxxxx",
  environment: "production",
  cacheConfig: { ttl: 3600 },
  syncConfig: { mode: "eager" },
});

Core Methods

add()

Add a new memory to the system.

add(
    content: str,
    user_id: str,
    priority: str = "medium",
    metadata: dict | None = None,
    async_mode: bool = False
) -> dict

add(options: AddMemoryOptions): Promise<Memory>
interface AddMemoryOptions {
  content: string;
  userId: string;
  priority?: Priority;
  metadata?: Record<string, any>;
  asyncMode?: boolean;
}

Parameters

Parameter	Type	Required	Description
`content`	`string`	Yes	The memory content to store
`user_id`	`string`	Yes	User identifier
`priority`	`string`	No	Priority level: "critical", "high", "medium", "low"
`metadata`	`object`	No	Additional metadata
`async_mode`	`boolean`	No	If true, returns immediately without waiting for cloud sync

Returns

A dictionary/object containing:

id: Unique memory identifier
content: The stored content
user_id: Associated user ID
priority: Assigned priority level
created_at: Creation timestamp
metadata: Any additional metadata

Example

memory = client.add(
    content="User prefers dark theme",
    user_id="user_123",
    priority="high",
    metadata={
        "category": "preferences",
        "source": "settings_update"
    }
)
print(f"Memory ID: {memory['id']}")
# Output: Memory ID: mem_abc123xyz

const memory = await client.add({
  content: "User prefers dark theme",
  userId: "user_123",
  priority: "high",
  metadata: {
    category: "preferences",
    source: "settings_update",
  },
});
console.log(`Memory ID: ${memory.id}`);
// Output: Memory ID: mem_abc123xyz

search()

Search for relevant memories using semantic search.

search(
    query: str,
    user_id: str | None = None,
    limit: int = 10,
    filters: dict | None = None,
    threshold: float = 0.0
) -> list[dict]

search(options: SearchOptions): Promise<Memory[]>
interface SearchOptions {
  query: string;
  userId?: string;
  limit?: number;
  filters?: Record<string, any>;
  threshold?: number;
}

Parameters

Parameter	Type	Required	Description
`query`	`string`	Yes	Search query
`user_id`	`string`	No	Filter by user ID
`limit`	`integer`	No	Maximum results to return (default: 10)
`filters`	`object`	No	Metadata filters
`threshold`	`float`	No	Minimum relevance score (0.0 to 1.0)

Returns

Array of memory objects, each containing:

All memory fields
score: Relevance score (0.0 to 1.0)
source: Whether from "cache" or "cloud"

Example

results = client.search(
    query="user preferences for UI",
    user_id="user_123",
    limit=5,
    filters={"category": "preferences"},
    threshold=0.7
)
for memory in results:
    print(f"{memory['content']} (score: {memory['score']:.2f})")

const results = await client.search({
  query: "user preferences for UI",
  userId: "user_123",
  limit: 5,
  filters: { category: "preferences" },
  threshold: 0.7,
});
results.forEach((memory) => {
  console.log(`${memory.content} (score: ${memory.score.toFixed(2)})`);
});

get()

Retrieve a specific memory by ID.

get(memory_id: str) -> dict | None

get(memoryId: string): Promise<Memory | null>

Example

memory = client.get("mem_abc123xyz")
if memory:
    print(f"Content: {memory['content']}")
else:
    print("Memory not found")

const memory = await client.get("mem_abc123xyz");
if (memory) {
  console.log(`Content: ${memory.content}`);
} else {
  console.log("Memory not found");
}

update()

Update an existing memory.

update(
    memory_id: str,
    content: str | None = None,
    priority: str | None = None,
    metadata: dict | None = None
) -> dict

update(options: UpdateOptions): Promise<Memory>
interface UpdateOptions {
  memoryId: string;
  content?: string;
  priority?: Priority;
  metadata?: Record<string, any>;
}

Example

updated = client.update(
    memory_id="mem_abc123xyz",
    priority="critical",
    metadata={"last_accessed": datetime.now().isoformat()}
)

const updated = await client.update({
  memoryId: "mem_abc123xyz",
  priority: "critical",
  metadata: { lastAccessed: new Date().toISOString() },
});

delete()

Delete a memory from both cache and cloud storage.

delete(memory_id: str) -> bool

delete(memoryId: string): Promise<boolean>

Example

success = client.delete("mem_abc123xyz")
print(f"Deleted: {success}")

const success = await client.delete("mem_abc123xyz");
console.log(`Deleted: ${success}`);

get_all()

Retrieve all memories for a user.

get_all(
    user_id: str,
    limit: int | None = None,
    offset: int = 0
) -> list[dict]

getAll(options: GetAllOptions): Promise<Memory[]>
interface GetAllOptions {
  userId: string;
  limit?: number;
  offset?: number;
}

Example

memories = client.get_all(
    user_id="user_123",
    limit=100,
    offset=0
)
print(f"Total memories: {len(memories)}")

const memories = await client.getAll({
  userId: "user_123",
  limit: 100,
  offset: 0,
});
console.log(`Total memories: ${memories.length}`);

Batch Operations

add_batch()

Add multiple memories in a single operation.

add_batch(memories: list[dict]) -> list[dict]

addBatch(memories: AddMemoryOptions[]): Promise<Memory[]>

Example

memories = [
    {
        "content": "Prefers email notifications",
        "user_id": "user_123",
        "priority": "high"
    },
    {
        "content": "Works in tech industry",
        "user_id": "user_123",
        "priority": "medium"
    }
]
results = client.add_batch(memories)
print(f"Added {len(results)} memories")

const memories = [
  {
    content: "Prefers email notifications",
    userId: "user_123",
    priority: "high",
  },
  {
    content: "Works in tech industry",
    userId: "user_123",
    priority: "medium",
  },
];
const results = await client.addBatch(memories);
console.log(`Added ${results.length} memories`);

delete_batch()

Delete multiple memories by ID.

delete_batch(memory_ids: list[str]) -> dict

deleteBatch(memoryIds: string[]): Promise<BatchDeleteResult>

Cache Management

cache_stats()

Get detailed cache statistics.

cache_stats() -> dict

cacheStats(): Promise<CacheStats>

Returns

{
    "size": 1234,           # Number of cached items
    "memory_usage": "45.6MB", # Memory used
    "hit_rate": 0.92,       # Cache hit rate
    "miss_rate": 0.08,      # Cache miss rate
    "evictions": 156,       # Number of evictions
    "avg_ttl": 3600,        # Average TTL in seconds
    "by_priority": {
        "critical": 10,
        "high": 234,
        "medium": 567,
        "low": 423
    }
}

interface CacheStats {
  size: number;
  memoryUsage: string;
  hitRate: number;
  missRate: number;
  evictions: number;
  avgTtl: number;
  byPriority: {
    critical: number;
    high: number;
    medium: number;
    low: number;
  };
}

optimize_cache()

Optimize cache by removing stale entries and reorganizing based on access patterns.

optimize_cache(
    aggressive: bool = False
) -> dict

optimizeCache(options?: OptimizeOptions): Promise<OptimizeResult>

clear_cache()

Clear cache for specific user or entirely.

clear_cache(user_id: str | None = None) -> bool

clearCache(userId?: string): Promise<boolean>

Synchronization

sync()

Manually trigger synchronization between cache and cloud.

sync(
    direction: str = "bidirectional",
    force: bool = False
) -> dict

sync(options?: SyncOptions): Promise<SyncResult>
interface SyncOptions {
  direction?: "bidirectional" | "to_cloud" | "from_cloud";
  force?: boolean;
}

Health & Monitoring

health_check()

Check the health status of all components.

health_check() -> dict

healthCheck(): Promise<HealthStatus>

Returns

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z",
    "components": {
        "redis": {
            "status": "healthy",
            "latency_ms": 1.2,
            "version": "7.0.5"
        },
        "mem0": {
            "status": "healthy",
            "latency_ms": 45.3,
            "quota_used": 0.23
        },
        "cache": {
            "status": "healthy",
            "size": 1234,
            "memory_usage": "45.6MB"
        }
    },
    "version": "1.0.0"
}

interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  timestamp: string;
  components: {
    redis: ComponentHealth;
    mem0: ComponentHealth;
    cache: ComponentHealth;
  };
  version: string;
}

Configuration Classes

CacheConfig

class CacheConfig:
    ttl: int | dict[str, int | None] = 3600
    max_memory: str = "512mb"
    eviction_policy: str = "allkeys-lru"
    compression: bool = False
    warm_cache: bool = True

interface CacheConfig {
  ttl?: number | Record<Priority, number | null>;
  maxMemory?: string;
  evictionPolicy?: string;
  compression?: boolean;
  warmCache?: boolean;
}

SyncConfig

class SyncConfig:
    mode: str = "lazy"  # lazy, eager, manual
    batch_size: int = 100
    interval: int = 60
    retry_policy: str = "exponential"
    max_retries: int = 3

interface SyncConfig {
  mode?: "lazy" | "eager" | "manual";
  batchSize?: number;
  interval?: number;
  retryPolicy?: string;
  maxRetries?: number;
}

Error Handling

Exception Types

from recall.exceptions import (
    RecallError,           # Base exception
    ConnectionError,       # Redis/Mem0 connection issues
    AuthenticationError,   # Invalid API key
    ValidationError,       # Invalid parameters
    CacheError,           # Cache-specific errors
    SyncError,            # Synchronization errors
    RateLimitError        # API rate limiting
)
try:
    client.add(content="", user_id="")
except ValidationError as e:
    print(f"Invalid input: {e}")
except RecallError as e:
    print(f"Recall error: {e}")

import {
  RecallError,
  ConnectionError,
  AuthenticationError,
  ValidationError,
  CacheError,
  SyncError,
  RateLimitError,
} from "@recall/client";
try {
  await client.add({ content: "", userId: "" });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(`Invalid input: ${error.message}`);
  } else if (error instanceof RecallError) {
    console.log(`Recall error: ${error.message}`);
  }
}

Async Support

Async Client (Python)

from recall import AsyncRecallClient
import asyncio
async def main():
    client = AsyncRecallClient(
        redis_url="redis://localhost:6379",
        mem0_api_key="your-api-key"
    )
    # Async methods
    memory = await client.add(
        content="Async memory",
        user_id="user_123"
    )
    results = await client.search(
        query="async operations",
        user_id="user_123"
    )
    # Concurrent operations
    tasks = [
        client.add(content=f"Memory {i}", user_id="user_123")
        for i in range(10)
    ]
    memories = await asyncio.gather(*tasks)
asyncio.run(main())

Next Steps

Explore advanced features
Learn about webhooks and events
Review best practices
Check SDK references for language-specific details