Client API Reference

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
1
2
3
4
5
6
7
8
9
10
11
// TypeScript
new RecallClient(options?: RecallClientOptions)
​
interface RecallClientOptions {
  redisUrl?: string;
  mem0ApiKey?: string;
  environment?: string;
  cacheConfig?: CacheConfig;
  syncConfig?: SyncConfig;
  [key: string]: any;
}

python
1
2
3
4
5
6
7
8
9
# 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

Example

python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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")
)

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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.

python
1
2
3
4
5
6
7
add(
    content: str,
    user_id: str,
    priority: str = "medium",
    metadata: dict | None = None,
    async_mode: bool = False
) -> dict

typescript
1
2
3
4
5
6
7
8
9
add(options: AddMemoryOptions): Promise<Memory>
​
interface AddMemoryOptions {
  content: string;
  userId: string;
  priority?: Priority;
  metadata?: Record<string, any>;
  asyncMode?: boolean;
}

Parameters

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

python
1
2
3
4
5
6
7
8
9
10
11
12
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

typescript
1
2
3
4
5
6
7
8
9
10
11
12
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.

python
1
2
3
4
5
6
7
search(
    query: str,
    user_id: str | None = None,
    limit: int = 10,
    filters: dict | None = None,
    threshold: float = 0.0
) -> list[dict]

typescript
1
2
3
4
5
6
7
8
9
search(options: SearchOptions): Promise<Memory[]>
​
interface SearchOptions {
  query: string;
  userId?: string;
  limit?: number;
  filters?: Record<string, any>;
  threshold?: number;
}

Parameters

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

python
1
2
3
4
5
6
7
8
9
10
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})")

typescript
1
2
3
4
5
6
7
8
9
10
11
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.

python
1
get(memory_id: str) -> dict | None

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

Example

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

typescript
1
2
3
4
5
6
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.

python
1
2
3
4
5
6
update(
    memory_id: str,
    content: str | None = None,
    priority: str | None = None,
    metadata: dict | None = None
) -> dict

typescript
1
2
3
4
5
6
7
8
update(options: UpdateOptions): Promise<Memory>
​
interface UpdateOptions {
  memoryId: string;
  content?: string;
  priority?: Priority;
  metadata?: Record<string, any>;
}

Example

python
1
2
3
4
5
updated = client.update(
    memory_id="mem_abc123xyz",
    priority="critical",
    metadata={"last_accessed": datetime.now().isoformat()}
)

typescript
1
2
3
4
5
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.

python
1
delete(memory_id: str) -> bool

typescript
1
delete(memoryId: string): Promise<boolean>

Example

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

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

get_all()

Retrieve all memories for a user.

python
1
2
3
4
5
get_all(
    user_id: str,
    limit: int | None = None,
    offset: int = 0
) -> list[dict]

typescript
1
2
3
4
5
6
7
getAll(options: GetAllOptions): Promise<Memory[]>
​
interface GetAllOptions {
  userId: string;
  limit?: number;
  offset?: number;
}

Example

python
1
2
3
4
5
6
memories = client.get_all(
    user_id="user_123",
    limit=100,
    offset=0
)
print(f"Total memories: {len(memories)}")

typescript
1
2
3
4
5
6
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.

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

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

Example

python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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")

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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.

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

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

Cache Management

cache_stats()

Get detailed cache statistics.

python
1
cache_stats() -> dict

typescript
1
cacheStats(): Promise<CacheStats>

Returns

python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "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
    }
}

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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.

python
1
2
3
optimize_cache(
    aggressive: bool = False
) -> dict

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

clear_cache()

Clear cache for specific user or entirely.

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

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

Synchronization

sync()

Manually trigger synchronization between cache and cloud.

python
1
2
3
4
sync(
    direction: str = "bidirectional",
    force: bool = False
) -> dict

typescript
1
2
3
4
5
6
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.

python
1
health_check() -> dict

typescript
1
healthCheck(): Promise<HealthStatus>

Returns

python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "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"
}

typescript
1
2
3
4
5
6
7
8
9
10
interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  timestamp: string;
  components: {
    redis: ComponentHealth;
    mem0: ComponentHealth;
    cache: ComponentHealth;
  };
  version: string;
}

Configuration Classes

CacheConfig

python
1
2
3
4
5
6
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

typescript
1
2
3
4
5
6
7
interface CacheConfig {
  ttl?: number | Record<Priority, number | null>;
  maxMemory?: string;
  evictionPolicy?: string;
  compression?: boolean;
  warmCache?: boolean;
}

SyncConfig

python
1
2
3
4
5
6
class SyncConfig:
    mode: str = "lazy"  # lazy, eager, manual
    batch_size: int = 100
    interval: int = 60
    retry_policy: str = "exponential"
    max_retries: int = 3

typescript
1
2
3
4
5
6
7
interface SyncConfig {
  mode?: "lazy" | "eager" | "manual";
  batchSize?: number;
  interval?: number;
  retryPolicy?: string;
  maxRetries?: number;
}

Error Handling

Exception Types

python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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}")

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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)

python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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