API Reference

Complete reference for all MCP tools available in Recall.

Tools overview

Recall provides these tools to Claude Desktop through the MCP protocol:

Tool	Description	Response time
`add_memory`	Store new information	Under 10ms
`search_memory`	Find relevant memories	Under 5ms (cache)
`get_all_memories`	List all memories	Under 50ms
`update_memory`	Modify existing memory	Under 10ms
`delete_memory`	Remove a memory	Under 10ms
`delete_all_memories`	Clear all memories	Under 100ms
`get_memory_history`	View memory changes	Under 20ms
`cache_stats`	Get performance metrics	Under 1ms
`optimize_cache`	Reorganize cache	Under 500ms
`health_check`	Check system status	Under 5ms

add_memory

Store new information in the memory system.

Parameters

Parameter	Type	Required	Description
`content`	string	No*	Text content to remember
`messages`	array	No*	Conversation messages to remember
`user_id`	string	No	User identifier (default: from env)
`priority`	string	No	`critical`, `high`, `medium`, `low` (default: `medium`)
`metadata`	object	No	Additional context
`async`	boolean	No	Process in background (default: `true`)

*Either content or messages is required.

Example

JSON

1{
2  "tool": "add_memory",
3  "parameters": {
4    "content": "User prefers dark mode and 14px font size",
5    "priority": "high",
6    "metadata": {
7      "category": "preferences",
8      "updated": "2024-01-15"
9    }
10  }
11}

Response

JSON

1{
2  "memory_id": "mem_abc123xyz",
3  "message": "Memory added successfully",
4  "cached": true
5}

search_memory

Find memories using semantic search.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`user_id`	string	No	Filter by user
`limit`	number	No	Max results (default: 10)
`prefer_cache`	boolean	No	Skip cloud if in cache (default: `true`)
`metadata_filter`	object	No	Filter by metadata

Example

JSON

1{
2  "tool": "search_memory",
3  "parameters": {
4    "query": "user preferences for UI",
5    "limit": 5,
6    "metadata_filter": {
7      "category": "preferences"
8    }
9  }
10}

Response

JSON

1{
2  "results": [
3    {
4      "memory": "User prefers dark mode and 14px font size",
5      "metadata": {
6        "category": "preferences",
7        "updated": "2024-01-15"
8      },
9      "score": 0.92,
10      "id": "mem_abc123xyz",
11      "created_at": "2024-01-15T10:30:00Z",
12      "user_id": "default"
13    }
14  ],
15  "source": "cache"
16}

get_all_memories

Retrieve all memories for a user.

Parameters

Parameter	Type	Required	Description
`user_id`	string	No	User identifier (default: from env)

Example

JSON

1{
2  "tool": "get_all_memories",
3  "parameters": {
4    "user_id": "sarah_chen"
5  }
6}

Response

JSON

1{
2  "memories": [
3    {
4      "id": "mem_abc123xyz",
5      "memory": "User prefers dark mode",
6      "hash": "a1b2c3d4",
7      "metadata": null,
8      "created_at": "2024-01-15T10:30:00Z",
9      "updated_at": "2024-01-15T10:30:00Z",
10      "user_id": "sarah_chen"
11    }
12  ],
13  "source": "cache",
14  "count": 1
15}

update_memory

Modify an existing memory.

Parameters

Parameter	Type	Required	Description
`memory_id`	string	Yes	Memory ID to update
`content`	string	Yes	New content
`metadata`	object	No	New metadata

Example

JSON

1{
2  "tool": "update_memory",
3  "parameters": {
4    "memory_id": "mem_abc123xyz",
5    "content": "User strongly prefers dark mode",
6    "metadata": {
7      "emphasized": true
8    }
9  }
10}

Response

JSON

1{
2  "success": true,
3  "message": "Memory updated successfully"
4}

delete_memory

Remove a specific memory.

Parameters

Parameter	Type	Required	Description
`memory_id`	string	Yes	Memory ID to delete

Example

JSON

