API Reference

MCP tools available in r3.

Tools overview

r3 provides these tools to Antigravity CLI through the MCP protocol:

add_memory

Store new information in the memory system.

Parameters

*Either content or messages is required.

Example

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

Response

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

search_memory

Find memories using semantic search.

Parameters

Example

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

Response

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

get_all_memories

Retrieve all memories for a user.

Parameters

Example

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

Response

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

update_memory

Modify an existing memory.

Parameters

Example

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

Response

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

delete_memory

Remove a specific memory.

Parameters

Example

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

Response

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

delete_all_memories

Clear all memories for a user.

Parameters

Example

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

Response

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

get_memory_history

View the change history of a memory.

Parameters

Example

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

Response

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

cache_stats

Get cache performance metrics.

Parameters

None

Example

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

Response

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

optimize_cache

Reorganize cache based on access patterns.

Parameters

Example

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

Response

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

health_check

Check system component status.

Parameters

None

Example

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

Response

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

Error responses

All tools can return errors:

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

Common error codes:

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