1{
2  "tool": "delete_memory",
3  "parameters": {
4    "memory_id": "mem_abc123xyz"
5  }
6}

Response

JSON

1{
2  "success": true,
3  "message": "Memory deleted successfully"
4}

delete_all_memories

Clear all memories for a user.

Parameters

Parameter	Type	Required	Description
`user_id`	string	No	User identifier (default: from env)

Example

JSON

1{
2  "tool": "delete_all_memories",
3  "parameters": {
4    "user_id": "sarah_chen"
5  }
6}

Response

JSON

1{
2  "deleted": 42,
3  "message": "Deleted 42 memories"
4}

get_memory_history

View the change history of a memory.

Parameters

Parameter	Type	Required	Description
`memory_id`	string	Yes	Memory ID

Example

JSON

1{
2  "tool": "get_memory_history",
3  "parameters": {
4    "memory_id": "mem_abc123xyz"
5  }
6}

Response

JSON

1{
2  "history": [
3    {
4      "version": 1,
5      "content": "User prefers dark mode",
6      "timestamp": "2024-01-15T10:30:00Z",
7      "action": "created"
8    },
9    {
10      "version": 2,
11      "content": "User strongly prefers dark mode",
12      "timestamp": "2024-01-15T11:00:00Z",
13      "action": "updated"
14    }
15  ],
16  "message": "Retrieved 2 history entries"
17}

cache_stats

Get cache performance metrics.

Parameters

None

Example

JSON

1{
2  "tool": "cache_stats",
3  "parameters": {}
4}

Response

JSON

1{
2  "hits": 1234,
3  "misses": 56,
4  "hit_rate": "95.7%",
5  "size": 789,
6  "max_size": 10000,
7  "memory_usage": "4.2MB",
8  "evictions": 12,
9  "avg_response_time": "3.2ms",
10  "connection_pool": {
11    "active": 2,
12    "idle": 8,
13    "waiting": 0
14  }
15}

optimize_cache

Reorganize cache based on access patterns.

Parameters

Parameter	Type	Required	Description
`force_refresh`	boolean	No	Force refresh all entries (default: `false`)
`max_memories`	number	No	Max memories to optimize (default: 1000)

Example

JSON

1{
2  "tool": "optimize_cache",
3  "parameters": {
4    "force_refresh": true,
5    "max_memories": 500
6  }
7}

Response

JSON

1{
2  "promoted": 45,
3  "demoted": 23,
4  "expired": 12,
5  "duration": "234ms",
6  "memory_freed": "1.2MB"
7}

health_check

Check system component status.

Parameters

None

Example

JSON

1{
2  "tool": "health_check",
3  "parameters": {}
4}

Response

JSON

1{
2  "redis": true,
3  "mem0": true,
4  "cache": {
5    "l1_size": 456,
6    "l2_size": 1234,
7    "hit_rate": "94.3%"
8  },
9  "uptime": "3d 14h 22m",
10  "memory": {
11    "used": "45.6MB",
12    "rss": "128MB"
13  }
14}

Error responses

All tools can return errors:

JSON

1{
2  "error": "Redis connection failed",
3  "code": "REDIS_CONNECTION_ERROR",
4  "details": {
5    "host": "localhost",
6    "port": 6379
7  }
8}

Common error codes:

Code	Description
`REDIS_CONNECTION_ERROR`	Can't connect to Redis
`MEM0_API_ERROR`	Mem0 API request failed
`INVALID_PARAMETERS`	Missing or invalid parameters
`MEMORY_NOT_FOUND`	Memory ID doesn't exist
`RATE_LIMIT_EXCEEDED`	Too many requests

Rate limits

Add operations: 100/minute
Search operations: 500/minute
Delete operations: 50/minute
Cache operations: No limit

Performance tips

Use priority levels - Mark important memories as high or critical
Enable async mode - For non-critical additions
Batch operations - Use messages array for conversations
Cache first - Set prefer_cache: true for searches
Optimize regularly - Run optimize_cache weekly